/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.

📥 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

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

📥 Request Body

📨 Example Request MX

📨 Example Request DO

📤 Response Body

📘 Example Response

⚠️ Important Notes & Requirements

✅ Use Cases

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