> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capa.fi/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Cross-Ramp
Creates a cross-ramp transaction on behalf of a **verified** user. This converts one fiat currency to another (e.g., MXN to USD) and initiates the transfer to the target bank account.
For staging transaction testing, use the [Mock Testing Guide](/reference/transactionpartnerv2controller_getmocktestingguide).
***
## Idempotency
Retry safely without creating duplicate transactions: pass an optional **`Idempotency-Key`** header (UUIDv4). A retry with the same key and body replays the original response. See the [Idempotency Guide](/docs/idempotency) for the full contract.
```shell theme={null}
curl --request POST \
--url https://staging-api.capa.fi/api/partner/v2/cross-ramp \
--header 'Content-Type: application/json' \
--header 'partner-api-key: ' \
--header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
--data '...'
```
***
## Field Relationships
* Provide either `sourceAmount` or `targetAmount`, not both.
* Provide either `targetBankAccount` (inline bank details) or `targetBankAccountId` (reference to a saved bank account).
* `sourceCurrency` and `targetCurrency` must differ.
* `targetCurrency` must match the currency of the target bank account's country.
* `receiverId` is optional — when provided, the transaction is processed for that receiver.
***
## Bank Account Requirements by Country
| Country | Required Fields |
| ----------- | -------------------------------------------------------------------------------------------------- |
| **MX** | `accountIdentifier` (18-digit CLABE) |
| **DO** | `accountIdentifier`, `bankName`, `accountType`, `documentIdentifier`, `documentType` |
| **US** | `accountIdentifier`, `bankName`, `routingNumber`, `accountHolder`, `address` |
| **SEPA** | `iban`, `bic`, `bankName`, `accountHolder` |
| **CN / HK** | `accountIdentifier`, `bankName`, `accountType`, `accountHolder`, `address`; `bic` optional (SWIFT) |
***
## China & Hong Kong Destinations
USD can be delivered to bank accounts in **China (CN)** and **Hong Kong (HK)** as **destination-only** corridors:
* **USD only** — CNY is not yet supported. Since source and target currencies must differ, the source currency must be **MXN, DOP, or EUR**.
* **`targetCountry`** — set to `"CN"` or `"HK"` to route USD there (USD otherwise defaults to the US); resolved from the target bank account country when omitted.
* **`targetRail`** — `LOCAL` (default) or `SWIFT`.
* **`invoiceFile`** — Base64-encoded PDF invoice, **required** when the target country is `CN`.
* **`reference`** — optional memo (max 140 chars) forwarded to the payment provider. Supported across all currencies.
See the [Cross-Ramp guide](/docs/cross-ramp#china--hong-kong-destinations) for the full flow.
***
## Integration Flow
[POST /api/partner/v2/users](/reference/userpartnercontrollerv2_createuser), then [KYC verification](/reference/userpartnercontrollerv2_createverificationlink)
[POST /api/partner/v2/cross-ramp/quotes](/reference/crossramppartnerv2controller_createpartnercrossrampquote) — locks the exchange rate
`POST /api/partner/v2/cross-ramp` (this endpoint)
The user deposits fiat in the source currency to the bank account in `sourceBankAccount`.
***
## Important Notes
* **User must be KYC-verified** before creating transactions.
* **Supported corridors**: MX, DO, US, and SEPA countries. USD can also be delivered to **CN (China)** and **HK (Hong Kong)** as destination-only corridors.
* **Amount limits**: Fiat amounts must fall within the min/max thresholds defined in your partner agreement.
***
## Use Cases
* **International Remittances**: Convert MXN to USD and send funds to a US bank account.
* **Multi-Currency Payouts**: Deliver funds in a different fiat currency from the source deposit.
* **Cross-Border B2B Payments**: Facilitate business payments across currencies.
***
## Error Codes
### Common Errors
| HTTP Status | Code | Message |
| ----------- | ---------------------- | ---------------------------------- |
| 401 | `UNAUTHORIZED` | "API Key is missing" |
| 401 | `UNAUTHORIZED` | "Invalid API Key format" |
| 401 | `UNAUTHORIZED` | "Invalid API Key" |
| 403 | `INVALID_PARTNER_FLOW` | "The partner has an invalid flow." |
### Verified User Errors
| HTTP Status | Code | Message |
| ----------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
| 400 | `REQUIRED_USER_ID_ERROR` | "This endpoint requires a user id to be provided" |
| 403 | `USER_NOT_VERIFIED_ERROR` | "User is not allowed to perform the operations because has not completed the KYC verification." |
### Endpoint-Specific Errors
| HTTP Status | Code | Message |
| ----------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 400 | `INVALID_USER_INPUT_ERROR` | "Invalid User Input" |
| 400 | `BAD_REQUEST` | "Either targetBankAccount or targetBankAccountId must be provided" |
| 400 | `BAD_REQUEST` | "Unsupported country for cross-ramp: {country}" |
| 400 | `BAD_REQUEST` | "invoiceFile is required when target bank account country is CN" |
| 400 | `BAD_REQUEST` | "Target currency must match target bank account currency (expected: {expected}, actual: {actual})" |
| 400 | `BAD_REQUEST` | "Source and target currencies must differ" |
| 400 | `BAD_REQUEST` | "Requested fiat currency is invalid or inactive" |
| 400 | `BAD_REQUEST` | "Provided quoteId is not a CROSS\_RAMP quote" |
| 400 | `BAD_REQUEST` | "Quote currency mismatch (expected: {expected}, actual: {actual})" |
| 400 | `QUOTE_EXPIRED` | "Quote has expired" |
| 400 | `BAD_REQUEST` | "Cannot create transaction: No supported banks configured for user with id: {userId}" |
| 400 | `BAD_REQUEST` | "The receiver user account is not verified" |
| 403 | `RECEIVER_CANNOT_INITIATE_TRANSACTION` | "Receiver accounts cannot initiate transactions directly." |
| 403 | `RECEIVER_USER_MISMATCH` | "The receiver does not belong to the specified user." |
| 403 | `USER_BANK_INFO_ACCESS_DENIED` | "The bank information does not belong to the specified user." |
| 404 | `RECEIVER_NOT_FOUND` | "Receiver not found." |
| 404 | `USER_BANK_INFO_NOT_FOUND` | "User bank information not found." |
## OpenAPI
````yaml reference/openapi/CrossRampPartnerV2Controller_createPartnerCrossRamp.json POST /api/partner/v2/cross-ramp
openapi: 3.0.0
info:
title: Capa Partner API - V2
description: >-
Partner API for integrating cryptocurrency on-ramp and off-ramp services
using Capa's infrastructure. Enable your users to seamlessly convert between
fiat and crypto.
version: v2
contact: {}
servers:
- url: https://staging-api.capa.fi
- url: https://production-api.capa.fi
security: []
paths:
/api/partner/v2/cross-ramp:
post:
tags:
- cross-ramp
operationId: CrossRampPartnerV2Controller_createPartnerCrossRamp
parameters:
- name: Idempotency-Key
in: header
description: >-
Optional. Unique key (UUIDv4 recommended) to safely retry this
request without creating a duplicate transaction. A retry with the
same key and body replays the original response. See
/docs/idempotency.
required: false
schema:
type: string
minLength: 16
maxLength: 128
example: 550e8400-e29b-41d4-a716-446655440000
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
targetBankAccount:
type: object
description: User bank info to be saved
properties:
accountIdentifier:
type: string
description: >-
Always required. MX: CLABE. DO/US: account number.
EU/SEPA: IBAN. For US (ACH), also provide routingNumber.
routingNumber:
type: string
description: Required only for US
bic:
type: string
description: Required only for SEPA countries
country:
type: string
enum:
- 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
- CN
- HK
description: >-
Required. Determines validation rules. CN (China) and HK
(Hong Kong) are cross-ramp destinations only (USD
delivery).
accountType:
type: string
enum:
- SAVINGS
- CHECKING
description: Required only for DO and US
bankName:
type: string
description: Required only for DO and US
documentIdentifier:
type: string
description: Required only for DO and US
documentType:
type: string
enum:
- PASSPORT
- CEDULA
- RNC
description: Required for DO
accountHolder:
type: object
description: Required for SEPA countries and US
properties:
type:
type: string
enum:
- INDIVIDUAL
- BUSINESS
businessName:
type: string
description: Required when type=BUSINESS
firstName:
type: string
description: Required when type=INDIVIDUAL
lastName:
type: string
description: Required when type=INDIVIDUAL
address:
type: object
description: Required only for US
properties:
streetLine1:
type: string
description: Required
streetLine2:
type: string
description: Optional
city:
type: string
description: Required
state:
type: string
description: Optional
postalCode:
type: string
description: Required
country:
type: string
description: Required. Must be US
enum:
- US
targetBankAccountId:
type: string
description: >-
ID of an existing bank account to use as the target. Either
targetBankAccount or targetBankAccountId must be provided.
userId:
type: string
description: User's identifier
example: 12a121ad-cbea-4ec4-9e0a-5c861e528bba
sourceAmount:
type: number
description: Amount of currency from source
targetAmount:
type: number
description: Amount of currency that will be delivered
sourceCurrency:
description: Source currency symbol
example: MXN
enum:
- MXN
- DOP
- USD
- EUR
type: string
targetCurrency:
description: Target currency symbol
example: USD
enum:
- MXN
- DOP
- USD
- EUR
type: string
quoteId:
type: string
description: Identifier for the quote to be used for the transaction.
premiumSpread:
type: number
description: Premium spread percentage
targetCountry:
type: string
enum:
- 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
- CN
- HK
description: >-
Target country. Required to route USD to China (CN) or Hong
Kong (HK), since USD otherwise defaults to the US. Resolved
from the target bank account country when omitted.
targetRail:
type: string
enum:
- LOCAL
- SWIFT
description: >-
Target payment rail for CN/HK destinations. Defaults to
LOCAL; use SWIFT for an international wire.
invoiceFile:
type: string
description: >-
Base64-encoded PDF invoice. Required when the target bank
account country is CN (China).
reference:
type: string
maxLength: 140
description: >-
Free-text remittance reference / memo (max 140 chars)
forwarded to the payment provider. Supported across all
currencies.
required:
- userId
- sourceCurrency
- targetCurrency
x-readme-ref-name: CreatePartnerCrossRampTransactionV2RequestBody
responses:
'201':
description: >-
Cross-ramp transaction created successfully. Returns the transaction
details, including its id and current status.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: string
description: Transaction ID
example: 12a121ad-cbea-4ec4-9e0a-5c861e528bba
userId:
type: string
description: User ID
example: 12a121ad-cbea-4ec4-9e0a-5c861e528bba
status:
description: Transaction status
example: PENDING
enum:
- FAILED
- COMPLETED
- PENDING
- PENDING_PAYMENT
- FIAT_PAYMENT_RECEIVED
- FIAT_RECEIVED
- CRYPTO_RECEIVED
- CRYPTO_NOT_RECEIVED
- COMPLETED_CRYPTO_RECEIVAL
- CANCELLED
- IN_PROGRESS
- BANK_TRANSFER_PENDING
- READY_BANK_TRANSFER
- AWAITING_MANUAL_CRYPTO_TRANSFER
- AWAITING_MANUAL_FIAT_TRANSFER
- PENDING_FUNDS
- FUNDS_RECEIVED
- AWAITING_FUND_TRANSFER
type: string
sourceCurrency:
description: Source currency symbol
example: MXN
enum:
- MXN
- DOP
- USD
- EUR
type: string
targetCurrency:
description: Target currency symbol
example: DOP
enum:
- MXN
- DOP
- USD
- EUR
type: string
sourceAmount:
type: number
description: Source amount
example: 1000
targetAmount:
type: number
description: Target amount that will be delivered
example: 950
exchangeRate:
type: number
description: Exchange rate from source to target fiat
example: 0.95
sourceBankAccount:
description: Bank account information for source fiat
allOf:
- type: object
properties:
accountHolder:
description: Beneficiary name of the bank account
example:
type: BUSINESS
name: Capa.fi
allOf:
- type: object
properties:
type:
description: Type of the account holder
example: BUSINESS
enum:
- INDIVIDUAL
- BUSINESS
type: string
name:
type: string
description: Business name of the account holder
example: Capa.fi
required:
- type
- name
x-readme-ref-name: AccountHolderResponse
bic:
type: string
description: BIC of the bank account (SEPA countries)
example: DEUTDEFF
routingNumber:
type: string
description: Routing number of the bank account (US)
example: '021000021'
address:
description: Address of the bank account
example:
streetLine1: 123 Main St
city: New York
state: NY
postalCode: '10001'
country: US
allOf:
- type: object
properties:
streetLine1:
type: string
description: Street line 1
example: 123 Main St
city:
type: string
description: City
example: New York
state:
type: string
description: State/Province
example: NY
postalCode:
type: string
description: Postal/ZIP code
example: '10001'
country:
type: string
description: ISO 3166-1 alpha-2 country code
example: US
required:
- streetLine1
- city
- state
- postalCode
- country
x-readme-ref-name: BankAccountAddressResponse
message:
type: string
description: >-
Message should be included in the deposit
intent, so we can track the deposit in the
bank
example: RANDOM_MESSAGE
country:
type: string
description: The country of the bank account
example: MX
accountIdentifier:
type: string
description: >-
The account identifier for the bank account
(CLABE in MX, account number elsewhere)
example: '014680260346007120'
bankName:
type: string
description: The name of the bank
example: Santander
accountType:
type: string
description: The type of the account
example: SAVINGS
isVerified:
type: boolean
description: Whether the account is verified
example: true
documentIdentifier:
type: string
description: >-
The document identifier used for verification
(e.g. national tax / ID number)
example: 123abc
documentType:
type: string
description: >-
Type of the document bound to the account
(country specific)
example: RNC
iban:
type: string
description: >-
International Bank Account Number (SEPA / EU
accounts)
example: DE89370400440532013000
required:
- country
- accountIdentifier
- isVerified
x-readme-ref-name: CrossRampSourceBankAccountResponse
targetBankAccount:
description: Bank account information for target fiat
allOf:
- type: object
properties:
accountHolder:
description: Beneficiary name of the bank account
example:
type: BUSINESS
name: Capa.fi
allOf:
- type: object
properties:
type:
description: Type of the account holder
example: BUSINESS
enum:
- INDIVIDUAL
- BUSINESS
type: string
name:
type: string
description: Business name of the account holder
example: Capa.fi
required:
- type
- name
x-readme-ref-name: AccountHolderResponse
bic:
type: string
description: BIC of the bank account (SEPA countries)
example: DEUTDEFF
routingNumber:
type: string
description: Routing number of the bank account (US)
example: '021000021'
address:
description: Address of the bank account
example:
streetLine1: 123 Main St
city: New York
state: NY
postalCode: '10001'
country: US
allOf:
- type: object
properties:
streetLine1:
type: string
description: Street line 1
example: 123 Main St
city:
type: string
description: City
example: New York
state:
type: string
description: State/Province
example: NY
postalCode:
type: string
description: Postal/ZIP code
example: '10001'
country:
type: string
description: ISO 3166-1 alpha-2 country code
example: US
required:
- streetLine1
- city
- state
- postalCode
- country
x-readme-ref-name: BankAccountAddressResponse
message:
type: string
description: >-
Message should be included in the deposit
intent, so we can track the deposit in the
bank
example: RANDOM_MESSAGE
country:
type: string
description: The country of the bank account
example: MX
accountIdentifier:
type: string
description: >-
The account identifier for the bank account
(CLABE in MX, account number elsewhere)
example: '014680260346007120'
bankName:
type: string
description: The name of the bank
example: Santander
accountType:
type: string
description: The type of the account
example: SAVINGS
isVerified:
type: boolean
description: Whether the account is verified
example: true
documentIdentifier:
type: string
description: >-
The document identifier used for verification
(e.g. national tax / ID number)
example: 123abc
documentType:
type: string
description: >-
Type of the document bound to the account
(country specific)
example: RNC
iban:
type: string
description: >-
International Bank Account Number (SEPA / EU
accounts)
example: DE89370400440532013000
required:
- country
- accountIdentifier
- isVerified
x-readme-ref-name: CrossRampSourceBankAccountResponse
createdAt:
type: string
description: Transaction creation date
example: '2024-01-01T12:00:00Z'
premiumSpread:
type: number
description: Premium spread applied
example: 0.01
completedAt:
type: string
description: Transaction completion date (null if not completed)
required:
- id
- userId
- status
- exchangeRate
- sourceBankAccount
- targetBankAccount
- createdAt
x-readme-ref-name: CrossRampPartnerV2Response
example:
success: true
data:
id: 12a121ad-cbea-4ec4-9e0a-5c861e528bba
userId: 12a121ad-cbea-4ec4-9e0a-5c861e528bba
status: PENDING
sourceCurrency: MXN
targetCurrency: DOP
sourceAmount: 1000
targetAmount: 950
exchangeRate: 0.95
sourceBankAccount:
country: MX
accountIdentifier: '014680260346007120'
bankName: Santander
isVerified: true
message: 12a121ad-cbea-4ec4-9e0a-5c861e528bba
targetBankAccount:
country: DO
accountIdentifier: '0123456789012345678'
bankName: Banco Popular Dominicano
isVerified: true
createdAt: '2024-01-01T12:00:00Z'
premiumSpread: 0.01
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
REQUIRED_USER_ID_ERROR:
value:
success: false
code: REQUIRED_USER_ID_ERROR
message: This endpoint requires a user id to be provided
INVALID_USER_INPUT_ERROR:
value:
success: false
code: INVALID_USER_INPUT_ERROR
message: Invalid User Input
BAD_REQUEST:
value:
success: false
code: BAD_REQUEST
message: >-
Either targetBankAccount or targetBankAccountId must be
provided
BAD_REQUEST_2:
value:
success: false
code: BAD_REQUEST
message: 'Unsupported country for cross-ramp: {country}'
BAD_REQUEST_3:
value:
success: false
code: BAD_REQUEST
message: >-
Target currency must match target bank account currency
(expected: {expected}, actual: {actual})
BAD_REQUEST_INVOICE_FILE:
value:
success: false
code: BAD_REQUEST
message: >-
invoiceFile is required when target bank account country
is CN
BAD_REQUEST_4:
value:
success: false
code: BAD_REQUEST
message: Provided quoteId is not a CROSS_RAMP quote
BAD_REQUEST_5:
value:
success: false
code: BAD_REQUEST
message: >-
Quote currency mismatch (expected: {expected}, actual:
{actual})
BAD_REQUEST_6:
value:
success: false
code: BAD_REQUEST
message: Source and target currencies must differ
BAD_REQUEST_7:
value:
success: false
code: BAD_REQUEST
message: Requested fiat currency is invalid or inactive
BAD_REQUEST_8:
value:
success: false
code: BAD_REQUEST
message: >-
This blockchain and token combination is disabled or does
not exist
BAD_REQUEST_9:
value:
success: false
code: BAD_REQUEST
message: >-
Cannot create transaction: No supported banks configured
for user with id: {userId}
BAD_REQUEST_10:
value:
success: false
code: BAD_REQUEST
message: The receiver user account is not verified
QUOTE_EXPIRED:
value:
success: false
code: QUOTE_EXPIRED
message: Quote has expired
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
UNAUTHORIZED:
value:
success: false
code: UNAUTHORIZED
message: API Key is missing
UNAUTHORIZED_2:
value:
success: false
code: UNAUTHORIZED
message: Invalid API Key format
UNAUTHORIZED_3:
value:
success: false
code: UNAUTHORIZED
message: Invalid API Key
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
USER_NOT_VERIFIED_ERROR:
value:
success: false
code: USER_NOT_VERIFIED_ERROR
message: >-
User is not allowed to perform the operations because has
not completed the KYC verification.
RECEIVER_CANNOT_INITIATE_TRANSACTION:
value:
success: false
code: RECEIVER_CANNOT_INITIATE_TRANSACTION
message: Receiver accounts cannot initiate transactions directly.
RECEIVER_USER_MISMATCH:
value:
success: false
code: RECEIVER_USER_MISMATCH
message: The receiver does not belong to the specified user.
USER_BANK_INFO_ACCESS_DENIED:
value:
success: false
code: USER_BANK_INFO_ACCESS_DENIED
message: >-
The bank information does not belong to the specified
user.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
RECEIVER_NOT_FOUND:
value:
success: false
code: RECEIVER_NOT_FOUND
message: Receiver not found.
USER_BANK_INFO_NOT_FOUND:
value:
success: false
code: USER_BANK_INFO_NOT_FOUND
message: User bank information not found.
NOT_FOUND_ERROR:
value:
success: false
code: NOT_FOUND_ERROR
message: Requested resource was not found
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
code: CONFLICT
message: >-
A request with this idempotency key is currently being
processed
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
code: INVALID_USER_INPUT_ERROR
message: Idempotency-Key was already used with a different request body
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
code: INTERNAL_SERVER_ERROR
message: Internal server error
security:
- PartnerApiKey: []
components:
schemas:
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
code:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable error message.
errors:
type: array
description: Optional per-field validation details.
items:
type: object
properties:
field:
type: string
message:
type: string
required:
- success
- code
- message
securitySchemes:
PartnerApiKey:
type: apiKey
in: header
name: partner-api-key
description: API key for the affiliated partner performing the request.
````