PayOrc
Payment Request API

MID Group

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

MID Group

API Version: 3.0.0

MID Group routing lets you direct specific transactions to designated merchant accounts (MIDs) based on your configuration. This is useful when you have multiple merchant accounts for different business lines, regions, or product categories and need to route payments to the appropriate account.

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.

MID Group routing must be enabled on your merchant account and configured in the Merchant Portal before use. Contact PayOrc support to set up your MID Groups.

How It Works

  1. Configure MID Groups in the Merchant Portal — assign labels to your merchant accounts.
  2. Pass the MID Group label in custom_data with each payment request.
  3. PayOrc routes the transaction to the merchant account associated with that label.

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 MID Group routing.

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_dataArrayYesMID Group routing — see Custom Data (MID Group)

Same request body as Payment Request API. Include urls.webhook_url the same way. Only custom_data differs for MID Group routing.

Custom Data (MID Group)

custom_data is an array of objects:

Array elementRequiredFormatExampleMeaning
{ "alpha": "..." }YesMID_GROUP"MID_GROUP"Enables MID Group routing
{ "beta": "..." }Yes{label}"INS_HEALTH"MID Group label from Merchant Portal
{ "gamma": "..." }No""""Reserved
{ "delta": "..." }No""""Reserved
{ "epsilon": "..." }No""""Reserved
  • beta must match the exact MID Group label configured in the Merchant Portal.
  • See Custom Data for combined MID Group + Split format.

MID Group Example

"custom_data": [
    { "alpha": "MID_GROUP" },
    { "beta": "INS_HEALTH" },
    { "gamma": "" },
    { "delta": "" },
    { "epsilon": "" }
]

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: Route to INS_HEALTH MID Group

Same full body as Payment Request API. Only custom_data differs for MID Group routing.

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": "MID-2024-001",
            "amount": 500,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Health insurance premium",
            "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": "MID_GROUP"
            },
            {
                "beta": "INS_HEALTH"
            },
            {
                "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
            }
        ]
    }
}'

Response — Success (200)

{
    "status": "SUCCESS",
    "status_code": 00,
    "message": "Order created",
    "p_order_id": 1000010240,
    "m_order_id": "MID-2023-001",
    "p_request_id": 1000010200,
    "order_creation_date": "15/06/2023 12:20:27",
    "amount": "AED 500.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"
}

Split Payment

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

Custom Data

Reference guide for using the custom_data array to enable MID Group routing and Split Payments.

On this page

MID GroupHow It WorksEndpointHeadersRequest Body — Top-Level FieldsCustom Data (MID Group)MID Group ExampleCustomer DetailsOrder DetailsBilling DetailsShipping DetailsItemsURLsParametersCode ExamplesExample: Route to INS_HEALTH MID GroupResponse — Success (200)Response FieldsResponse — Error (4xx)