> ## 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 Bulk Cross-Ramp > Create several cross-ramps for one user from a single quote, each funded and paid out on its own. 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. > [!NOTE] > > 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](https://docs.capa.fi/docs/idempotency.md) for the full contract. ```shell theme={null} curl --request POST \ --url https://api.sandbox.capa.fi/api/partner/v2/cross-ramp/bulk \ --header 'Content-Type: application/json' \ --header '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](https://docs.capa.fi/reference/crossramppartnerv2controller_createpartnercrossrampquote.md) 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](https://docs.capa.fi/reference/crossramppartnerv2controller_createpartnercrossramp.md#china--hong-kong-destinations). * **`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 **1. Create a user and complete KYC** [POST /api/partner/v2/users](https://docs.capa.fi/reference/userpartnercontrollerv2_createuser.md), then [KYC verification](https://docs.capa.fi/reference/userpartnercontrollerv2_createverificationlink.md) **2. Get one cross-ramp quote for the total** [POST /api/partner/v2/cross-ramp/quotes](https://docs.capa.fi/reference/crossramppartnerv2controller_createpartnercrossrampquote.md), 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. Fund each transaction** One deposit per transaction to its `sourceBankAccount`. For SPEI, use its `message` as the concepto. **5. Track each transaction** Each transaction moves through the normal [cross-ramp statuses](https://docs.capa.fi/docs/cross-ramp.md#transaction-status-progression) and sends its own [webhooks](https://docs.capa.fi/docs/transaction-events.md#cross-ramp-events). *** ## 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](https://docs.capa.fi/reference/crossramppartnerv2controller_createpartnercrossramp.md#error-codes), 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. ## OpenAPI ````yaml reference/openapi/CrossRampPartnerV2Controller_createPartnerCrossRampBulk.json POST /api/partner/v2/cross-ramp/bulk 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://api.sandbox.capa.fi - url: https://api.capa.fi security: [] paths: /api/partner/v2/cross-ramp/bulk: post: tags: - cross-ramp operationId: CrossRampPartnerV2Controller_createPartnerCrossRampBulk 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 required: - userId - quoteId - transactions properties: userId: type: string description: User's identifier example: 12a121ad-cbea-4ec4-9e0a-5c861e528bba quoteId: type: string description: >- 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: type: array minItems: 2 maxItems: 50 description: >- One entry per beneficiary. Each becomes its own cross-ramp, funded and paid out separately. items: type: object properties: sourceAmount: type: number description: >- This transaction's amount in the source currency. Use it when the quote targets USD (e.g. MXN→USD). Every transaction must use the same field, and the amounts must add up exactly to the quote's sourceAmount. example: 4000 targetAmount: type: number description: >- This transaction's amount in the target currency. Use it when the quote starts from USD (e.g. USD→MXN). Every transaction must use the same field, and the amounts must add up exactly to the quote's targetAmount. example: 200 targetBankAccount: type: object description: >- Beneficiary bank account, same shape as the single Create Cross-Ramp endpoint. Provide this or targetBankAccountId. 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 pay out to. Provide this or targetBankAccount. receiverId: type: string description: >- Optional identifier of an existing receiver to associate with this transaction. invoiceFile: type: string description: >- Base64-encoded PDF invoice. Required when the target bank account country is CN or HK. The whole request, every invoice included, must stay under 25 MB. reference: type: string maxLength: 140 description: >- Free-text remittance reference / memo (max 140 chars) forwarded to the payment provider. Supported across all currencies. 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. responses: '201': description: >- Bulk created. Returns one cross-ramp per requested transaction, in request order, each funded through its own sourceBankAccount. content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: bulkId: type: string description: >- Bulk identifier, shared by every transaction it created example: 3f6c1e0a-6d0b-4d4e-9a52-1b2f7d6e8c11 quoteId: type: string description: >- The quote every transaction in the bulk was priced with example: 12a121ad-cbea-4ec4-9e0a-5c861e528bbb transactions: type: array description: >- One cross-ramp per requested transaction, in request order. Same shape as the Create Cross-Ramp response. items: 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_FUNDS 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_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 '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} 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. 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: 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.