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	`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. 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