/api/partner/v2/off-ramp

Creates an off-ramp transaction on behalf of a verified user. This enables the conversion of crypto to fiat and initiates the withdrawal to a registered bank account verified as belonging to the user.

🔐 Headers

Header	Description
`partner-api-key`	API key associated with your partner account. Required. See API Key Generation Guide.

This endpoint requires authentication using a valid partner-api-key.

For Staging Transaction Testing please use Mock Testing Guide

📥 Request Body

`Parameter`	`Type`	Required	Description
`userId`	`string`	✅	ID of the user on whose behalf the transaction is created. The user’s kyc must be verified first.
`fiatAmount`	`number`	🔘	Amount of fiat to be converted. Required if `cryptoAmount` is not provided.
`cryptoAmount`	`number`	🔘	Amount of crypto to be converted to fiat. Required if `fiatAmount` is not provided.
`fiatCurrency`	`string`	✅	Currency for the off-ramp transaction. The user must have an account in this currency. Accepted values follow the `ISO 4217` format (e.g., `MXN`, `DOP`).
`blockchainSymbol`	`string`	✅	Identifier of the blockchain used for the conversion. Refer to our supported blockchain list for availability.
`tokenSymbol`	`string`	✅	Identifier of the token used for the conversion. Refer to our supported token list for availability.
`premiumSpread`	`number`	🔘	Additional percentage applied to the exchange rate. This amount is fully awarded to the partner.
`userBankInformation`	`object`	✅	User’s bank information to be saved. See nested fields below.
`userBankInformation .accountIdentifier`	`string`	✅	Unique account identifier (CLABE for Mexico, Account Number for the Dominican Republic).
`userBankInformation .country`	`string`	✅	Country in which the bank account is held.
`userBankInformation .bankName`	`string`	🔘	Name of the user’s bank. List of Dominican Republic Banks
`userBankInformation .accountType`	`string`	🔘	Type of bank account `SAVINGS` or `CHECKING`. Only required for the Dominican Republic.
`userBankInformation .documentIdentifier`	`string`	🔘	Unique identifier of the document linked to the bank account. Only required for the Dominican Republic.
`userBankInformation .documentType`	`string`	🔘	Document Type `PASSPORT` or `RNC` or`CEDULA`. Only Required for the Dominican Republic

📨 Example Request MX

curl --request POST \
     --url https://staging-api.capa.fi/api/partner/v2/off-ramp \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'partner-api-key: API-KEY' \
     --data '
{
  "userBankInformation": {
    "accountIdentifier": "012345678912345678",
    "country": "MX"
  },
  "fiatCurrency": "MXN",
  "blockchainSymbol": "POL",
  "tokenSymbol": "USDC",
  "userId": "8374f327-38bd-4b0b-b8a7-2524599eb903",
  "fiatAmount": 10000,
  "premiumSpread": 0.01
}
'

📨 Example Request DO

curl --request POST \
     --url https://staging-api.capa.fi/api/partner/v2/off-ramp \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'partner-api-key: API-KEY' \
     --data '
{
  "userBankInformation": {
    "accountIdentifier": "9605734495",
    "country": "DO",
    "bankName": "Banco BHD",
    "accountType": "SAVINGS",
    "documentIdentifier": "132753852",
    "documentType": "RNC",
  },
  "fiatCurrency": "DOP",
  "blockchainSymbol": "POL",
  "tokenSymbol": "USDC",
  "userId": "8374f327-38bd-4b0b-b8a7-2524599eb903",
  "fiatAmount": 10000,
  "premiumSpread": 0.01,
}
'

📤 Response Body

Field	Type	Description
`id`	`string`	Unique ID of the created transaction.
`userId`	`string`	User ID associated with the transaction.
`status`	`string`	Current status of the transaction. Initially set to `"PENDING"`.
`cryptoAmount`	`number`	Amount of cryptocurrency being converted.
`fiatAmount`	`number`	Amount of fiat currency received after conversion.
`exchangeRate`	`number`	Exchange rate used for the crypto-to-fiat conversion.
`tokenSymbol`	`string`	Symbol of the cryptocurrency used.
`blockchainSymbol`	`string`	Symbol of the blockchain the cryptocurrency belongs to.
`fiatCurrency`	`string`	Currency code of the fiat currency received (e.g., `"MXN"`).
`createdAt`	`string`	ISO timestamp indicating when the transaction was created.
`completedAt`	`string`	ISO timestamp indicating when the transaction was completed, or `null` if pending.
`destinationWalletAddress`	`string`	Wallet address where the user will need to send the crypto.
`bankAccount`	`object`	Information about the user’s bank account.
`bankAccount.isVerified`	`boolean`	Indicates whether the account has been verified and linked to the user.
`bankAccount .accountIdentifier`	`string`	Unique identifier of the account (CLABE for Mexico, Account Number for DO).
`bankAccount.country`	`string`	Country where the bank account is held.
`bankAccount.accountType`	`string`	Type of bank account. Only required for the Dominican Republic.
`bankAccount.bankName`	`string`	Name of the bank. Only required for the Dominican Republic.
`bankAccount .documentIdentifier`	`string`	Unique identifier of the document linked to the account.
`premiumSpread`	`number`	Additional percentage applied for premium services.

📘 Example Response

{
    "success": true,
    "data": {
        "id": "0483907e-ca31-432c-8234-fc401a921ef9",
        "userId": "d3127f5f-ff64-47f9-a9cc-ff603862eca6",
        "status": "PENDING",
        "cryptoAmount": 0.26,
        "fiatAmount": 4.728013,
        "exchangeRate": 18.184665,
        "tokenSymbol": "USDC",
        "blockchainSymbol": "POL",
        "fiatCurrency": "MXN",
        "createdAt": "2025-06-09T21:51:32.288Z",
        "completedAt": null,
        "destinationWalletAddress": "0x4cd63f6e9b8885dd502012f7b008b54d17a56e6f",
        "bankAccount": {
            "country": "MX",
            "accountIdentifier": "012345678902422382",
            "isVerified": true
        },
        "premiumSpread": 0.005
    }
}

⚠️ Important Notes & Requirements

Partner API Key is mandatory: All requests must include a valid PartnerApiKey in the header. Get your API key.
User must be verified: The user (userId) must have completed KYC. The verification is only made once.
Supported Countries: Only flows from MX (Mexico) and DO (Dominican Republic) are currently supported.
Amount Limits: Crypto amounts must respect the minimum and maximum thresholds defined in the partner agreement.
Valid Blockchain & Token name: Ensure blockchainSymbol and tokenSymbol are retrieved from valid sources. Contact support for available options.
Destination wallet: Each user have it’s own destination wallet, ensure you’re using the wallet from the response to send the crypto
Verification Bank Account in Mexico: If this is the first time a bank account is used there will be a penny test in Mexico to check that the KYC’d user is the actual owner. If it is not the transaction will be cancelled.
Account Identifier Validation in Mexico: Make sure to send a valid CLABE for Mexico using the following regex ^\d{18}$. This npm package could also be used for validation Clabe Validator

✅ Use Cases

User Payout: Initiate a crypto-to-fiat payout to a verified user.
B2C Integration: Allow individual users to off-ramp from within your app or service.
B2B or Corporate Flows: Automate withdrawals to company bank accounts after receiving crypto payments.

Headers

partner-api-key

string

required

Api key for the affiliated partner that is performing the request

Body

application/json

userId

string

required

Identifier for the user who's submitting the off-ramp order

Example:

"8374f327-38bd-4b0b-b8a7-2524599eb903"

userBankInformation

object

User bank info to be saved

Show child attributes

userBankInformation.accountIdentifier

string

Unique identifier for bank account. CLABE if country=MX.

userBankInformation.country

enum<string>

Required. Determines validation rules

Available options:

MX,

DO,

US,

AT,

BE,

BG,

HR,

CY,

CZ,

DK,

EE,

FI,

FR,

DE,

GR,

HU,

IE,

IT,

LV,

LT,

LU,

MT,

NL,

PL,

PT,

RO,

SK,

SI,

ES,

SE,

IS,

LI,

NO,

CH,

GB,

MC,

SM,

AD,

VA

userBankInformation.accountType

enum<string>

Required for DO

Available options:

SAVINGS,

CHECKING

userBankInformation.bankName

string

Required for DO / US / SEPA. Not allowed for MX.

userBankInformation.documentIdentifier

string

Required only for DO

userBankInformation.documentType

string

Required only for DO

userBankInformation.routingNumber

string

Required only for US (9-digit ABA).

userBankInformation.address

object

Required only for US (account address).

userBankInformation.bic

string

Required only for SEPA (EU).

userBankInformation.iban

string

Required only for SEPA (EU).

userBankInformation.accountHolder

object

Required for US & SEPA (INDIVIDUAL | BUSINESS).

quoteId

string

Identifier for the quote to be used for the transaction.

fiatAmount

number

Amount of fiat currency to be received in conversion.

Example:

10200

cryptoAmount

number

Amount of crypto currency to be converted to fiat currency.

Example:

10200

fiatCurrency

enum<string>

Identifier for the fiat currency which the user will rec. Required when quoteId is not provided.

Available options:

MXN,

DOP,

USD,

EUR

Example:

"MXN"

blockchainSymbol

enum<string>

Identifier for the blockchain to token from which the conversion will be made. Required when quoteId is not provided.

Available options:

POL,

SOL,

BASE,

ARB,

BSC,

OP,

WLD,

STK,

ETH,

MTN,

CORE

Example:

"BASE"

tokenSymbol

enum<string>

Identifier for the token from which the conversion will be made. Required when quoteId is not provided.

Available options:

USDC,

USDT,

MXNe,

SOL,

ETH,

wBTC,

cbBTC,

PYSUD,

POL,

BNB,

WLD,

STK,

USDY,

CORE,

USDC.e,

wUSDL,

CoreBTC,

MATIC,

USDbC

Example:

"ETH"

premiumSpread

number

Spread percentage to be applied to the exchange rate

Example:

0.01

Response

201 - application/json

success

boolean

Example:

true

data

object

Show child attributes

data.id

string

required

Transaction identifier

Example:

"63f51f11-6869-47b0-a109-ddb50ef20efb"

data.userId

string

required

User identifier

Example:

"8374f327-38bd-4b0b-b8a7-2524599eb903"

data.status

string

required

Transaction status

Example:

"PENDING_PAYMENT"

data.cryptoAmount

number

required

Amount of crypto currency involved in the transaction

Example:

2500

data.fiatAmount

number

required

Amount of fiat currency involved in the transaction

Example:

50000

data.exchangeRate

number

required

Exchange rate used for the transaction

Example:

19.53964594161554

data.tokenSymbol

enum<string>

required

Token symbol

Available options:

USDC,

USDT,

MXNe,

SOL,

ETH,

wBTC,

cbBTC,

PYSUD,

POL,

BNB,

WLD,

STK,

USDY,

CORE,

USDC.e,

wUSDL,

CoreBTC,

MATIC,

USDbC

Example:

"USDC"

data.blockchainSymbol

enum<string>

required

Blockchain symbol

Available options:

POL,

SOL,

BASE,

ARB,

BSC,

OP,

WLD,

STK,

ETH,

MTN,

CORE

Example:

"POL"

data.fiatCurrency

enum<string>

required

Fiat currency symbol

Available options:

MXN,

DOP,

USD,

EUR

Example:

"MXN"

data.createdAt

string

required

Transaction creation date

Example:

"2025-05-14T10:00:00Z"

data.completedAt

string | null

required

Transaction completion date (null if not completed)

data.destinationWalletAddress

string

required

Destination wallet address for the transaction

Example:

"0x7796d4f304bd84171ee6730ad0f69c07a47e786d"

data.bankAccount

object

required

Bank account information

Show child attributes

data.bankAccount.country

string

required

The country of the bank account

Example:

"MX"

data.bankAccount.accountIdentifier

string

required

The account identifier for the bank account (CLABE in MX, account number elsewhere)

Example:

"014680260346007120"

data.bankAccount.isVerified

boolean

required

Whether the account is verified

Example:

true

data.bankAccount.bankName

string

The name of the bank

Example:

"Santander"

data.bankAccount.accountType

string

The type of the account

Example:

"SAVINGS"

data.bankAccount.documentIdentifier

string

The document identifier used for verification (e.g. national tax / ID number)

Example:

"123abc"

data.bankAccount.documentType

string

Type of the document bound to the account (country specific)

Example:

"RNC"

data.bankAccount.iban

string

International Bank Account Number (SEPA / EU accounts)

Example:

"DE89370400440532013000"

data.bankAccount.bic

string

Bank Identifier Code (SWIFT BIC) for SEPA / EU accounts

Example:

"DEUTDEFF"

data.bankAccount.routingNumber

string

ABA routing number (US only, 9 digits)

Example:

"021000021"

data.crossFiatAmount

number

data.premiumSpread

number

Premium spread applied to the transaction (0 if not provided)

Example:

0.01

Capa Partner API - V2

​🔐 Headers

​📥 Request Body

​📨 Example Request MX

​📨 Example Request DO

​📤 Response Body

​📘 Example Response

​⚠️ Important Notes & Requirements

​✅ Use Cases

Headers

Body

Response

🔐 Headers

📥 Request Body

📨 Example Request MX

📨 Example Request DO

📤 Response Body

📘 Example Response

⚠️ Important Notes & Requirements

✅ Use Cases