Skip to main content
POST
Upload Cross-Ramp Invoice
Uploads the commercial invoice for a cross-ramp that was created without one (status WAITING_INVOICE). On success the cross-ramp moves to PENDING_FUNDS. The response returns id, status and updatedAt; read the cross-ramp afterwards to get sourceBankAccount, the funding instructions the user needs to deposit the source currency.
The invoice is optional at creation for every country, but nothing is paid out without it. If you did not send invoiceFile in Create Cross-Ramp, the cross-ramp waits in WAITING_INVOICE and no funding instructions are returned until this call succeeds; the payout to the provider is placed after the upload.

Idempotency

This route does not support the Idempotency-Key header. It is naturally idempotent: repeating an upload that already succeeded returns 200 with the current status and creates nothing new.

Rules

  • The cross-ramp must be in WAITING_INVOICE.
  • invoiceFile: Base64-encoded PDF, maximum 25 MB once decoded. The file is parsed as a real PDF: an unreadable or encrypted file, or one with 0 or more than 500 pages, is rejected with INVALID_COMMERCIAL_INVOICE.
  • A valid PDF is accepted automatically (no manual review) and moves the cross-ramp to PENDING_FUNDS.
  • The user must be verified and have no outstanding beneficial-owner signature; otherwise the request is rejected with 403 and the cross-ramp stays WAITING_INVOICE.
  • For a transaction of a bulk, the stored invoices of the bulk may total at most 24 MiB decoded and 500 pages. A file that would go over is rejected with 400 CROSS_RAMP_BULK_INVOICE_BUDGET_EXCEEDED (size) or CROSS_RAMP_BULK_INVOICE_PAGES_EXCEEDED (pages); nothing is stored and the transaction stays WAITING_INVOICE, so you can retry with a smaller file.
  • For a bulk transaction, a 503 (CROSS_RAMP_BULK_INVOICE_BUSY or CROSS_RAMP_BULK_INVOICE_SIZE_UNAVAILABLE) is temporary and nothing is stored. CROSS_RAMP_BULK_INVOICE_BUSY means another invoice of the same bulk kept the bulk busy for about 2 seconds: wait a second or two and repeat the upload.
  • If storing the file fails you get a retryable 500 and the status stays WAITING_INVOICE. Retry with the same file.
  • A WAITING_INVOICE cross-ramp can also be cancelled with the cancel endpoint. There is no expiry.
  • Replacing an invoice that was already uploaded is not supported.
  • There is no dedicated upload webhook event; see Transaction Events.
See the Cross-Ramp guide for the full flow.

Error Codes

Common Errors

Endpoint-Specific Errors

Authorizations

partner-api-key
string
header
required

API key for the affiliated partner performing the request.

Path Parameters

id
string<uuid>
required

Cross-ramp transaction ID returned when the cross-ramp was created.

Body

application/json
invoiceFile
string
required

Base64-encoded PDF commercial invoice. Maximum 25 MB once decoded. Parsed as a real PDF: an unreadable or encrypted file, or one with 0 or more than 500 pages, is rejected with INVALID_COMMERCIAL_INVOICE.

Response

Invoice accepted. The cross-ramp is now PENDING_FUNDS. Repeating the upload after success returns 200 with the current status.

success
boolean
Example:

true

data
object