Document upload

Attaching supporting documents to a payout is strongly recommended for high-value transactions or payments to higher-risk corridors. Depending on the compliance conditions agreed during your approval, it may be mandatory for downstream payment flows to upload client documents (i.e. KYC docs) at point of payment, or your terms and conditions with your customer.

Document upload follows a three-step process:

1. Generate a pre-signed upload link
2. Upload the document to that link
3. Include the document key when submitting your payout request

Step 1 — Generate an upload link

Call the Generate Upload Link endpoint to obtain a pre-signed URL for your document.

{
  "fileName": "payment_receipt.pdf"
}

Response:

{
  "link": "https://your-upload-link.s3.amazonaws.com/...",
  "key": "unique-s3-key-for-your-document"
}

Step 2 — Upload the document

Using the link returned in Step 1, perform a PUT request with the document as the request body.

PUT {link}

A 200 OK response confirms the upload was successful.

⚠️

Note: The upload link is valid for 10 minutes. If it expires, return to

Step 1 to generate a new link.

Step 3 — Attach the document to your payout

Include the supportingDocS3Key from Step 1 in your payout request. Note that purposeId becomes mandatory when a supporting document is attached.

For the Exchange & Payout flow:

See the Make Payment endpoint for the full request reference.

{
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 3529,
  "sourceAmount": 5,
  "purposeId": 14,
  "targetAccountId": 3786,
  "paymentId": "9dc2ee8a-15cd-44e5-8ba8-b757c7a3b141",
  "supportingDocS3Key": "unique-s3-key-for-your-document",
  "sender": {
    // sender details — see Sender object guide
  }
}

For the Payout API (two-step) flow:

See the Create Payment Request endpoint for the full request reference.

{
  "beneficiaryId": 278,
  "purposeId": 12,
  "amount": 100,
  "walletId": 1,
  "clientReference": "your-reference",
  "paymentId": "a7600e0e-a973-4d26-b15c-89de5836e900",
  "supportingDocS3Key": "unique-s3-key-for-your-document"
}

The transaction response will include a supportingDocument field containing a pre-signed download link to view the uploaded file.