Upload Documents

Document upload uses multipart/form-data. The request includes metadata fields plus a required file field named file. You need DOCUMENTS_WRITE to upload or delete documents. You need DOCUMENTS_READ to request signed download URLs.

Multipart fields

Field	Required?	Notes
`category`	Required	Document category, such as `INVOICE` or `CERTIFICATE_OF_INCORPORATION`.
`entityType`	Required	Entity the document belongs to, such as `CUSTOMER`, `BENEFICIARY`, or `PAYMENT`.
`entityId`	Required	ID of the entity. For pre-payment invoices, use `pending`.
`file`	Required	Binary file field. The field name must be exactly `file`.

Allowed MIME types are application/pdf, image/jpeg, image/png, and image/webp. The maximum file size is 20 MB.

Common entity targets

Flow	`entityType`	`entityId`
Customer KYB document	`CUSTOMER`	Existing customer ID
Payment invoice before payment creation	`PAYMENT`	`pending`
Payment document after payment creation, until the payment is approved	`PAYMENT`	Existing payment ID
Beneficiary document	`BENEFICIARY`	Existing beneficiary ID

Multipart request signing uses Nuvera’s canonical multipart body hash, not the raw multipart stream hash. See Multipart body hash before implementing uploads.

Upload a payment invoice

Payment creation requires at least one document with category INVOICE. If the payment does not exist yet, upload the invoice with entityType=PAYMENT and entityId=pending.

TOKEN="<signed-multipart-request-jwt>"

curl https://rest-api.nuvera.global/api/v1/documents \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -F "category=INVOICE" \
  -F "entityType=PAYMENT" \
  -F "entityId=pending" \
  -F "file=@./invoice.pdf;type=application/pdf"

Upload a customer document

Use the customer ID returned by POST /api/v1/customers.

TOKEN="<signed-multipart-request-jwt>"

curl https://rest-api.nuvera.global/api/v1/documents \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -F "category=CERTIFICATE_OF_INCORPORATION" \
  -F "entityType=CUSTOMER" \
  -F "entityId=<customer-id>" \
  -F "file=@./certificate.pdf;type=application/pdf"

Read or delete a document

Use GET /api/v1/documents/{id} to receive a signed download URL.

DOCUMENT_ID="<document-id>"
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/documents/$DOCUMENT_ID" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN"

Use DELETE /api/v1/documents/{id} only for documents that should no longer be used by a customer or payment flow. A document can be deleted only while the record it belongs to can still be changed: a payment document not yet attached to a payment (entityId=pending) or whose payment is in CORRECTION_NEEDED, a beneficiary document while the beneficiary is in CORRECTION_REQUESTED, and a customer document while the customer is in DRAFT or CORRECTION_REQUESTED. Every other delete is refused with 400, as is deleting a file that was sent as a support ticket or RFI attachment. An upload to an existing payment is accepted only while the payment is in PENDING_REVIEW or CORRECTION_NEEDED; in any other status it is refused with 400. For full document schemas, open the API Reference.

Getting Started

Partner API

Core Workflows

Operations

Upload Documents

Multipart fields

Common entity targets

Upload a payment invoice

Upload a customer document

Read or delete a document

​Multipart fields

​Common entity targets

​Upload a payment invoice

​Upload a customer document

​Read or delete a document

Multipart fields

Common entity targets

Upload a payment invoice

Upload a customer document

Read or delete a document