/api/partner/v2/cross-ramp

Creates a cross-ramp transaction on behalf of a verified user. This enables the conversion of fiat to fiat and initiates the transfer to the target bank account.

🔐 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.
`sourceAmount`	`number`	🔘	Amount of fiat to be converted. Required if `cryptoAmount` is not provided.
`targetAmount`	`number`	🔘	Amount of crypto to be converted to fiat. Required if `fiatAmount` is not provided.
`sourceCurrency`	`string`	✅	Currency to send for the cross-ramp transaction. The user must have an account in this currency. Accepted values follow the `ISO 4217` format (e.g., `MXN`, `DOP`,`USD`).
`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

curl

curl --request POST \
     --url https://staging-api.capa.fi/api/partner/v2/on-ramp \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'partner-api-key: API-KEY' \
     --data '
{
  "sourceCurrency": "USD",
  "userId": "d3127f5f-ff64-47f9-a9cc-ff603862eca6",
  "sourceAmount": 10000,
  "targetAmount": 10000,
	"userBankInformation": {
    "accountIdentifier": "012345678912345678",
    "country": "MX"
  },
  "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.
`userBankInformation`	`object`	User’s bank information. 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
`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",
        "sourceAmount": 0.26,
        "targetAmount": 4.728013,
        "exchangeRate": 18.184665,
	      "sourceCurrency": "DOP",
				"targetCurrency": "MXN",
        "createdAt": "2025-06-09T21:51:32.288Z",
        "completedAt": null,
        "userBankInformation": {
            "country": "MX",
            "accountIdentifier": "012345678902422382",
            "isVerified": true
        },
				"bankAccount": {
            "country": "DO",
            "bankName":"Banco BHD",
            "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 and have an will go through an account verification process. The verification is only made once.
Supported Countries: Only flows from MX (Mexico), DO (Dominican Republic) and US (United States) are currently supported.
Amount Limits: Crypto amounts must respect the minimum and maximum thresholds defined in the partner agreement.

✅ 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

User's identifier

Example:

"12a121ad-cbea-4ec4-9e0a-5c861e528bba"

sourceCurrency

enum<string>

required

Source currency symbol

Available options:

MXN,

DOP,

USD,

EUR

Example:

"MXN"

targetCurrency

enum<string>

required

Target currency symbol

Available options:

MXN,

DOP,

USD,

EUR

Example:

"USD"

targetBankAccount

object

User bank info to be saved

Show child attributes

targetBankAccount.accountIdentifier

string

Always required. MX: CLABE. DO/US: account number. EU/SEPA: IBAN. For US (ACH), also provide routingNumber.

targetBankAccount.routingNumber

string

Required only for US

targetBankAccount.bic

string

Required only for SEPA countries

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

targetBankAccount.accountType

enum<string>

Required only for DO and US

Available options:

SAVINGS,

CHECKING

targetBankAccount.bankName

string

Required only for DO and US

targetBankAccount.documentIdentifier

string

Required only for DO and US

targetBankAccount.documentType

enum<string>

Required for DO

Available options:

PASSPORT,

CEDULA,

RNC

targetBankAccount.accountHolder

object

Required for SEPA countries and US

Show child attributes

targetBankAccount.accountHolder.type

enum<string>

Available options:

INDIVIDUAL,

BUSINESS

targetBankAccount.accountHolder.businessName

string

Required when type=BUSINESS

targetBankAccount.accountHolder.firstName

string

Required when type=INDIVIDUAL

targetBankAccount.accountHolder.lastName

string

Required when type=INDIVIDUAL

targetBankAccount.address

object

Required only for US

Show child attributes

targetBankAccount.address.streetLine1

string

Required

targetBankAccount.address.streetLine2

string

Optional

targetBankAccount.address.city

string

Required

targetBankAccount.address.state

string

Optional

targetBankAccount.address.postalCode

string

Required

targetBankAccount.address.country

enum<string>

Required. Must be US

Available options:

US

sourceAmount

number

Amount of currency from source

Example:

1000

targetAmount

number

Amount of currency that will be delivered

Example:

50.5

quoteId

string

Identifier for the quote to be used for the transaction.

premiumSpread

number

Premium spread percentage

Example:

0.01

Response

201 - application/json

success

boolean

Example:

true

data

object

Show child attributes

data.id

string

required

Transaction ID

Example:

"12a121ad-cbea-4ec4-9e0a-5c861e528bba"

data.userId

string

required

User ID

Example:

"12a121ad-cbea-4ec4-9e0a-5c861e528bba"

data.status

enum<string>

required

Transaction status

Available options:

FAILED,

COMPLETED,

PENDING,

PENDING_PAYMENT,

FIAT_PAYMENT_RECEIVED,

FIAT_RECEIVED,

CRYPTO_RECEIVED,

CRYPTO_NOT_RECEIVED,

COMPLETED_CRYPTO_RECEIVAL,

EXPIRED,

CANCELLED,

IN_PROGRESS,

BANK_TRANSFER_PENDING,

READY_BANK_TRANSFER,

AWAITING_MANUAL_CRYPTO_TRANSFER,

AWAITING_MANUAL_FIAT_TRANSFER,

PENDING_FUNDS,

FUNDS_RECEIVED,

AWAITING_FUND_TRANSFER

Example:

"PENDING"

data.exchangeRate

number

required

Exchange rate from source to target fiat

Example:

0.95

data.sourceBankAccount

object

required

Bank account information for source fiat

Show child attributes

data.sourceBankAccount.country

string

required

The country of the bank account

Example:

"MX"

data.sourceBankAccount.accountIdentifier

string

required

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

Example:

"014680260346007120"

data.sourceBankAccount.isVerified

boolean

required

Whether the account is verified

Example:

true

data.sourceBankAccount.accountHolder

object

Beneficiary name of the bank account

Show child attributes

data.sourceBankAccount.accountHolder.type

enum<string>

required

Type of the account holder

Available options:

INDIVIDUAL,

BUSINESS

Example:

"BUSINESS"

data.sourceBankAccount.accountHolder.name

string

required

Business name of the account holder

Example:

"Capa.fi"

Example:

{ "type": "BUSINESS", "name": "Capa.fi" }

data.sourceBankAccount.bic

string

BIC of the bank account (SEPA countries)

Example:

"DEUTDEFF"

data.sourceBankAccount.routingNumber

string

Routing number of the bank account (US)

Example:

"021000021"

data.sourceBankAccount.address

object

Address of the bank account

Show child attributes

data.sourceBankAccount.address.streetLine1

string

required

Street line 1

Example:

"123 Main St"

data.sourceBankAccount.address.city

string

required

City

Example:

"New York"

data.sourceBankAccount.address.state

string

required

State/Province

Example:

"NY"

data.sourceBankAccount.address.postalCode

string

required

Postal/ZIP code

Example:

"10001"

data.sourceBankAccount.address.country

string

required

ISO 3166-1 alpha-2 country code

Example:

"US"

Example:

{
  "streetLine1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "postalCode": "10001",
  "country": "US"
}

data.sourceBankAccount.message

string

Message should be included in the deposit intent, so we can track the deposit in the bank

Example:

"RANDOM_MESSAGE"

data.sourceBankAccount.bankName

string

The name of the bank

Example:

"Santander"

data.sourceBankAccount.accountType

string

The type of the account

Example:

"SAVINGS"

data.sourceBankAccount.documentIdentifier

string

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

Example:

"123abc"

data.sourceBankAccount.documentType

string

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

Example:

"RNC"

data.sourceBankAccount.iban

string

International Bank Account Number (SEPA / EU accounts)

Example:

"DE89370400440532013000"

data.targetBankAccount

object

required

Bank account information for target fiat

Show child attributes

data.targetBankAccount.country

string

required

The country of the bank account

Example:

"MX"

data.targetBankAccount.accountIdentifier

string

required

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

Example:

"014680260346007120"

data.targetBankAccount.isVerified

boolean

required

Whether the account is verified

Example:

true

data.targetBankAccount.accountHolder

object

Beneficiary name of the bank account

Show child attributes

data.targetBankAccount.accountHolder.type

enum<string>

required

Type of the account holder

Available options:

INDIVIDUAL,

BUSINESS

Example:

"BUSINESS"

data.targetBankAccount.accountHolder.name

string

required

Business name of the account holder

Example:

"Capa.fi"

Example:

{ "type": "BUSINESS", "name": "Capa.fi" }

data.targetBankAccount.bic

string

BIC of the bank account (SEPA countries)

Example:

"DEUTDEFF"

data.targetBankAccount.routingNumber

string

Routing number of the bank account (US)

Example:

"021000021"

data.targetBankAccount.address

object

Address of the bank account

Show child attributes

data.targetBankAccount.address.streetLine1

string

required

Street line 1

Example:

"123 Main St"

data.targetBankAccount.address.city

string

required

City

Example:

"New York"

data.targetBankAccount.address.state

string

required

State/Province

Example:

"NY"

data.targetBankAccount.address.postalCode

string

required

Postal/ZIP code

Example:

"10001"

data.targetBankAccount.address.country

string

required

ISO 3166-1 alpha-2 country code

Example:

"US"

Example:

{
  "streetLine1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "postalCode": "10001",
  "country": "US"
}

data.targetBankAccount.message

string

Message should be included in the deposit intent, so we can track the deposit in the bank

Example:

"RANDOM_MESSAGE"

data.targetBankAccount.bankName

string

The name of the bank

Example:

"Santander"

data.targetBankAccount.accountType

string

The type of the account

Example:

"SAVINGS"

data.targetBankAccount.documentIdentifier

string

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

Example:

"123abc"

data.targetBankAccount.documentType

string

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

Example:

"RNC"

data.targetBankAccount.iban

string

International Bank Account Number (SEPA / EU accounts)

Example:

"DE89370400440532013000"

data.createdAt

string

required

Transaction creation date

Example:

null

data.sourceCurrency

enum<string>

Source currency symbol

Available options:

MXN,

DOP,

USD,

EUR

Example:

"MXN"

data.targetCurrency

enum<string>

Target currency symbol

Available options:

MXN,

DOP,

USD,

EUR

Example:

"DOP"

data.sourceAmount

number

Source amount

Example:

1000

data.targetAmount

number

Target amount that will be delivered

Example:

950

data.premiumSpread

number

Premium spread applied

Example:

0.01

data.completedAt

string

Transaction completion date (null if not completed)

Capa Partner API - V2

​🔐 Headers

​📥 Request Body

​📨 Example Request

​📤 Response Body

​📘 Example Response

​⚠️ Important Notes & Requirements

​✅ Use Cases

Headers

Body

Response

🔐 Headers

📥 Request Body

📨 Example Request

📤 Response Body

📘 Example Response

⚠️ Important Notes & Requirements

✅ Use Cases