> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Process payins via API

> Deliver stablecoin from your Circle Mint balance to a DFNS wallet via the API: register a recipient, create payins, and track on-chain delivery.

export const Get = props => {
  return <code style={{
    paddingLeft: 0,
    paddingTop: 0
  }}>
      <Badge color="green" size="sm">GET</Badge>
      <span style={{
    marginLeft: '0.5em'
  }}>{props.children}</span>
    </code>;
};

export const Post = props => {
  return <code style={{
    paddingLeft: 0,
    paddingTop: 0
  }}>
      <Badge color="blue" size="sm">POST</Badge>
      <span style={{
    marginLeft: '0.5em'
  }}>{props.children}</span>
    </code>;
};

This guide covers the API flow for on-ramping — delivering stablecoin from your provider balance to a DFNS wallet — using [Payins](/features/fiat-on-off-ramps).

## Prerequisites

* Circle Mint enabled for your organization, with provider credentials configured (see [dashboard setup](/guides/payins#connect-circle-mint))
* A destination wallet on a [supported network](/features/fiat-on-off-ramps)
* `Payins:Create` and `Payins:Read` [permissions](/core-concepts/roles-and-permissions)
* An organization user or service account — delegated end users cannot create payins

## Payin lifecycle

<Steps>
  <Step title="Register a recipient">
    <Post>/payins/recipients</Post> : [Register payin recipient](/api-reference/payins/register-payin-recipient)

    Register a wallet's address as a payin recipient with the provider before delivering funds to it.

    ```json Request theme={null}
    POST /payins/recipients

    {
      "provider": "CircleMint",
      "walletId": "wa-5pfuu-9euek-h0odgb6snva8ph3k",
      "currency": "USD"
    }
    ```

    ```json Response theme={null}
    {
      "provider": "CircleMint",
      "walletId": "wa-5pfuu-9euek-h0odgb6snva8ph3k",
      "currency": "USD",
      "status": "PendingVerification"
    }
    ```

    The registration must be approved on the provider's side — for Circle Mint, by an administrator in the Mint Console — before payins to that wallet can be created.
  </Step>

  <Step title="Wait for the recipient to be approved">
    <Get>/payins/recipients</Get> : [Get payin recipient](/api-reference/payins/get-payin-recipient)

    Check the recipient's status until it is `Active`. Pass the `provider`, `walletId`, and `currency` as query parameters.

    ```json Request theme={null}
    GET /payins/recipients?provider=CircleMint&walletId=wa-5pfuu-9euek-h0odgb6snva8ph3k&currency=USD
    ```

    Recipient status values:

    | Status                | Meaning                                                      |
    | --------------------- | ------------------------------------------------------------ |
    | `NotRegistered`       | The wallet's address is not registered with the provider     |
    | `PendingVerification` | Registered, awaiting provider approval (Circle Mint Console) |
    | `Active`              | Approved — payins to this wallet can be created              |
  </Step>

  <Step title="Create a payin">
    <Post>/payins</Post> : [Create payin](/api-reference/payins/create-payin)

    Deliver stablecoin from your provider balance to the wallet on-chain. The `currency` determines the delivered stablecoin (for example, `USD` delivers USDC).

    ```json Request theme={null}
    POST /payins

    {
      "walletId": "wa-5pfuu-9euek-h0odgb6snva8ph3k",
      "amount": "100.00",
      "provider": "CircleMint",
      "currency": "USD"
    }
    ```

    ```json Response theme={null}
    {
      "id": "payin-59t9u-eng2t-dd9p5nm02uc81sto",
      "walletId": "wa-5pfuu-9euek-h0odgb6snva8ph3k",
      "amount": "100.00",
      "currency": "USD",
      "network": "Ethereum",
      "status": "Processing",
      "provider": "CircleMint",
      "dateCreated": "2023-04-14T20:41:28.715Z",
      "data": {
        "executionStatus": "Initializing"
      }
    }
    ```

    The `amount` is expressed in currency units (for example, `"100.00"`), not minimum denomination.
  </Step>

  <Step title="Track the payin">
    <Get>/payins/\{payinId}</Get> : [Get payin status](/api-reference/payins/get-payin-status)

    Poll the payin to follow its progress. The response carries both the top-level `status` and the granular `data.executionStatus`, along with the delivery `transactionHash` once the transfer is on chain.

    ```json Request theme={null}
    GET /payins/{payinId}
    ```
  </Step>
</Steps>

## Payin statuses

The top-level `status` values are:

| Status       | Meaning                                                  |
| ------------ | -------------------------------------------------------- |
| `Processing` | The payin is active — funds are being delivered on-chain |
| `Completed`  | Stablecoin has been delivered to the wallet              |
| `Failed`     | Non-recoverable error                                    |

The provider-specific `data.executionStatus` (Circle Mint) refines this: `Initializing`, `AwaitingTransfer`, `Completed`, `Failed`. On failure, `data.reason` explains why.

## Check provider balances

<Get>/payins/balances</Get> : [List payin balances](/api-reference/payins/list-payin-balances)

Retrieve your available balance at the provider, one entry per currency. Pass the `provider` as a query parameter.

```json Request theme={null}
GET /payins/balances?provider=CircleMint
```

```json Response theme={null}
{
  "items": [
    {
      "provider": "CircleMint",
      "currency": "USD",
      "amount": "408.82"
    }
  ]
}
```

## List payins

<Get>/payins</Get> : [List payins](/api-reference/payins/list-payins)

List your payins to reconcile deliveries:

```json Request theme={null}
GET /payins
```