Upload Document

Upload a supporting document

curl --request POST \
  --url https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/ \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Version: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --form file='@example-file' \
  --form type=offer_letter

import requests

url = "https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "type": "offer_letter" }
headers = {
    "X-Client-ID": "<api-key>",
    "X-Client-Secret": "<api-key>",
    "X-Merchant-ID": "<api-key>",
    "X-API-Version": "<api-key>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('type', 'offer_letter');

const options = {
  method: 'POST',
  headers: {
    'X-Client-ID': '<api-key>',
    'X-Client-Secret': '<api-key>',
    'X-Merchant-ID': '<api-key>',
    'X-API-Version': '<api-key>'
  }
};

options.body = form;

fetch('https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "X-API-Version: <api-key>",
    "X-Client-ID: <api-key>",
    "X-Client-Secret: <api-key>",
    "X-Merchant-ID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Client-ID", "<api-key>")
	req.Header.Add("X-Client-Secret", "<api-key>")
	req.Header.Add("X-Merchant-ID", "<api-key>")
	req.Header.Add("X-API-Version", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/")
  .header("X-Client-ID", "<api-key>")
  .header("X-Client-Secret", "<api-key>")
  .header("X-Merchant-ID", "<api-key>")
  .header("X-API-Version", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Client-ID"] = '<api-key>'
request["X-Client-Secret"] = '<api-key>'
request["X-Merchant-ID"] = '<api-key>'
request["X-API-Version"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Document uploaded",
  "data": {
    "ref": "8207383264",
    "type": "offer_letter"
  }
}

POST

payments

{payment_id}

documents

Upload a supporting document

curl --request POST \
  --url https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/ \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Version: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --form file='@example-file' \
  --form type=offer_letter

import requests

url = "https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "type": "offer_letter" }
headers = {
    "X-Client-ID": "<api-key>",
    "X-Client-Secret": "<api-key>",
    "X-Merchant-ID": "<api-key>",
    "X-API-Version": "<api-key>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('type', 'offer_letter');

const options = {
  method: 'POST',
  headers: {
    'X-Client-ID': '<api-key>',
    'X-Client-Secret': '<api-key>',
    'X-Merchant-ID': '<api-key>',
    'X-API-Version': '<api-key>'
  }
};

options.body = form;

fetch('https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "X-API-Version: <api-key>",
    "X-Client-ID: <api-key>",
    "X-Client-Secret: <api-key>",
    "X-Merchant-ID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Client-ID", "<api-key>")
	req.Header.Add("X-Client-Secret", "<api-key>")
	req.Header.Add("X-Merchant-ID", "<api-key>")
	req.Header.Add("X-API-Version", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/")
  .header("X-Client-ID", "<api-key>")
  .header("X-Client-Secret", "<api-key>")
  .header("X-Merchant-ID", "<api-key>")
  .header("X-API-Version", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-pacb-uat.eximpe.com/pg/payments/{payment_id}/documents/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Client-ID"] = '<api-key>'
request["X-Client-Secret"] = '<api-key>'
request["X-Merchant-ID"] = '<api-key>'
request["X-API-Version"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"type\"\r\n\r\noffer_letter\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Document uploaded",
  "data": {
    "ref": "8207383264",
    "type": "offer_letter"
  }
}

Overview

Uploads one file for a B2B services payment and answers with a ref. What you do with that ref depends on which of the two document steps you are in:

You uploaded	You then	With
the commercial invoice	send the `ref` under its checklist code	Submit Verification Details
a delivery proof, after the payment settles	send the `ref` in the settlement submission	Submit Settlement Documents

{ "documents": [{ "code": "invoice", "ref": "8207383264" }] }

Two calls, not one. Uploading a file does not answer a requirement; it stores a file. The requirement is answered when a later call names the ref. That separation is what lets the same upload endpoint serve both the verification step and the post-settlement one — and it is why neither step needs a draft of its own. An upload is durable, so a ref you are holding is your draft.

Classify the payment first

The type you may send depends on which flow the payment is in, so the payment has to be in one. A VBA credit arrives unclassified, and until you have sent its business_model and purpose_code through Submit Verification Details an upload is refused:

{
  "success": false,
  "error": {
    "code": 40359,
    "message": "Invalid verification request.",
    "details": "Invalid verification request. This payment has no verification checklist, so there is no set of document types to accept; send the order's business model and purpose code first."
  }
}

Send the pair once and every later upload on that payment is routed for you. Get Verification Requirements tells you whether a payment is still waiting on it.

The message names no flow, because there is not one yet. Every other refusal on a classified services payment reads Invalid B2B services request. This one cannot: the classification is exactly what is missing, so naming a flow would be a guess. The code is 40359 either way.

The request

multipart/form-data, two parts:

Part
`file`	The document itself.
`type`	What kind of document it is — one of the two codes below.

The path resolves the payment before anything is stored, under the same ownership rules as the verification endpoint: your own payments, and your sub-merchants’.

PSPs send X-Merchant-ID, naming the settling sub-merchant, exactly as on the verification endpoints.

Document types

B2B services uses two, and takes no others:

`type`		Where it goes
`invoice`	Commercial invoice	The verification checklist
`delivery_proof`	Evidence the service was delivered — a signed acceptance note, a milestone sign-off, a delivery confirmation, a timesheet	The post-settlement document set

The type decides where the file is stored, so it also decides which call can cite the resulting ref: an invoice ref is citable on Submit Verification Details, a delivery_proof ref in refs on Submit Settlement Documents. Cite one on the other call and it reads as unknown — ERR_B2B_SETTLEMENT_001 on the settlement submit, Unknown document ref. on the verification one. A type outside these two — including document codes other flows define, such as passport — is refused:

{
  "success": false,
  "error": {
    "code": 40359,
    "message": "Invalid B2B services request.",
    "details": { "type": "Unknown document type for this payment's flow; send one of: delivery_proof, invoice." }
  }
}

delivery_proof is not a checklist item. It never appears in Get Verification Requirements, because it is owed after settlement rather than before it. Do not go looking for it there.

The file

Validated on upload, so a bad file fails here rather than at submit time.


Extensions	`pdf` · `png` · `jpg` · `jpeg` · `docx` · `xlsx` · `csv`
Maximum size	10 MB
Maximum file name	100 characters, extension included
Encrypted PDFs	Rejected — a password-protected file cannot be read by anyone who has to review it

A file name over 100 characters answers 500, not 400. The envelope carries 40359, and details is a stringified object holding the real reason — File name must be less than 100 characters., code 40296. It is your input that is wrong, not our service, so rename the file and upload it again rather than retrying. Truncate long names before uploading and you will never see it.

The response

201, with the ref:

{
  "success": true,
  "message": "Document uploaded",
  "data": {
    "ref": "8207383264",
    "type": "invoice"
  }
}

string

required

The stored document’s identifier. Send it as documents[].ref on the verification submit, or in refs on the settlement submit.The file is stored against the payment in the path, so the ref is only citable from that payment. A ref from one of your other payments reads as unknown, exactly as a made-up one does — the answer never distinguishes the two.

string

required

Echoes the type you sent.

Uploading more than one

Both types accumulate. Every upload adds its own row and returns its own ref; nothing supersedes anything, and an earlier ref stays valid. Invoices. A payment may carry several — an amended invoice beside the original, or a job billed across two. You only cite the invoice code once on Submit Verification Details; the citation names the code, so every invoice on the payment is filed when the set completes. A second invoice needs no citation of its own.

There is no way to remove an invoice you uploaded by mistake. It stays on the payment and is filed with the rest. Upload only what you want ops to see.

Delivery proofs. Collect them as they arrive, including before the payment settles. Nothing is filed until you submit, and refs on that call is the whole set — a proof you would rather not file is one you leave out, and it is dropped. That is the settlement step’s way of undoing an upload; the verification step has no equivalent. Once the settlement set is submitted it is locked. A further delivery_proof upload is refused with ERR_B2B_SETTLEMENT_002.

No waivers on this flow

Some checklists let a document be discharged with a waiver_reason instead of a file. The B2B services checklist has no waivable item — the commercial invoice is required, and there is nothing to waive. A waiver_reason sent on this flow is a 400.

Get Verification Requirements

What this payment actually needs.

Submit Verification Details

Where the ref is bound to a checklist code.

Submit Settlement Documents

Where delivery_proof refs are filed, after settlement.

B2B Services Verification

The whole flow, in order.

Authorizations

X-Client-ID

string

header

required

Client Application ID - Your unique application identifier used to authenticate API requests. You can find your Client ID in the Developer Settings section of the merchant dashboard.

X-Client-Secret

string

header

required

Client Secret Key - Your secret key used alongside the Client ID for secure authentication. Keep this confidential and never expose it in client-side code. Available in the Developer Settings section of the merchant dashboard.

X-Merchant-ID

string

header

required

Merchant Identifier - The unique ID for the merchant account. This is required for PSP (Payment Service Provider) merchants who manage multiple merchant accounts. You can find merchant IDs in the Merchant Management section of the dashboard.

X-API-Version

string

header

required

API Version - Specifies which version of the API to use (e.g., '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which API version your integration uses. Default version information is available in the Developer Settings.

Path Parameters

payment_id

string

required

UID of the payment the document is for.

Body

multipart/form-data

file

required

The document file. Allowed extensions: pdf, png, jpg, jpeg, docx, xlsx, csv. Maximum 10 MB. Password-protected PDFs are rejected.

type

enum<string>

required

Document type — one of the codes the checklists ask for, so the value you upload under is the value you submit under. Read the ones this payment actually needs from Get Verification Requirements rather than mapping this list into your code: it is the complete set any checklist can ask for, and it grows as the regulatory matrix is revised. delivery_proof is the one type here that no checklist asks for: it is a post-settlement compliance document, uploaded through this endpoint and then filed by ref through Submit post-settlement documents.

Available options:

offer_letter,

passport,

student_id_or_visa,

student_id,

fee_invoice,

passenger_list,

traveller_passports,

traveller_visas,

ticket,

invoice,

relationship_declaration,

delivery_proof

Example:

"offer_letter"

Response

Document uploaded.

success

boolean

Example:

true

message

string

Example:

"Document uploaded"

data

object

Show child attributes

Order

Payment

Merchant

Settlement

Refund

Virtual Bank Accounts

LRS

B2B Services

Webhooks

Overview

Classify the payment first

The request

Document types

The file

The response

Uploading more than one

No waivers on this flow

Get Verification Requirements

Submit Verification Details

Submit Settlement Documents

B2B Services Verification

Authorizations

Path Parameters

Body

Response

​Overview

​Classify the payment first

​The request

​Document types

​The file

​The response

​Uploading more than one

​No waivers on this flow

​Related

Get Verification Requirements

Submit Verification Details

Submit Settlement Documents

B2B Services Verification

Authorizations

Path Parameters

Body

Response

Overview

Classify the payment first

The request

Document types

The file

The response

Uploading more than one

No waivers on this flow

Related