Create Bulk Cross-Ramp

cURL

curl --request POST \
  --url https://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "quoteId": "12a121ad-cbea-4ec4-9e0a-5c861e528bbb",
  "transactions": [
    {
      "sourceAmount": 4000,
      "targetAmount": 200,
      "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>",
      "receiverId": "<string>",
      "invoiceFile": "<string>",
      "reference": "<string>"
    }
  ]
}
'

import requests

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

payload = {
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "quoteId": "12a121ad-cbea-4ec4-9e0a-5c861e528bbb",
    "transactions": [
        {
            "sourceAmount": 4000,
            "targetAmount": 200,
            "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>",
            "receiverId": "<string>",
            "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',
    quoteId: '12a121ad-cbea-4ec4-9e0a-5c861e528bbb',
    transactions: [
      {
        sourceAmount: 4000,
        targetAmount: 200,
        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>',
        receiverId: '<string>',
        invoiceFile: '<string>',
        reference: '<string>'
      }
    ]
  })
};

fetch('https://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk', 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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk",
  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',
    'quoteId' => '12a121ad-cbea-4ec4-9e0a-5c861e528bbb',
    'transactions' => [
        [
                'sourceAmount' => 4000,
                'targetAmount' => 200,
                '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>',
                'receiverId' => '<string>',
                '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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk"

	payload := strings.NewReader("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"quoteId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bbb\",\n  \"transactions\": [\n    {\n      \"sourceAmount\": 4000,\n      \"targetAmount\": 200,\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      \"receiverId\": \"<string>\",\n      \"invoiceFile\": \"<string>\",\n      \"reference\": \"<string>\"\n    }\n  ]\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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"quoteId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bbb\",\n  \"transactions\": [\n    {\n      \"sourceAmount\": 4000,\n      \"targetAmount\": 200,\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      \"receiverId\": \"<string>\",\n      \"invoiceFile\": \"<string>\",\n      \"reference\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"quoteId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bbb\",\n  \"transactions\": [\n    {\n      \"sourceAmount\": 4000,\n      \"targetAmount\": 200,\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      \"receiverId\": \"<string>\",\n      \"invoiceFile\": \"<string>\",\n      \"reference\": \"<string>\"\n    }\n  ]\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_FUNDS",
    "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

bulk

cURL

curl --request POST \
  --url https://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "quoteId": "12a121ad-cbea-4ec4-9e0a-5c861e528bbb",
  "transactions": [
    {
      "sourceAmount": 4000,
      "targetAmount": 200,
      "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>",
      "receiverId": "<string>",
      "invoiceFile": "<string>",
      "reference": "<string>"
    }
  ]
}
'

import requests

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

payload = {
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "quoteId": "12a121ad-cbea-4ec4-9e0a-5c861e528bbb",
    "transactions": [
        {
            "sourceAmount": 4000,
            "targetAmount": 200,
            "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>",
            "receiverId": "<string>",
            "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',
    quoteId: '12a121ad-cbea-4ec4-9e0a-5c861e528bbb',
    transactions: [
      {
        sourceAmount: 4000,
        targetAmount: 200,
        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>',
        receiverId: '<string>',
        invoiceFile: '<string>',
        reference: '<string>'
      }
    ]
  })
};

fetch('https://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk', 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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk",
  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',
    'quoteId' => '12a121ad-cbea-4ec4-9e0a-5c861e528bbb',
    'transactions' => [
        [
                'sourceAmount' => 4000,
                'targetAmount' => 200,
                '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>',
                'receiverId' => '<string>',
                '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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk"

	payload := strings.NewReader("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"quoteId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bbb\",\n  \"transactions\": [\n    {\n      \"sourceAmount\": 4000,\n      \"targetAmount\": 200,\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      \"receiverId\": \"<string>\",\n      \"invoiceFile\": \"<string>\",\n      \"reference\": \"<string>\"\n    }\n  ]\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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bba\",\n  \"quoteId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bbb\",\n  \"transactions\": [\n    {\n      \"sourceAmount\": 4000,\n      \"targetAmount\": 200,\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      \"receiverId\": \"<string>\",\n      \"invoiceFile\": \"<string>\",\n      \"reference\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"quoteId\": \"12a121ad-cbea-4ec4-9e0a-5c861e528bbb\",\n  \"transactions\": [\n    {\n      \"sourceAmount\": 4000,\n      \"targetAmount\": 200,\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      \"receiverId\": \"<string>\",\n      \"invoiceFile\": \"<string>\",\n      \"reference\": \"<string>\"\n    }\n  ]\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_FUNDS",
    "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 several cross-ramp transactions from one cross-ramp quote, for a single verified user paying several beneficiaries. The quote’s exchange is executed once, for the total, and each transaction is then funded and paid out on its own.

Bulk cross-ramp is enabled on request. Ask your Capa contact to enable it for your sandbox and production environments; until then this endpoint returns 404.

Idempotency

Retry safely without creating a duplicate bulk: 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://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <partner-api-key>' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --data '{
    "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
    "quoteId": "12a121ad-cbea-4ec4-9e0a-5c861e528bbb",
    "transactions": [
      { "sourceAmount": 4000, "targetBankAccountId": "8d1f0c3e-2b7a-4e55-9c1d-6a4f2e9b7c10" },
      { "sourceAmount": 6000, "targetBankAccountId": "c2a9e4b1-5f3d-4a8e-8b6c-1d7e0f9a2b34", "reference": "INV-2026-114" }
    ]
  }'

Field Relationships

One quote for the total. Create it with Create Cross-Ramp Quote for the sum of all the transactions, with bulkTransactionCount set to the number of transactions. Exactly one side of the quote must be USD: for example MXN→USD (including USD delivered to CN/HK) or USD→MXN. A quote where neither side is USD is rejected.
The quote fixes the currencies and the source route, as on the single endpoint with a quoteId. The body has no sourceCurrency, targetCurrency, premiumSpread or forwardingDays.
Size every transaction on the quote’s non-USD side, using the same field the quote was created with:
- quote targets USD (e.g. MXN→USD): create the quote with sourceAmount, and give every transaction a sourceAmount;
- quote starts from USD (e.g. USD→MXN): create the quote with targetAmount, and give every transaction a targetAmount.
The amounts must add up exactly to the quote’s amount on that side.
2 to 50 transactions per bulk. Every transaction gives either targetBankAccount or targetBankAccountId.
Beneficiaries may differ. One bulk can pay, for example, US and CN beneficiaries under the same MXN→USD quote. targetCountry, targetRail, invoiceFile and reference work per transaction exactly as on Create Cross-Ramp.
invoiceFile is required for CN and HK beneficiaries. The whole request, every invoice included, must stay under 25 MB.

Fees

Each transaction pays the fixed fee of its own USD leg, for its own route (for example a CN SWIFT payout and a US payout differ). The quote already nets one such fee per transaction, priced for the quote’s route, because you set bulkTransactionCount. When every transaction uses that route, their payouts add up exactly to the quote’s targetAmount:

Quote targets USD: the fee comes out of that transaction’s USD payout.
Quote starts from USD: the fee is added to that transaction’s USD deposit.

The fee of the non-USD leg, which runs once for the total, is shared across the transactions in proportion to their amounts. Each transaction in the response shows its own sourceAmount, targetAmount and fees.

Funding

Every transaction in the response has its own sourceBankAccount, and is funded with its own deposit for its own sourceAmount. For MXN deposits by SPEI, put the transaction’s sourceBankAccount.message (its id) in the concepto, so each deposit is matched to the right transaction. Nothing is executed with the liquidity provider until every transaction in the bulk is funded. A transaction that is never funded holds the whole bulk; contact Capa support to resolve it.

Integration Flow

Create a user and complete KYC

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

Get one cross-ramp quote for the total

POST /api/partner/v2/cross-ramp/quotes, priced on the non-USD side, with bulkTransactionCount set to the number of transactions

Create the bulk

POST /api/partner/v2/cross-ramp/bulk (this endpoint), before the quote expires

Fund each transaction

One deposit per transaction to its sourceBankAccount. For SPEI, use its message as the concepto.

Track each transaction

Each transaction moves through the normal cross-ramp statuses and sends its own webhooks.

Important Notes

User must be KYC-verified before creating transactions.
Each transaction is a normal cross-ramp. It has its own id, statuses, webhooks and proof of payment, and it appears in transaction listings like any other cross-ramp. Group them with the bulkId and quoteId returned here.
Amount limits apply to each transaction, including the 10–10,000 USD range for USD delivered to CN/HK.
The quote is consumed by the bulk. It cannot be reused for another bulk or a single cross-ramp.

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.”
404	—	“Not Found” — bulk cross-ramp is not enabled for this environment yet

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” — the failing rule is in `errors[].message`, e.g. “Every transaction must set the same one of sourceAmount or targetAmount”, “invoiceFile is required when target bank account country is CN or HK”, or 2–50 transactions, one bank account per transaction, a base64 `invoiceFile`
400	`BAD_REQUEST`	”Bulk cross-ramp requires USD on the source or the target side of the quote”
400	`BAD_REQUEST`	”The quote was priced on {sourceAmount\|targetAmount}; size every transaction on the same side”
400	`BAD_REQUEST`	”Size the quote and every transaction on {sourceAmount\|targetAmount}; each transaction’s USD amount absorbs its own fee”
400	`BAD_REQUEST`	”This quote cannot be used for a bulk; request a new quote”
400	`BAD_REQUEST`	”This quote was priced for {n} transactions; request a quote with bulkTransactionCount set to {m}“
400	`BAD_REQUEST`	”Request the quote with bulkTransactionCount set to {m}, the number of transactions”
400	`BAD_REQUEST`	”The transactions’ {sourceAmount\|targetAmount} must add up to the quote’s (expected: {expected}, actual: {actual})“
400	`BAD_REQUEST`	”Transaction at index {index} is too small to carry a share of the quote”
400	`BAD_REQUEST`	”Transaction at index {index} has an amount too large to process”
400	`BAD_REQUEST`	”A transaction’s USD amount does not cover its own payment fee; use a larger amount”
400	`BAD_REQUEST`	”Provided quoteId is not a CROSS_RAMP quote”
400	`BAD_REQUEST`	”Cross-ramp requires an OTC quote; request a new quote”
400	`QUOTE_EXPIRED`	”Quote has expired”
403	`FORBIDDEN`	”The quote belongs to a different partner.”

A transaction can also fail with any error of Create Cross-Ramp, such as an invalid or foreign bank account. In that case nothing is created and the quote is consumed, so request a new quote before retrying.

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"

quoteId

string

required

A cross-ramp quote for the total of all the transactions. Its currencies and source route apply to every transaction. Exactly one side of the quote must be USD.

Example:

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

transactions

object[]

required

One entry per beneficiary. Each becomes its own cross-ramp, funded and paid out separately.

Required array length: 2 - 50 elements

Show child attributes

Response

Bulk created. Returns one cross-ramp per requested transaction, in request order, each funded through its own sourceBankAccount.

success

boolean

Example:

true

data

object

Show child attributes

​Idempotency

​Field Relationships

​Fees

​Funding

​Integration Flow

​Important Notes

​Error Codes

​Common Errors

​Verified User Errors

​Endpoint-Specific Errors

Authorizations

Headers

Body

Response

Idempotency

Field Relationships

Fees

Funding

Integration Flow

Important Notes

Error Codes

Common Errors

Verified User Errors

Endpoint-Specific Errors