Create Cross-Ramp

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/cross-ramp \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "sourceCurrency": "MXN",
  "targetCurrency": "USD",
  "targetBankAccount": {
    "accountIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "accountHolder": {
      "businessName": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "address": {
      "streetLine1": "<string>",
      "streetLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "US"
    }
  },
  "targetBankAccountId": "<string>",
  "sourceAmount": 123,
  "targetAmount": 123,
  "quoteId": "<string>",
  "premiumSpread": 123,
  "invoiceFile": "<string>",
  "reference": "<string>"
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/cross-ramp"

payload = {
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "sourceCurrency": "MXN",
    "targetCurrency": "USD",
    "targetBankAccount": {
        "accountIdentifier": "<string>",
        "routingNumber": "<string>",
        "bic": "<string>",
        "bankName": "<string>",
        "documentIdentifier": "<string>",
        "accountHolder": {
            "businessName": "<string>",
            "firstName": "<string>",
            "lastName": "<string>"
        },
        "address": {
            "streetLine1": "<string>",
            "streetLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "postalCode": "<string>",
            "country": "US"
        }
    },
    "targetBankAccountId": "<string>",
    "sourceAmount": 123,
    "targetAmount": 123,
    "quoteId": "<string>",
    "premiumSpread": 123,
    "invoiceFile": "<string>",
    "reference": "<string>"
}
headers = {
    "partner-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'partner-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '12a121ad-cbea-4ec4-9e0a-5c861e528bba',
    sourceCurrency: 'MXN',
    targetCurrency: 'USD',
    targetBankAccount: {
      accountIdentifier: '<string>',
      routingNumber: '<string>',
      bic: '<string>',
      bankName: '<string>',
      documentIdentifier: '<string>',
      accountHolder: {businessName: '<string>', firstName: '<string>', lastName: '<string>'},
      address: {
        streetLine1: '<string>',
        streetLine2: '<string>',
        city: '<string>',
        state: '<string>',
        postalCode: '<string>',
        country: 'US'
      }
    },
    targetBankAccountId: '<string>',
    sourceAmount: 123,
    targetAmount: 123,
    quoteId: '<string>',
    premiumSpread: 123,
    invoiceFile: '<string>',
    reference: '<string>'
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/cross-ramp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-api.capa.fi/api/partner/v2/cross-ramp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '12a121ad-cbea-4ec4-9e0a-5c861e528bba',
    'sourceCurrency' => 'MXN',
    'targetCurrency' => 'USD',
    'targetBankAccount' => [
        'accountIdentifier' => '<string>',
        'routingNumber' => '<string>',
        'bic' => '<string>',
        'bankName' => '<string>',
        'documentIdentifier' => '<string>',
        'accountHolder' => [
                'businessName' => '<string>',
                'firstName' => '<string>',
                'lastName' => '<string>'
        ],
        'address' => [
                'streetLine1' => '<string>',
                'streetLine2' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'postalCode' => '<string>',
                'country' => 'US'
        ]
    ],
    'targetBankAccountId' => '<string>',
    'sourceAmount' => 123,
    'targetAmount' => 123,
    'quoteId' => '<string>',
    'premiumSpread' => 123,
    'invoiceFile' => '<string>',
    'reference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/cross-ramp"

	payload := strings.NewReader("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"sourceCurrency\": \"MXN\",\n  \"targetCurrency\": \"USD\",\n  \"targetBankAccount\": {\n    \"accountIdentifier\": \"<string>\",\n    \"routingNumber\": \"<string>\",\n    \"bic\": \"<string>\",\n    \"bankName\": \"<string>\",\n    \"documentIdentifier\": \"<string>\",\n    \"accountHolder\": {\n      \"businessName\": \"<string>\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    },\n    \"address\": {\n      \"streetLine1\": \"<string>\",\n      \"streetLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"postalCode\": \"<string>\",\n      \"country\": \"US\"\n    }\n  },\n  \"targetBankAccountId\": \"<string>\",\n  \"sourceAmount\": 123,\n  \"targetAmount\": 123,\n  \"quoteId\": \"<string>\",\n  \"premiumSpread\": 123,\n  \"invoiceFile\": \"<string>\",\n  \"reference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("partner-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/cross-ramp")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"sourceCurrency\": \"MXN\",\n  \"targetCurrency\": \"USD\",\n  \"targetBankAccount\": {\n    \"accountIdentifier\": \"<string>\",\n    \"routingNumber\": \"<string>\",\n    \"bic\": \"<string>\",\n    \"bankName\": \"<string>\",\n    \"documentIdentifier\": \"<string>\",\n    \"accountHolder\": {\n      \"businessName\": \"<string>\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    },\n    \"address\": {\n      \"streetLine1\": \"<string>\",\n      \"streetLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"postalCode\": \"<string>\",\n      \"country\": \"US\"\n    }\n  },\n  \"targetBankAccountId\": \"<string>\",\n  \"sourceAmount\": 123,\n  \"targetAmount\": 123,\n  \"quoteId\": \"<string>\",\n  \"premiumSpread\": 123,\n  \"invoiceFile\": \"<string>\",\n  \"reference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/cross-ramp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"sourceCurrency\": \"MXN\",\n  \"targetCurrency\": \"USD\",\n  \"targetBankAccount\": {\n    \"accountIdentifier\": \"<string>\",\n    \"routingNumber\": \"<string>\",\n    \"bic\": \"<string>\",\n    \"bankName\": \"<string>\",\n    \"documentIdentifier\": \"<string>\",\n    \"accountHolder\": {\n      \"businessName\": \"<string>\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    },\n    \"address\": {\n      \"streetLine1\": \"<string>\",\n      \"streetLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"postalCode\": \"<string>\",\n      \"country\": \"US\"\n    }\n  },\n  \"targetBankAccountId\": \"<string>\",\n  \"sourceAmount\": 123,\n  \"targetAmount\": 123,\n  \"quoteId\": \"<string>\",\n  \"premiumSpread\": 123,\n  \"invoiceFile\": \"<string>\",\n  \"reference\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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
  }
}

POST

api

partner

cross-ramp

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/cross-ramp \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "sourceCurrency": "MXN",
  "targetCurrency": "USD",
  "targetBankAccount": {
    "accountIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "accountHolder": {
      "businessName": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "address": {
      "streetLine1": "<string>",
      "streetLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "US"
    }
  },
  "targetBankAccountId": "<string>",
  "sourceAmount": 123,
  "targetAmount": 123,
  "quoteId": "<string>",
  "premiumSpread": 123,
  "invoiceFile": "<string>",
  "reference": "<string>"
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/cross-ramp"

payload = {
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "sourceCurrency": "MXN",
    "targetCurrency": "USD",
    "targetBankAccount": {
        "accountIdentifier": "<string>",
        "routingNumber": "<string>",
        "bic": "<string>",
        "bankName": "<string>",
        "documentIdentifier": "<string>",
        "accountHolder": {
            "businessName": "<string>",
            "firstName": "<string>",
            "lastName": "<string>"
        },
        "address": {
            "streetLine1": "<string>",
            "streetLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "postalCode": "<string>",
            "country": "US"
        }
    },
    "targetBankAccountId": "<string>",
    "sourceAmount": 123,
    "targetAmount": 123,
    "quoteId": "<string>",
    "premiumSpread": 123,
    "invoiceFile": "<string>",
    "reference": "<string>"
}
headers = {
    "partner-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'partner-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '12a121ad-cbea-4ec4-9e0a-5c861e528bba',
    sourceCurrency: 'MXN',
    targetCurrency: 'USD',
    targetBankAccount: {
      accountIdentifier: '<string>',
      routingNumber: '<string>',
      bic: '<string>',
      bankName: '<string>',
      documentIdentifier: '<string>',
      accountHolder: {businessName: '<string>', firstName: '<string>', lastName: '<string>'},
      address: {
        streetLine1: '<string>',
        streetLine2: '<string>',
        city: '<string>',
        state: '<string>',
        postalCode: '<string>',
        country: 'US'
      }
    },
    targetBankAccountId: '<string>',
    sourceAmount: 123,
    targetAmount: 123,
    quoteId: '<string>',
    premiumSpread: 123,
    invoiceFile: '<string>',
    reference: '<string>'
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/cross-ramp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-api.capa.fi/api/partner/v2/cross-ramp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '12a121ad-cbea-4ec4-9e0a-5c861e528bba',
    'sourceCurrency' => 'MXN',
    'targetCurrency' => 'USD',
    'targetBankAccount' => [
        'accountIdentifier' => '<string>',
        'routingNumber' => '<string>',
        'bic' => '<string>',
        'bankName' => '<string>',
        'documentIdentifier' => '<string>',
        'accountHolder' => [
                'businessName' => '<string>',
                'firstName' => '<string>',
                'lastName' => '<string>'
        ],
        'address' => [
                'streetLine1' => '<string>',
                'streetLine2' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'postalCode' => '<string>',
                'country' => 'US'
        ]
    ],
    'targetBankAccountId' => '<string>',
    'sourceAmount' => 123,
    'targetAmount' => 123,
    'quoteId' => '<string>',
    'premiumSpread' => 123,
    'invoiceFile' => '<string>',
    'reference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/cross-ramp"

	payload := strings.NewReader("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"sourceCurrency\": \"MXN\",\n  \"targetCurrency\": \"USD\",\n  \"targetBankAccount\": {\n    \"accountIdentifier\": \"<string>\",\n    \"routingNumber\": \"<string>\",\n    \"bic\": \"<string>\",\n    \"bankName\": \"<string>\",\n    \"documentIdentifier\": \"<string>\",\n    \"accountHolder\": {\n      \"businessName\": \"<string>\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    },\n    \"address\": {\n      \"streetLine1\": \"<string>\",\n      \"streetLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"postalCode\": \"<string>\",\n      \"country\": \"US\"\n    }\n  },\n  \"targetBankAccountId\": \"<string>\",\n  \"sourceAmount\": 123,\n  \"targetAmount\": 123,\n  \"quoteId\": \"<string>\",\n  \"premiumSpread\": 123,\n  \"invoiceFile\": \"<string>\",\n  \"reference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("partner-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/cross-ramp")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"sourceCurrency\": \"MXN\",\n  \"targetCurrency\": \"USD\",\n  \"targetBankAccount\": {\n    \"accountIdentifier\": \"<string>\",\n    \"routingNumber\": \"<string>\",\n    \"bic\": \"<string>\",\n    \"bankName\": \"<string>\",\n    \"documentIdentifier\": \"<string>\",\n    \"accountHolder\": {\n      \"businessName\": \"<string>\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    },\n    \"address\": {\n      \"streetLine1\": \"<string>\",\n      \"streetLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"postalCode\": \"<string>\",\n      \"country\": \"US\"\n    }\n  },\n  \"targetBankAccountId\": \"<string>\",\n  \"sourceAmount\": 123,\n  \"targetAmount\": 123,\n  \"quoteId\": \"<string>\",\n  \"premiumSpread\": 123,\n  \"invoiceFile\": \"<string>\",\n  \"reference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/cross-ramp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"sourceCurrency\": \"MXN\",\n  \"targetCurrency\": \"USD\",\n  \"targetBankAccount\": {\n    \"accountIdentifier\": \"<string>\",\n    \"routingNumber\": \"<string>\",\n    \"bic\": \"<string>\",\n    \"bankName\": \"<string>\",\n    \"documentIdentifier\": \"<string>\",\n    \"accountHolder\": {\n      \"businessName\": \"<string>\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    },\n    \"address\": {\n      \"streetLine1\": \"<string>\",\n      \"streetLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"postalCode\": \"<string>\",\n      \"country\": \"US\"\n    }\n  },\n  \"targetBankAccountId\": \"<string>\",\n  \"sourceAmount\": 123,\n  \"targetAmount\": 123,\n  \"quoteId\": \"<string>\",\n  \"premiumSpread\": 123,\n  \"invoiceFile\": \"<string>\",\n  \"reference\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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
  }
}

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.

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 for the full contract.

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/cross-ramp \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <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 for the full flow.

Integration Flow

Create a user and complete KYC

POST /api/partner/v2/users, then KYC verification

Get a cross-ramp quote (optional)

POST /api/partner/v2/cross-ramp/quotes — locks the exchange rate

Create cross-ramp transaction

POST /api/partner/v2/cross-ramp (this endpoint)

User deposits source currency

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: “
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: , 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: , actual: )“
400	`QUOTE_EXPIRED`	”Quote has expired”
400	`BAD_REQUEST`	”Cannot create transaction: No supported banks configured for user with id: “
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.”

Authorizations

partner-api-key

string

header

required

API key for the affiliated partner performing the request.

Headers

Idempotency-Key

string

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 string length: 16 - 128

Example:

"550e8400-e29b-41d4-a716-446655440000"

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

targetBankAccountId

string

ID of an existing bank account to use as the target. Either targetBankAccount or targetBankAccountId must be provided.

sourceAmount

number

Amount of currency from source

targetAmount

number

Amount of currency that will be delivered

quoteId

string

Identifier for the quote to be used for the transaction.

premiumSpread

number

Premium spread percentage

targetCountry

enum<string>

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.

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,

CN,

HK

targetRail

enum<string>

Target payment rail for CN/HK destinations. Defaults to LOCAL; use SWIFT for an international wire.

Available options:

LOCAL,

SWIFT

invoiceFile

string

Base64-encoded PDF invoice. Required when the target bank account country is CN (China).

reference

string

Free-text remittance reference / memo (max 140 chars) forwarded to the payment provider. Supported across all currencies.

Maximum string length: 140

Response

Cross-ramp transaction created successfully. Returns the transaction details, including its id and current status.

success

boolean

Example:

true

data

object

Show child attributes

Execute Off-Ramp Create Cross-Ramp Quote

⌘I

​Idempotency

​Field Relationships

​Bank Account Requirements by Country

​China & Hong Kong Destinations

​Integration Flow

​Important Notes

​Use Cases

​Error Codes

​Common Errors

​Verified User Errors

​Endpoint-Specific Errors

Authorizations

Headers

Body

Response

Idempotency

Field Relationships

Bank Account Requirements by Country

China & Hong Kong Destinations

Integration Flow

Important Notes

Use Cases

Error Codes

Common Errors

Verified User Errors

Endpoint-Specific Errors