Upload Invoice by URL

Share an invoice or AWB document URL against a captured PayOrc transaction — PayOrc fetches the file for the PSP and stores only the URL for portal viewing.

Upload Invoice / AWB by URL

Version: 3.0.0

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

PayOrc downloads the document temporarily to forward it to the PSP, does not keep a permanent copy on PayOrc servers, and stores the URL so you can open it from the merchant portal.

Prerequisite: Same as Upload Invoice (file) — use a captured transaction_id (CAPTURE / PARTIALLY_CAPTURE / SALE, status AUTHORISED, not voided). For PayU, the MID must be PACB-enabled.

When and Why to Use

Use this API when the invoice/AWB already lives on your own hosting (CDN, S3, merchant site) and you prefer to pass a URL instead of multipart upload.

Invoice by URL — Share a hosted commercial invoice after capture.
AWB by URL — Share a hosted airway bill / shipment document.
Portal View — The stored URL is shown as the View link in transaction details.

The URL must be publicly reachable over HTTPS by PayOrc servers. HTTP and private/VPN-only links are rejected.

Endpoint

Method	URL
POST	`https://api.payorc.com/orders/v1/transaction/documents/url`

Please use the test credentials for sandbox testing. Request body is JSON (not multipart).

Headers

Field	Type	Required	Description
`merchant-key`	String	Yes	Your merchant API key
`merchant-secret`	String	Yes	Your merchant API secret
`Content-Type`	String	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`transaction_id`	String	Yes	Captured PayOrc transaction ID
`document_type`	String	Yes	`INVOICE` or `AWB`
`document_ref`	String	Yes	Invoice number or AWB reference. Min 3, max 100 characters.
`document_url`	String	Yes	Absolute HTTPS URL to the document. Max 2048 characters. HTTP is not allowed.

Validations

Rule	Detail
Ownership	`transaction_id` must belong to the authenticated merchant
Transaction state	Type ∈ `CAPTURE`, `PARTIALLY_CAPTURE`, `SALE`; status `AUTHORISED`; not voided
`document_type`	Only `INVOICE` or `AWB`
`document_ref`	Required; 3–100 characters
`document_url`	Required; HTTPS only; max 2048 characters
Downloaded file types	`.pdf`, `.doc`, `.docx`, `.jpg`, `.jpeg` (from URL path or `Content-Type`)
Downloaded file size	Maximum 2 MB
Invoice duplicate	At most one `INVOICE` per order
AWB duplicate	Same `document_ref` cannot be uploaded twice as `AWB` for the same order
PayU PACB	PayU MIDs must have PACB enabled

Code Examples

Example 1 — Invoice by URL

curl --location 'https://api.payorc.com/orders/v1/transaction/documents/url' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--header 'Content-Type: application/json' \
--data '{
    "transaction_id": "1000063438",
    "document_type": "INVOICE",
    "document_ref": "INV-123456",
    "document_url": "https://merchant.example.com/invoices/INV-123456.pdf"
}'

Example 2 — AWB by URL

curl --location 'https://api.payorc.com/orders/v1/transaction/documents/url' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--header 'Content-Type: application/json' \
--data '{
    "transaction_id": "1000063438",
    "document_type": "AWB",
    "document_ref": "AWB-987654",
    "document_url": "https://merchant.example.com/awb/AWB-987654.pdf"
}'

Example 3 — Node.js

const axios = require('axios');

axios({
  method: 'post',
  url: 'https://api.payorc.com/orders/v1/transaction/documents/url',
  headers: {
    'merchant-key': '{merchant-key}',
    'merchant-secret': '{merchant-secret}',
    'Content-Type': 'application/json'
  },
  data: {
    transaction_id: '1000063438',
    document_type: 'INVOICE',
    document_ref: 'INV-123456',
    document_url: 'https://merchant.example.com/invoices/INV-123456.pdf'
  }
})
  .then(response => console.log(JSON.stringify(response.data)))
  .catch(error => console.log(error.response?.data || error));

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": "INV-123456.pdf",
        "document_url": "https://merchant.example.com/invoices/INV-123456.pdf"
    }
}

Response — Validation Error (400)

{
    "message": "document_url is not valid/not supplied (https only, max 2048 characters)",
    "status": "fail",
    "code": "E0044"
}

Response — Processing Error

Same response codes as Upload Invoice (file) (101–109, 201–205). Download failures typically map to 101 (format), 103 (fetch/upload failure), or 106 (size).

{
    "status": "failed",
    "code": "103",
    "message": "Failed to Upload",
    "data": null
}

Important Notes

Use JSON — this is not the multipart file upload endpoint.
PayOrc stores document_url only; the downloaded bytes are discarded after PSP upload.
Portal View opens the merchant URL for URL-based rows.
For multipart file upload, see Upload Invoice.

Upload Invoice — Multipart file upload
Capture — Capture before uploading documents
Fetch Order — Confirm transaction state

API Summary

Aspect	Details
API	Transaction Document by URL
Method	`POST`
Content Type	`application/json`
Endpoint	`/orders/v1/transaction/documents/url`
Authentication	`merchant-key` + `merchant-secret`
Required Parameters	`transaction_id`, `document_type`, `document_ref`, `document_url`
Allowed `document_type`	`INVOICE`, `AWB`
Downloaded file types	PDF, DOC, DOCX, JPG, JPEG
Max download size	2 MB
Eligible txn types	`CAPTURE`, `PARTIALLY_CAPTURE`, `SALE`
Storage	URL in DB only (no permanent PayOrc file)

Upload Invoice by URL

On this page