Upload Invoice

Upload Invoice / AWB

Version: 3.0.0

Upload your invoice or shipment (AWB) document after a successful payment. This is required to verify your transaction and comply with government and RBI regulations for cross-border or export payments.

When and Why to Use

Use the Transaction Document Upload API to attach supporting documents to a settled transaction:

1. Invoice upload — Attach a commercial invoice after capture (required for cross-border / export / PACB compliance).
2. AWB upload — Attach an airway bill / shipment document reference against the same order.
3. Order records — Keep merchant document references linked to the PayOrc transaction_id for reconciliation and regulatory verification.

Endpoint

Unlike Capture / Void / Refund, document upload uses a dedicated multipart endpoint (not action on /transaction).

Headers

Request Body

The request body must be sent as multipart/form-data.

Validations

Code Examples

Example 1 — Upload Invoice

curl --location 'https://api.payorc.com/orders/v1/transaction/documents' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--form 'transaction_id="1000063438"' \
--form 'document_type="INVOICE"' \
--form 'document_ref="INV-123456"' \
--form 'file=@"/path/to/invoice.pdf"'

Example 2 — Upload AWB

curl --location 'https://api.payorc.com/orders/v1/transaction/documents' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--form 'transaction_id="1000063438"' \
--form 'document_type="AWB"' \
--form 'document_ref="AWB-987654"' \
--form 'file=@"/path/to/awb.pdf"'

Example 3 — Node.js

const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('transaction_id', '1000063438');
form.append('document_type', 'INVOICE');
form.append('document_ref', 'INV-123456');
form.append('file', fs.createReadStream('/path/to/invoice.pdf'));

axios({
  method: 'post',
  url: 'https://api.payorc.com/orders/v1/transaction/documents',
  headers: {
    'merchant-key': '{merchant-key}',
    'merchant-secret': '{merchant-secret}',
    ...form.getHeaders()
  },
  data: form
})
  .then(response => console.log(JSON.stringify(response.data)))
  .catch(error => console.log(error.response?.data || error));

Example 4 — Python

import requests
import json

url = 'https://api.payorc.com/orders/v1/transaction/documents'

headers = {
    'merchant-key': '{merchant-key}',
    'merchant-secret': '{merchant-secret}'
}

data = {
    'transaction_id': '1000063438',
    'document_type': 'INVOICE',
    'document_ref': 'INV-123456'
}

with open('/path/to/invoice.pdf', 'rb') as f:
    files = {'file': f}
    response = requests.post(url, headers=headers, data=data, files=files)

print(json.dumps(response.json(), indent=2))

Response — Success (200)

{
    "status": "success",
    "code": "00",
    "message": "Uploaded Successfully",
    "data": {
        "m_order_id": "ORD-2024-001",
        "p_order_id": 1000063400,
        "transaction_id": "1000063438",
        "document_type": "INVOICE",
        "document_ref": "INV-123456",
        "psp": "PAYU",
        "file_name": "doc-1712345678-123456789.pdf"
    }
}

Response — Validation Error (400)

Returned by the Open API layer when request validation fails (before PSP upload).

{
    "message": "Document upload requires a captured transaction_id (CAPTURE / PARTIALLY_CAPTURE / SALE). AUTH transactions are not allowed.",
    "status": "fail",
    "code": "E0044"
}

Other common validation messages:

Response — Processing Error

Returned when the upload reaches connector processing (PSP / business rules). status is failed and code is the document-upload response code.

{
    "status": "failed",
    "code": "102",
    "message": "Invalid Transaction Status",
    "data": null
}

Duplicate invoice example:

{
    "status": "failed",
    "code": "201",
    "message": "Invoice already uploaded",
    "data": {
        "document_type": "INVOICE",
        "document_ref": "INV-123456",
        "p_order_id": 1000063400
    }
}

Response Codes

Document Upload Flow

CAPTURE / SALE completed
        |
        v
transaction_id (captured)
        |
        v
Prepare invoice or AWB file
        |
        v
POST /orders/v1/transaction/documents
  (multipart: transaction_id, document_type, document_ref, file)
        |
        v
Open API validates merchant ownership + captured state
        |
        v
PayOrc stores document + forwards to PSP (e.g. PayU)
        |
        v
Success (00) or failed response code

1. Complete payment and ensure the transaction is captured (or SALE).
2. Prepare the invoice or AWB file (≤ 2 MB; allowed types only).
3. Call POST /orders/v1/transaction/documents with merchant credentials.
4. On success (code: "00"), the document is associated with the order and available in console transaction details.

Important Notes

• Use multipart/form-data — this is not the JSON Capture/Void/Refund body.
• document_ref is required (invoice number or AWB id) and must be 3–100 characters.
• One invoice per order; multiple AWB uploads are allowed if each document_ref is unique.
• Do not hard-code merchant-secret in client-side apps.
• Use sandbox credentials when testing.

Related APIs

• Capture — Capture an authorization before uploading documents
• Fetch Order — Confirm transaction state and IDs
• Refund — Post-capture refunds (separate from document upload)

API Summary