> ## 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 to a DFNS wallet via the API with Circle Mint or Borderless: register recipients, request quotes, create payins, and track on-chain delivery.
export const Get = props => {
return
GET
{props.children}
;
};
export const Post = props => {
return
POST
{props.children}
;
};
This guide covers the API flow for on-ramping — delivering stablecoin to a DFNS wallet — using [Payins](/features/fiat-on-off-ramps). Two providers are supported:
* **[Circle Mint payins](#circle-mint-payins)** — deliver stablecoin from your Circle Mint balance.
* **[Borderless payins](#borderless-payins)** — on-ramp from fiat; the payer funds a Wire, ACH, or SEPA deposit and Borderless delivers the stablecoin on-chain.
## Circle Mint payins
Deliver stablecoin from your Circle Mint balance to a registered recipient wallet.
### 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
/payins/recipients : [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.
/payins/recipients : [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¤cy=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 |
/payins : [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.
/payins/\{payinId} : [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}
```
## 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.
## Borderless payins
[Borderless](https://www.borderless.xyz) is a fiat on-ramp: rather than delivering from a stablecoin balance you already hold, the payer funds a fiat deposit (Wire, ACH, or SEPA) and Borderless delivers the stablecoin on-chain to your wallet. The flow is quote-based — lock a rate, create the payin, then hand the payer the deposit instructions Borderless returns.
### Prerequisites
* A [Borderless](https://www.borderless.xyz) account with completed KYB, and an account set up in the Borderless dashboard
* `Payins:Create` and `Payins:Read` [permissions](/core-concepts/roles-and-permissions)
* An organization user or service account — delegated end users cannot create payins
/payins/options : [List payin options](/api-reference/payins/list-payin-options)
List the assets Borderless can deliver and the fiat currency, payment-method, and country combinations its active institutions currently cover. Pass `provider=Borderless`.
```json Request theme={null}
GET /payins/options?provider=Borderless
```
/payins/accounts : [List payin accounts](/api-reference/payins/list-payin-accounts)
/payins/accounts/assets : [Register payin account asset](/api-reference/payins/register-payin-account-asset)
List your Borderless accounts and the wallet addresses registered per asset. An account is created in the Borderless dashboard. If the destination wallet's address is not yet registered for the asset you want delivered, register it — this is required before Borderless can deliver to the wallet.
```json Request theme={null}
GET /payins/accounts?provider=Borderless
```
/payins/quote : [Request payin quote](/api-reference/payins/request-payin-quote)
Request an executable quote for the delivery. The response returns one or more quotes, each with a `quoteId`, an expiry, and an offer holding the delivered `amount` (net of fees) and the `fees` in the fiat currency.
```json Request theme={null}
POST /payins/quote
{
"provider": "Borderless",
"walletId": "wa-5pfuu-9euek-h0odgb6snva8ph3k",
"amount": "100.00",
"currency": "USD",
"country": "US",
"paymentMethod": "Wire",
"borderlessAccountId": "",
"asset": {
"kind": "Erc20",
"contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
}
```
/payins : [Create payin](/api-reference/payins/create-payin)
Create the payin with `provider: Borderless` and the `quoteId` to lock the rate. The response's `data` carries the Borderless deposit instructions — the details the payer uses to fund the fiat deposit.
```json Request theme={null}
POST /payins
{
"provider": "Borderless",
"walletId": "wa-5pfuu-9euek-h0odgb6snva8ph3k",
"borderlessAccountId": "",
"quoteId": "",
"asset": {
"kind": "Erc20",
"contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
}
```
/payins/\{payinId} : [Get payin status](/api-reference/payins/get-payin-status)
The payer settles the fiat deposit using the returned instructions. Poll the payin to follow its progress: `data.executionStatus` reflects the Borderless steps, and the delivery `transactionHash` appears once the stablecoin is delivered on-chain.
```json Request theme={null}
GET /payins/{payinId}
```
## Check provider balances
/payins/balances : [List payin balances](/api-reference/payins/list-payin-balances)
Retrieve your available balance at the provider, one entry per currency. Pass the `provider` (`CircleMint` or `Borderless`) 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
/payins : [List payins](/api-reference/payins/list-payins)
List your payins to reconcile deliveries:
```json Request theme={null}
GET /payins
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.