PayOrc
Payment Request API

Split Payment

Distribute a single transaction's payout across a primary account and multiple sub-accounts using Split Payments.

Split Payment

API Version: 3.0.0

Split Payments let you distribute a single transaction's payout across a primary account and multiple sub-accounts in one smooth transaction. This simplifies fund allocation, making it easy to pay out multiple recipients from a single customer payment.

Use class: "ECOM" with action: "SALE" or "AUTH". See Class by API for the full mapping.

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

Split Payments must be enabled on your merchant account before use. Contact PayOrc support to activate this feature and obtain your Split IDs.

How It Works

  1. Configure Split IDs — Each sub-account (recipient) has a unique Split ID assigned by PayOrc.
  2. Pass split rules in custom_data — Specify the split type (percentage or flat amount) and value for each recipient.
  3. Customer pays the full amount — The customer pays the total order amount as usual.
  4. PayOrc distributes funds — After settlement, PayOrc automatically splits the payout across all configured accounts.

Endpoint

MethodURL
POSThttps://api.payorc.com/orders/v1/create

Please use the test credentials for sandbox testing.

Headers

HeaderTypeRequiredDescription
merchant-keyStringYesYour merchant API key (e.g., live-D111PIS13YK)
merchant-secretStringYesYour merchant API secret (e.g., sec-JI11G0P13Z0)
Content-TypeStringYesMust be application/json

Request Body — Top-Level Fields

All fields are nested inside a top-level data object: { "data": { ... } }. Same schema as Payment Request API — only custom_data carries split rules.

FieldTypeRequiredDescription
classStringYesMust be ECOM
actionStringYesSALE or AUTH — see Transaction Actions
capture_methodStringNoAUTOMATIC or MANUAL — only when action is AUTH. Default: AUTOMATIC if omitted. Ignored for SALE
payment_tokenStringNoNot used for ECOM
customer_detailsObjectYesCustomer information — see Customer Details
order_detailsObjectYesOrder amount, currency, and description — see Order Details
billing_detailsObjectYesBilling address — see Billing Details
shipping_detailsObjectYesShipping address — see Shipping Details
itemsArrayNoLine items — see Items
urlsObjectYesRedirect and webhook URLs — see URLs
parametersArrayNoMerchant metadata echoed in webhooks — see Parameters
custom_dataArrayYesSplit payment rules — see Custom Data (Split Rules)

Same request body as Payment Request API. Include urls.webhook_url the same way. Only custom_data differs for split rules.

Custom Data (Split Rules)

custom_data is an array of objects. Enable split mode with alpha, then define rules in beta through epsilon.

Array elementRequiredFormatExampleMeaning
{ "alpha": "..." }Yes|SPLIT_PAYMENT"|SPLIT_PAYMENT"Enables split payment mode
{ "beta": "..." }Yes|{id},{type},{value}"|100,P,2"2% to Split ID 100
{ "gamma": "..." }No|{id},{type},{value}"|101,F,50"Flat 50 to Split ID 101
{ "delta": "..." }No|{id},{type},{value}"|102,F,25"Flat 25 to Split ID 102
{ "epsilon": "..." }No|{id},{type},{value}"|103,P,1"1% to Split ID 103
  • Split payments work in live mode only.
  • P = percentage of order amount; F = flat amount in order currency.
  • Split IDs are provided by PayOrc after you configure sub-accounts.
  • See Custom Data for combined MID Group + Split format.

Customer Details

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

FieldTypeRequiredDescription
m_customer_idStringNoYour internal customer identifier
nameStringYes*Customer's full name (first and last name) — may be ""
emailStringYes*Customer's email address — may be ""
mobileStringNoCustomer's mobile phone number (digits only)
codeStringNoCountry dialing code (e.g., 91 for India, 971 for UAE)

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

Order Details

FieldTypeRequiredDescription
m_order_idStringNoYour internal order identifier
amountNumberYesOrder amount — minimum 1 (e.g., 60.20)
convenience_feeNumberYes*Additional fee — may be 0 or ""
quantityNumberYes*Number of items — may be ""; defaults to 1 in processing
currencyStringYesISO 4217 currency code (e.g., AED, USD, EUR, GBP, INR)
descriptionStringYes*Human-readable order description — may be ""
return_urlStringNoOptional 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.

Billing Details

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

FieldTypeRequiredDescription
address_line1StringYes*Billing address line 1 — may be ""
address_line2StringYes*Billing address line 2 — may be ""
cityStringYes*Billing city — may be ""
provinceStringYes*Billing state or province — may be ""
countryStringYes*ISO 3166-1 alpha-2 country code (e.g., AE) — may be ""
pinStringYes*Billing postal/ZIP code — may be ""

Shipping Details

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

FieldTypeRequiredDescription
shipping_nameStringYes*Recipient's full name — may be ""
shipping_emailStringYes*Recipient's email — may be ""
shipping_codeStringNoCountry dialing code for shipping mobile
shipping_mobileStringNoRecipient's phone number (digits only)
address_line1StringYes*Shipping address line 1 — may be ""
address_line2StringYes*Shipping address line 2 — may be ""
cityStringYes*Shipping city — may be ""
provinceStringYes*Shipping state or province — may be ""
countryStringYes*ISO 3166-1 alpha-2 country code — may be ""
pinStringYes*Shipping postal/ZIP code — may be ""
location_pinStringYes*Google Maps location URL — may be ""
shipping_currencyStringYes*ISO 4217 currency for shipping — may be ""
shipping_amountNumberYes*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.

FieldTypeRequiredDescription
titleStringNoProduct name
descriptionStringNoProduct description
quantityNumberNoQuantity ordered (minimum 1)
unit_priceStringNoPrice per unit (e.g., "10.00")
discount_amountStringNoDiscount applied
reference_idStringNoMerchant product identifier
image_urlStringNoProduct image URL
product_urlStringNoProduct page URL
genderStringNoMale, Female, Kids, or Other
categoryStringNoProduct category
colorStringNoProduct color
product_materialStringNoe.g., cotton, polyester
size_typeStringNoSize type label
sizeStringNoe.g., L, XL, 12
brandStringNoBrand name
is_refundableBooleanNoWhether 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.

FieldTypeRequiredDescription
successStringNoURL to redirect after successful payment
cancelStringNoURL to redirect if customer cancels
failureStringNoURL to redirect if payment fails
webhook_urlStringNoPer-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": "" }
]
FieldTypeRequiredDescription
alphaStringNoMerchant-defined data
betaStringNoMerchant-defined data
gammaStringNoMerchant-defined data
deltaStringNoMerchant-defined data
epsilonStringNoMerchant-defined data

Code Examples

Replace {URL} with https://api.payorc.com/orders/v1/create, and {merchant-key} / {merchant-secret} with your actual credentials.

Example 1: Percentage-Based Split (2% to primary, flat AED 50 to sub-account)

Same full body as Payment Request API. Only custom_data differs for split rules.

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": "SPLIT-2024-001",
            "amount": 100,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Split payment order",
            "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": "|SPLIT_PAYMENT"
            },
            {
                "beta": "|100,P,2"
            },
            {
                "gamma": "|101,F,50"
            },
            {
                "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
            }
        ]
    }
}'

Response — Success (200)

{
    "status": "SUCCESS",
    "status_code": 00,
    "message": "Order created",
    "p_order_id": 1000010240,
    "m_order_id": "SPLIT-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

FieldTypeDescription
statusStringSUCCESS or fail
status_codeNumber00 for success
messageStringHuman-readable message
p_order_idNumberPayOrc's internal order ID
m_order_idStringYour merchant order ID (echoed back)
p_request_idNumberPayOrc request tracking ID
order_creation_dateStringTimestamp of order creation
amountStringFormatted amount with currency
payment_linkStringFull-page hosted payment URL
iframe_linkStringEmbeddable iframe payment URL

Response — Error (4xx)

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

Pay by Token

Charge a saved card token for Card-on-File (CoF) transactions — use a previously tokenized payment method for recurring or one-click payments.

MID Group

Route specific transactions to designated merchant accounts using MID Group configuration.

On this page

Split PaymentHow It WorksEndpointHeadersRequest Body — Top-Level FieldsCustom Data (Split Rules)Customer DetailsOrder DetailsBilling DetailsShipping DetailsItemsURLsParametersCode ExamplesExample 1: Percentage-Based Split (2% to primary, flat AED 50 to sub-account)Response — Success (200)Response FieldsResponse — Error (4xx)