Skip to main content
POST
cURL
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.

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 same field the quote was created with:
    • quote targets USD (e.g. MXN→USD): use sourceAmount to fix what each transaction deposits, or targetAmount to fix the USD each beneficiary receives. With targetAmount, every payout must use the route the quote was priced for (targetCountry and targetRail);
    • quote starts from USD (e.g. USD→MXN): use 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 to continue only for China and Hong Kong. A bulk has one payout corridor. In a China or Hong Kong bulk, a transaction created without one is WAITING_INVOICE (on hold, no funding instructions), exactly like a single Create Cross-Ramp. The whole request, every invoice included, must stay under 25 MB, and the invoices of one bulk may total at most 24 MiB decoded and 500 pages (CROSS_RAMP_BULK_INVOICE_BUDGET_EXCEEDED or CROSS_RAMP_BULK_INVOICE_PAGES_EXCEEDED, 400, nothing is created). For any other country the invoice is optional: transactions are PENDING_FUNDS right away and an invoice you send is still stored. Each invoiceFile is parsed: an unreadable or encrypted PDF, or one with 0 or more than 500 pages, is rejected with INVALID_COMMERCIAL_INVOICE and nothing is created.

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, sized on sourceAmount: the fee comes out of that transaction’s USD payout.
  • Quote targets USD, sized on targetAmount: the USD payout stays exactly as sent, and the fee is added to that transaction’s deposit, converted at the quote’s rate. The deposits still add up to the quote’s sourceAmount.
  • 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.

Invoices

Send invoiceFile per transaction at creation, or attach the invoices afterwards:
  • A transaction with invoiceFile, or any transaction paying out to a country other than China or Hong Kong, is created PENDING_FUNDS, with its sourceBankAccount.
  • A China or Hong Kong transaction without an invoice is created WAITING_INVOICE and carries no sourceBankAccount. Do not ask the user to fund it yet.
  • Upload the missing invoices with Upload Bulk Cross-Ramp Invoices (up to 25 per request), or one by one with Upload Cross-Ramp Invoice. Each transaction then moves to PENDING_FUNDS; read it to get its sourceBankAccount.
  • The whole bulk waits (China and Hong Kong). A China or Hong Kong bulk is processed only when every transaction has its invoice and is funded. The single payout to the payment provider is placed at that moment, and the supporting document sent to the provider is one PDF merged from all the bulk’s transaction invoices.
  • Other countries do not wait for invoices. The bulk is processed once every transaction is funded. Invoices you sent are stored, but the provider ignores them.
  • Invoice budget. The stored invoices of one bulk may total at most 24 MiB decoded and 500 pages, counting those sent at creation and those uploaded later. An upload that would go over is rejected, nothing is stored and the transaction stays WAITING_INVOICE; retry with a smaller or shorter file. Cancelled transactions free their share. If an upload answers 503 (CROSS_RAMP_BULK_INVOICE_BUSY or CROSS_RAMP_BULK_INVOICE_SIZE_UNAVAILABLE), wait a second or two and retry; on the bulk invoices route a busy bulk fails the whole request.

Funding

Every transaction in the response that is PENDING_FUNDS has its own sourceBankAccount, and is funded with its own deposit for its own sourceAmount. A WAITING_INVOICE transaction (China and Hong Kong only) has none until its invoice is uploaded. 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 has its invoice and is funded. A transaction that is never funded, or never gets its invoice, holds the whole bulk; contact Capa support to resolve it.

Integration Flow

1

Create a user and complete KYC

2

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
3

Create the bulk

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

Upload any missing invoices

For transactions created without invoiceFile (WAITING_INVOICE): POST /api/partner/v2/cross-ramp/bulk//invoices
5

Fund each transaction

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

Track each transaction

Each transaction moves through the normal cross-ramp statuses, starting at WAITING_INVOICE when it was created without an invoice, 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

These are the errors this endpoint returns most often. Branch on code, not message, and handle codes you don’t recognize by their HTTP status. See Error Codes for the complete list.

Common Errors

Verified User Errors

Endpoint-Specific Errors

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 separately. A transaction with an invoiceFile, or paying out to a country other than China or Hong Kong, is PENDING_FUNDS; a China or Hong Kong one without an invoice is WAITING_INVOICE (on hold, no funding instructions) until its invoice is uploaded. A China or Hong Kong bulk is processed only when every transaction has its invoice and is funded; any other bulk is processed once funded, with no invoice needed. The single payout to the provider is placed at that moment. The invoices of one bulk may total at most 24 MiB decoded and 500 pages (CROSS_RAMP_BULK_INVOICE_BUDGET_EXCEEDED or CROSS_RAMP_BULK_INVOICE_PAGES_EXCEEDED, 400, nothing is created); an unreadable or encrypted PDF, or one with 0 or more than 500 pages, is rejected with INVALID_COMMERCIAL_INVOICE.

Required array length: 2 - 50 elements

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