Bulk Upload

Bulk Upload Payment Links

Version: 3.0.0

Generate an API Key for the Payment Link channel before making requests.

Bulk upload lets you create multiple payment links in a single request by uploading an Excel or CSV file. This is useful when you need to generate a large number of links for campaigns, product launches, or batch customer billing.

Each row in the file creates one payment link. Validation is all-or-nothing: if any row fails validation, the entire batch is rejected and no links are created.

Endpoint

Method	URL
POST	`https://api.payorc.com/payment-links/v1/bulk-upload`

Authentication

Header	Type	Description
`merchant-key`	String	Your merchant key
`merchant-secret`	String	Your merchant secret

Request Body (multipart/form-data)

Field	Type	Required	Description
`payment_link_file`	File	Yes	Excel (`.xlsx`) file containing payment link details (max 2 MB)

Only .xlsx files are accepted (max 2 MB). The file must use the exact column headers described below. Rows with missing required fields or invalid data will cause the entire upload to fail.

File Format

The upload file must use the following column headers (exact spelling and casing):

Column	Type	Required	Description
`Currency`	String	Yes	ISO 4217 currency code (e.g., `USD`, `AED`, `SAR`)
`Amount`	Number	Yes	Payment amount (1 – 99999999)
`Shipping Fee`	Number	Yes	Shipping fee (0 – 99999)
`Convenience Fee`	Number	Yes	Convenience fee (0 – 99999)
`Qty Per Transaction`	Number	Yes	Maximum quantity per transaction (1 – 9999999)
`No Of Transactions`	Number	Yes	Number of transactions allowed per user (1 – 9999999)
`No Limit Per User`	String	No	`1` for unlimited transactions per user, `0` otherwise (defaults to `0`)
`Total Collection`	String	Yes	Per-user frequency: `per_day`, `per_month`, or `till_expiry`
`Overall Qty Allowed`	Number	Yes	Overall quantity allowed (1 – 9999999)
`No Limit Over All`	String	No	`1` for unlimited overall quantity, `0` otherwise (defaults to `0`)
`Qty Frequency`	String	Yes	Overall frequency: `per_day`, `per_month`, or `till_expiry`
`Is Expiry`	Number	Yes	`1` to enable expiry, `0` to disable
`End Date`	String	Conditional	Required when `Is Expiry` is `1`. Format `YYYY-MM-DD`, today or later
`Description`	String	No	Description shown to the customer (max 100 characters)
`Error Message`	String	No	Custom error message on validation failure (max 100 characters)
`Customer Name`	String	No	Customer name in `Firstname Lastname` format (max 50 characters)
`Customer Email`	String	No	Customer email (max 50 characters)
`Product Details`	String	No	Product or service details (max 200 characters)
`Split Payment`	String	No	`0` to disable split payment, `1` to enable (defaults to `0`)
`Tip`	String	No	`0` to disable tip, `1` to enable (forced to `0` unless `Split Payment` is `1`)

Code Examples

curl -X POST https://api.payorc.com/payment-links/v1/bulk-upload \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -F "payment_link_file=@/path/to/payment-links.xlsx"

Response — Success (200)

{
  "data": {
    "total_records": 1,
    "links_created": 1,
    "links_failed": 0,
    "links": [
      {
        "payment_link": "https://checkout.payorc.com/checkout/qr/6a1d4f160b1b43999539e9ad1cc9565d",
        "qr_id": "6a1d4f160b1b43999539e9ad1cc9565d",
        "link_id": "0000002058",
        "amount": 100,
        "currency": "AED"
      }
    ]
  },
  "message": "Bulk payment links processed",
  "status": "success",
  "code": "00"
}

Response Fields

Field	Type	Description
`status`	String	Response status
`message`	String	Response message
`code`	String	Response code
`data`	Object	Bulk upload result
`data.total_records`	Number	Total rows processed from the file
`data.links_created`	Number	Number of payment links created
`data.links_failed`	Number	Number of rows that failed
`data.uploaded_file_url`	String	URL of the uploaded file
`data.links`	Array	List of created payment links
`data.links[].payment_link`	String	Payment link URL
`data.links[].qr_id`	String	QR code identifier
`data.links[].link_id`	String	Unique link ID
`data.links[].amount`	Number	Payment amount
`data.links[].currency`	String	ISO 4217 currency code
`data.failed_rows`	Array	Rows that failed during creation (present only when `links_failed` > 0)

Response — Error (4xx)

{
  "status": "fail",
  "message": "Invalid file format. Expected .xlsx or .csv",
  "code": "E0035"
}

All rows must pass validation before any links are created. If a row fails while links are being created (for example, a database error), it is reported in failed_rows and successfully created links are not rolled back.

Example Column Layout

The first row of the .xlsx file must contain these exact headers. Each subsequent row creates one payment link:

Currency	Amount	Shipping Fee	Convenience Fee	Qty Per Transaction	No Of Transactions	No Limit Per User	Total Collection	Overall Qty Allowed	No Limit Over All	Qty Frequency	Is Expiry	End Date	Description	Error Message	Customer Name	Customer Email	Product Details	Split Payment	Tip
AED	100	50	20	9	3	0	per_day	10	0	per_day	1	2026-12-31	Wireless Headphones	Error message	John Doe	[email protected]	Product description	0	0

On this page