Skip to main content
POST
Upload Bulk Cross-Ramp Invoices
Uploads the commercial invoices for several transactions of a bulk cross-ramp that were created without one (status WAITING_INVOICE). Each invoice that is accepted moves its transaction to PENDING_FUNDS; read the transaction afterwards to get the sourceBankAccount the user needs to deposit.
Bulk cross-ramp is enabled on request, and so is this endpoint: until it is enabled for your environment it returns 404.
The response is 200 whenever the request itself is valid, even if some invoices failed. Always read every entry of results and handle each status.

Idempotency

This route does not support the Idempotency-Key header. It is naturally idempotent: an invoice for a transaction that already passed the invoice step is answered ALREADY_UPLOADED and nothing new is stored, so a failed or timed-out request can be sent again as is.

Request

  • invoices: between 1 and 25 entries per request, with no repeated transactionId.
  • transactionId: a transaction of this bulk, as returned when the bulk was created.
  • invoiceFile: Base64-encoded PDF, no whitespace, maximum 25 MB once decoded. Each file is parsed: an unreadable or encrypted PDF, or one with 0 or more than 500 pages, is an ERROR entry with INVALID_COMMERCIAL_INVOICE.
  • The Base64 text of all the invoices together must stay under about 25 MiB. Split larger sets across several requests.

Response

results has one entry per requested invoice, in request order. An ERROR entry carries the same codes as Upload Cross-Ramp Invoice: CROSS_RAMP_NOT_AWAITING_INVOICE, USER_NOT_VERIFIED_ERROR, SIGNATURE_REQUIREMENT_NOT_MET, INVALID_COMMERCIAL_INVOICE, COMMERCIAL_INVOICE_UPLOAD_FAILED, and INTERNAL_ERROR for an unexpected failure. Three more apply to bulks: The request still answers 200 for these: retry only the failed entries. If another invoice of the same bulk is being processed (it stays busy for about 2 seconds), the whole request fails with HTTP 503 CROSS_RAMP_BULK_INVOICE_BUSY and nothing is processed, not even entries that would have been rejected. Wait a second or two and resend the same request.

Rules

  • Entries are processed one by one, in order. A rejected invoice never blocks the others.
  • A malformed request, one that names a transaction that is not part of the bulk, or one that finds the bulk busy (503), processes nothing and answers with an HTTP error (see below).
  • The 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, in every country; for China and Hong Kong the supporting document sent to the provider is one PDF merged from all the bulk’s invoices.
  • A transaction can also receive its invoice on its own with Upload Cross-Ramp Invoice.
  • Replacing an invoice that was already uploaded is not supported.
See the Cross-Ramp guide for the full flow.

Error Codes

These errors apply to the whole request and process nothing. Errors of an individual invoice are returned inside results instead.

Common Errors

Endpoint-Specific Errors

Authorizations

partner-api-key
string
header
required

API key for the affiliated partner performing the request.

Path Parameters

bulkId
string<uuid>
required

Bulk ID returned when the bulk was created.

Body

application/json
invoices
object[]
required

Invoices to attach, one per transaction of the bulk. At most 25 entries, no repeated transactionId, and about 25 MiB of Base64 text in total.

Required array length: 1 - 25 elements

Response

The request was well-formed. Each entry of results is UPLOADED, ALREADY_UPLOADED or ERROR (with a code and message); some entries may fail while others succeed. A failed entry leaves its transaction unchanged and can be retried. An entry that would take the stored invoices of the bulk above 24 MiB decoded or 500 pages is an ERROR with code CROSS_RAMP_BULK_INVOICE_BUDGET_EXCEEDED or CROSS_RAMP_BULK_INVOICE_PAGES_EXCEEDED; CROSS_RAMP_BULK_INVOICE_SIZE_UNAVAILABLE is temporary, retry those entries after a short wait.

success
boolean
Example:

true

data
object