Payment Request API

Create an order and request a payment link from PayOrc - the definitive reference for order creation.

Payment Request API

API Version: 3.0.0

The Payment Request API is the core endpoint for creating orders in PayOrc. It generates a hosted payment page that your customer completes to make a payment. Use class: "ECOM" with action: "SALE" or "AUTH".

Class by API

All hosted order APIs use POST /orders/v1/create. The API accepts only two class values: ECOM and CAUTH.

API	`class`	`action`	Description
Payment Request API	`ECOM`	`SALE`, `AUTH`	Hosted checkout — customer enters card on payment page
AUTH REVERSAL (Add Card)	`ECOM`	`AUTH_REVERSAL`	Card tokenization — returns `m_payment_token` via webhook
Pay by Token	`CAUTH`	`SALE`, `AUTH`	Charge a stored card using `payment_token`
Split Payment	`ECOM`	`SALE`, `AUTH`	Hosted checkout with payout split rules
MID Group	`ECOM`	`SALE`, `AUTH`	Hosted checkout routed to a MID group label

Only ECOM and CAUTH are accepted. Any other class value returns a validation error.

Navigate to Developers → API Keys → Add new API key → Select Hosted Solution in the Channel Dropdown to generate your API credentials.

Endpoint

Method	URL
POST	`https://api.payorc.com/orders/v1/create`

Please use the test credentials for sandbox testing.

Headers

Header	Type	Required	Description
`merchant-key`	String	Yes	Your merchant API key (e.g., `live-D111PIS13YK`)
`merchant-secret`	String	Yes	Your merchant API secret (e.g., `sec-JI11G0P13Z0`)
`Content-Type`	String	Yes	Must be `application/json`

Request Body — Top-Level Fields

All fields are nested inside a top-level data object: { "data": { ... } }.

Field	Type	Required	Description
`class`	String	Yes	Must be `ECOM` for hosted checkout — see Transaction Classes
`action`	String	Yes	Transaction action — `SALE`, `AUTH`, or `AUTH_REVERSAL` — see Transaction Actions
`capture_method`	String	No	`AUTOMATIC` or `MANUAL` — only when `action` is `AUTH`. Default: `AUTOMATIC` if omitted. Ignored when `action` is `SALE`
`payment_token`	String	No	Not used for `ECOM` — use Pay by Token (`class: "CAUTH"`) instead
`customer_details`	Object	Yes	Customer information — see Customer Details
`order_details`	Object	Yes	Order amount, currency, and description — see Order Details
`billing_details`	Object	Yes	Billing address — see Billing Details
`shipping_details`	Object	Yes	Shipping address — see Shipping Details
`items`	Array	No	Line items for the order — see Items
`urls`	Object	Yes	Redirect and webhook URLs — see URLs
`parameters`	Array	No	Merchant metadata echoed in webhooks — see Parameters
`custom_data`	Array	No	MID Group / Split Payment config — see Custom Data

Transaction Classes

The class field determines the type of transaction.

Value	Name	Description	When to Use
`ECOM`	E-Commerce	Customer enters card details on the hosted payment page	Payment Request, AUTH REVERSAL, Split Payment, MID Group
`CAUTH`	Card Auth	Charge a stored card using `payment_token`	Pay by Token only

For hosted Payment Request API, use class: "ECOM". For token-based charges use class: "CAUTH" (Pay by Token). For card tokenization use class: "ECOM" with action: "AUTH_REVERSAL" (Add Card).

Transaction Actions

The action field determines when funds are captured from the customer's card.

Value	Name	Description
`SALE`	Sale	Authorize AND capture in one step — funds are taken immediately
`AUTH`	Auth (Pre-Authorization)	Hold funds on the customer's card without capturing — you must capture later via a separate API call
`AUTH_REVERSAL`	Add Card	Authorize then immediately void — tokenizes the card and returns `m_payment_token` via webhook. See AUTH REVERSAL

When to use SALE:

One-time purchases where you want immediate payment
Digital goods or services delivered instantly
Physical goods shipped immediately

When to use AUTH:

Hotel bookings (capture at check-in)
Car rentals (capture at pickup)
Orders with a verification step before fulfillment

When to use AUTH_REVERSAL:

Save a card for future Pay by Token charges without capturing funds

Capture Methods

The capture_method field controls how and when the authorized amount is captured. Only applicable when action is AUTH.

Value	Name	Description
`AUTOMATIC`	Auto-Capture	Funds are captured automatically after authorization (typically within seconds)
`MANUAL`	Manual Capture	You must explicitly capture funds via a separate API call before the authorization expires

If you omit capture_method on an AUTH order, PayOrc defaults to AUTOMATIC — funds are captured shortly after authorization. Set MANUAL explicitly when you need to hold funds and call Capture later. When action is SALE, capture_method is ignored and capture happens immediately.

When action is SALE, the capture_method field is ignored — capture happens immediately regardless.

Customer Details

The customer_details object is required. Individual fields may be empty strings if not available at order creation.

Field	Type	Required	Description
`m_customer_id`	String	No	Your internal customer identifier
`name`	String	Yes*	Customer's full name (first and last name) — may be `""`
`email`	String	Yes*	Customer's email address — may be `""`
`mobile`	String	No	Customer's mobile phone number (digits only)
`code`	String	No	Country dialing code (e.g., `91` for India, `971` for UAE)

* Required by schema; pass an empty string if not available.

Order Details

Field	Type	Required	Description
`m_order_id`	String	No	Your internal order identifier
`amount`	Number	Yes	Order amount — minimum `1` (e.g., `60.20`)
`convenience_fee`	Number	Yes*	Additional fee — may be `0` or `""`
`quantity`	Number	Yes*	Number of items — may be `""`; defaults to `1` in processing
`currency`	String	Yes	ISO 4217 currency code (e.g., `AED`, `USD`, `EUR`, `GBP`, `INR`)
`description`	String	Yes*	Human-readable order description — may be `""`
`return_url`	String	No	Optional return URL stored with the order

* Required by schema; pass an empty string or 0 if not applicable.

The amount field must be a number without currency symbols, commas, or spaces. Minimum value is 1.

Amount Formatting Rules:

Use decimal point for cents: 10.50 not 10,50
No currency symbol: 60.20 not $60.20
No thousand separators: 1000.00 not 1,000.00
Minimum value is 1

Billing Details

The billing_details object is required. Fields may be empty strings if not collected.

Field	Type	Required	Description
`address_line1`	String	Yes*	Billing address line 1 — may be `""`
`address_line2`	String	Yes*	Billing address line 2 — may be `""`
`city`	String	Yes*	Billing city — may be `""`
`province`	String	Yes*	Billing state or province — may be `""`
`country`	String	Yes*	ISO 3166-1 alpha-2 country code (e.g., `AE`) — may be `""`
`pin`	String	Yes*	Billing postal/ZIP code — may be `""`

Shipping Details

The shipping_details object is required. Fields may be empty strings if not collected.

Field	Type	Required	Description
`shipping_name`	String	Yes*	Recipient's full name — may be `""`
`shipping_email`	String	Yes*	Recipient's email — may be `""`
`shipping_code`	String	No	Country dialing code for shipping mobile
`shipping_mobile`	String	No	Recipient's phone number (digits only)
`address_line1`	String	Yes*	Shipping address line 1 — may be `""`
`address_line2`	String	Yes*	Shipping address line 2 — may be `""`
`city`	String	Yes*	Shipping city — may be `""`
`province`	String	Yes*	Shipping state or province — may be `""`
`country`	String	Yes*	ISO 3166-1 alpha-2 country code — may be `""`
`pin`	String	Yes*	Shipping postal/ZIP code — may be `""`
`location_pin`	String	Yes*	Google Maps location URL — may be `""`
`shipping_currency`	String	Yes*	ISO 4217 currency for shipping — may be `""`
`shipping_amount`	Number	Yes*	Shipping cost — may be `0` or `""`

Items

The items array is optional. When provided, each item supports the fields below. Use title (not name) and reference_id (not sku) — these match what the API accepts and stores.

Field	Type	Required	Description
`title`	String	No	Product name
`description`	String	No	Product description
`quantity`	Number	No	Quantity ordered (minimum `1`)
`unit_price`	String	No	Price per unit (e.g., `"10.00"`)
`discount_amount`	String	No	Discount applied
`reference_id`	String	No	Merchant product identifier
`image_url`	String	No	Product image URL
`product_url`	String	No	Product page URL
`gender`	String	No	`Male`, `Female`, `Kids`, or `Other`
`category`	String	No	Product category
`color`	String	No	Product color
`product_material`	String	No	e.g., `cotton`, `polyester`
`size_type`	String	No	Size type label
`size`	String	No	e.g., `L`, `XL`, `12`
`brand`	String	No	Brand name
`is_refundable`	Boolean	No	Whether the product can be returned

URLs

The urls object is required. Redirect URLs may be empty strings — PayOrc falls back to MID default URLs when not provided.

Field	Type	Required	Description
`success`	String	No	URL to redirect after successful payment
`cancel`	String	No	URL to redirect if customer cancels
`failure`	String	No	URL to redirect if payment fails
`webhook_url`	String	No	Per-order webhook URL (HTTPS). Overrides dashboard webhook for this order when set

You can configure a default webhook URL in the PayOrc Merchant Portal. Use urls.webhook_url to override it for a specific order. The URL must use HTTPS (localhost is allowed for testing).

Parameters

parameters is an array of objects — one object per field. PayOrc echoes these values in webhook notifications.

"parameters": [
    { "alpha": "your-value" },
    { "beta": "" },
    { "gamma": "" },
    { "delta": "" },
    { "epsilon": "" }
]

Field	Type	Required	Description
`alpha`	String	No	Merchant-defined data
`beta`	String	No	Merchant-defined data
`gamma`	String	No	Merchant-defined data
`delta`	String	No	Merchant-defined data
`epsilon`	String	No	Merchant-defined data

Custom Data

Reserved for MID Group and Split Payments. See the Custom Data reference for format and examples.

custom_data is an array of objects (same structure as parameters). It is only validated when MID Group or Split Payment features are enabled on your account.

Supported Currency Codes

Code	Currency	Symbol
`AED`	UAE Dirham	د.إ
`USD`	US Dollar	$
`EUR`	Euro	€
`GBP`	British Pound	£
`INR`	Indian Rupee	₹
`SAR`	Saudi Riyal	﷼
`QAR`	Qatari Riyal	﷼
`KWD`	Kuwaiti Dinar	د.ك
`BHD`	Bahraini Dinar	.د.ب
`OMR`	Omani Rial	ر.ع.

Response Codes

Code	Status	Meaning
`00`	SUCCESS	Order created successfully
`400`	fail	Bad Request — missing or invalid parameters
`401`	fail	Unauthorized — invalid merchant key or secret
`403`	fail	Forbidden — account restrictions
`422`	fail	Unprocessable Entity — validation error
`429`	fail	Too Many Requests — rate limit exceeded
`500`	fail	Internal Server Error — retry with backoff

Error Handling

Scenario	HTTP Code	Error Message	Resolution
Invalid credentials	`401`	`Invalid merchant key and secret`	Verify your `merchant-key` and `merchant-secret`
Missing amount	`400`	`Amount is required`	Include `amount` in `order_details`
Invalid currency	`422`	`Unsupported currency`	Use a supported ISO 4217 code
Duplicate order ID	`400`	`Order ID already exists`	Use a unique `m_order_id`
Rate limited	`429`	`Too many requests`	Wait and retry with exponential backoff

Always implement proper error handling. Check both the HTTP status code AND the status field in the response body before proceeding.

Code Examples

Replace {merchant-key} / {merchant-secret} with your credentials. Every language example below includes the full request body — all required objects (customer_details, order_details, billing_details, shipping_details, urls) plus optional items, parameters, and custom_data.

Example 1: Basic SALE with ECOM

curl --location --globoff 'https://api.payorc.com/orders/v1/create' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "class": "ECOM",
        "action": "SALE",
        "capture_method": "",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "CUST-1234",
            "name": "John Doe",
            "email": "[email protected]",
            "mobile": "9876543210",
            "code": "91"
        },
        "order_details": {
            "m_order_id": "ORD-2024-001",
            "amount": 100,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Premium subscription",
            "return_url": ""
        },
        "billing_details": {
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044"
        },
        "shipping_details": {
            "shipping_name": "John Doe",
            "shipping_email": "[email protected]",
            "shipping_code": "",
            "shipping_mobile": "",
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044",
            "location_pin": "",
            "shipping_currency": "AED",
            "shipping_amount": 0
        },
        "urls": {
            "success": "https://yourdomain.com/payment/success",
            "cancel": "https://yourdomain.com/payment/cancel",
            "failure": "https://yourdomain.com/payment/failure",
            "webhook_url": "https://yourdomain.com/webhook"
        },
        "parameters": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "custom_data": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "items": [
            {
                "title": "Premium Plan",
                "description": "Monthly subscription",
                "quantity": 1,
                "unit_price": "100.00",
                "discount_amount": "0.00",
                "reference_id": "SKU-001",
                "image_url": "https://example.com/image.png",
                "product_url": "https://example.com/product",
                "gender": "Male",
                "category": "Subscription",
                "color": "",
                "product_material": "",
                "size_type": "",
                "size": "",
                "brand": "PayOrc",
                "is_refundable": true
            }
        ]
    }
}'

Example 2: AUTH with Manual Capture and Line Items

curl --location --globoff 'https://api.payorc.com/orders/v1/create' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "class": "ECOM",
        "action": "AUTH",
        "capture_method": "MANUAL",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "CUST-5678",
            "name": "Jane Smith",
            "email": "[email protected]",
            "mobile": "9876543210",
            "code": "91"
        },
        "order_details": {
            "m_order_id": "ORD-2024-002",
            "amount": 250,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "USD",
            "description": "Hotel reservation",
            "return_url": ""
        },
        "billing_details": {
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044"
        },
        "shipping_details": {
            "shipping_name": "John Doe",
            "shipping_email": "[email protected]",
            "shipping_code": "",
            "shipping_mobile": "",
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044",
            "location_pin": "",
            "shipping_currency": "AED",
            "shipping_amount": 0
        },
        "urls": {
            "success": "https://yourdomain.com/booking/confirmed",
            "cancel": "https://yourdomain.com/booking/cancelled",
            "failure": "https://yourdomain.com/booking/failed",
            "webhook_url": "https://yourdomain.com/webhook"
        },
        "parameters": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "custom_data": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "items": [
            {
                "title": "Deluxe Room - 3 Nights",
                "description": "Hotel room reservation",
                "quantity": 3,
                "unit_price": "75.00",
                "discount_amount": "0.00",
                "reference_id": "ROOM-DELUXE",
                "image_url": "",
                "product_url": "",
                "gender": "",
                "category": "Hotel",
                "color": "",
                "product_material": "",
                "size_type": "",
                "size": "",
                "brand": "",
                "is_refundable": true
            },
            {
                "title": "Breakfast Add-on",
                "description": "Daily breakfast",
                "quantity": 3,
                "unit_price": "8.33",
                "discount_amount": "0.00",
                "reference_id": "ADDON-BKFAST",
                "image_url": "",
                "product_url": "",
                "gender": "",
                "category": "Addon",
                "color": "",
                "product_material": "",
                "size_type": "",
                "size": "",
                "brand": "",
                "is_refundable": false
            }
        ]
    }
}'

Example 3: Minimal Valid Payload (empty optional values)

All objects must still be present. Individual field values may be empty strings where the schema allows.

curl --location --globoff 'https://api.payorc.com/orders/v1/create' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "class": "ECOM",
        "action": "SALE",
        "capture_method": "",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "",
            "name": "",
            "email": "",
            "mobile": "",
            "code": ""
        },
        "order_details": {
            "m_order_id": "ORD-MIN-001",
            "amount": 10,
            "quantity": "",
            "convenience_fee": "",
            "currency": "AED",
            "description": "",
            "return_url": ""
        },
        "billing_details": {
            "address_line1": "",
            "address_line2": "",
            "city": "",
            "province": "",
            "country": "",
            "pin": ""
        },
        "shipping_details": {
            "shipping_name": "",
            "shipping_email": "",
            "shipping_code": "",
            "shipping_mobile": "",
            "address_line1": "",
            "address_line2": "",
            "city": "",
            "province": "",
            "country": "",
            "pin": "",
            "location_pin": "",
            "shipping_currency": "",
            "shipping_amount": ""
        },
        "urls": {
            "success": "",
            "cancel": "",
            "failure": "",
            "webhook_url": ""
        },
        "parameters": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "custom_data": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "items": []
    }
}'

Response — Success (200)

{
    "status": "SUCCESS",
    "status_code": "00",
    "message": "Order created",
    "p_order_id": 1000010240,
    "m_order_id": "ORD-2023-001",
    "p_request_id": 1000010200,
    "order_creation_date": "15/06/2023 12:20:27",
    "amount": "AED 100.00",
    "payment_link": "https://checkout.payorc.com/pay/xxxxx",
    "iframe_link": "https://checkout.payorc.com/iframe/xxxxx"
}

Response Fields

Field	Type	Description
`status`	String	`SUCCESS` or `fail`
`status_code`	Number	`00` for success
`message`	String	Human-readable message
`p_order_id`	Number	PayOrc's internal order ID
`m_order_id`	String	Your merchant order ID (echoed back)
`p_request_id`	Number	PayOrc request tracking ID
`order_creation_date`	String	Timestamp of order creation
`amount`	String	Formatted amount with currency
`payment_link`	String	Full-page hosted payment URL
`iframe_link`	String	Embeddable iframe payment URL

The payment_link opens a full-page checkout. The iframe_link is designed to be embedded in an iframe on your website. Use whichever suits your integration.

Response — Error (4xx)

{
    "message": "Invalid merchant key and secret",
    "status": "fail",
    "code": "401"
}

Flow Diagram

The payment request flow works as follows:

Merchant sends a POST /orders/create request with order details.
PayOrc creates the order and returns payment_link and iframe_link.
Merchant redirects the customer to the payment_link.
Customer enters card details on the PayOrc-hosted payment page.
PayOrc processes the payment with the acquiring bank.
PayOrc sends a webhook notification to the merchant's configured URL.
Customer is redirected to the merchant's success, cancel, or failure URL.

Always verify payment status via webhook or the transaction status API rather than relying solely on the redirect URL. Customers can manipulate redirect parameters.

Payment Request API

On this page