Add Card - AUTH REVERSAL

Tokenize a customer's card by performing an AUTH followed by an immediate VOID — securely store the card for future payments.

Add Card: AUTH REVERSAL

API Version: 3.0.0

The Add Card (AUTH REVERSAL) endpoint tokenizes a customer's card without charging them. It performs an authorization followed by an immediate void, generating a secure m_payment_token that can be used for future transactions. This is the recommended way to collect and store card details for recurring billing, subscriptions, or one-click checkout.

Use class: "ECOM" with action: "AUTH_REVERSAL". 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.

How It Works

Customer enters card details on your hosted payment page or SDK.
PayOrc authorizes a small amount on the card (AUTH).
PayOrc immediately voids the authorization — no funds are captured.
A secure token (m_payment_token) is returned in the webhook response.
You store the token on your backend and use it for future payments.

The billing and shipping details collected during tokenization are automatically reused for future transactions using the m_payment_token, eliminating the need to resend them.

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": { ... } }. Same schema as Payment Request API — focus fields are action: "AUTH_REVERSAL" and customer_details.m_customer_id.

Field	Type	Required	Description
`class`	String	Yes	Must be `ECOM`
`action`	String	Yes	Must be `AUTH_REVERSAL`
`capture_method`	String	No	Ignored for AUTH REVERSAL (authorization is voided immediately)
`payment_token`	String	No	Not used — token is returned after success
`customer_details`	Object	Yes	`m_customer_id` required — see Customer Details
`order_details`	Object	Yes	Order amount and currency — 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 — 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 — see Custom Data

Same request body as Payment Request API. Include urls.webhook_url (token is delivered via webhook). Focus: action: "AUTH_REVERSAL" and customer_details.m_customer_id.

Transaction Classes

The class field determines the type of transaction.

Value	Name	Description
`ECOM`	E-Commerce	Customer is present and enters card details on your hosted payment page

For AUTH REVERSAL, class must be ECOM. Do not use CAUTH — that class is only for Pay by Token charges with an existing payment_token.

Customer Details

The customer_details object is required. For this API, m_customer_id is mandatory so the token is linked to the customer.

Field	Type	Required	Description
`m_customer_id`	String	Yes	Your internal customer identifier — required to link the token to the customer
`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.

m_customer_id is required. The generated m_payment_token is associated with this customer ID for future Pay by Token requests.

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.

Same amount rules as Payment Request API — minimum 1. The authorization is voided immediately, so no funds are captured.

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

custom_data is an array of objects — same shape as parameters. Use it for MID Group and Split Payment configuration. See Custom Data.

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

Field	Type	Required	Description
`alpha`	String	No	Feature flag / routing key (e.g. `MID_GROUP`, `
`beta`	String	No	Feature value (e.g. MID label or split rule)
`gamma`	String	No	Additional rule / reserved
`delta`	String	No	Additional rule / reserved
`epsilon`	String	No	Additional rule / reserved

Code Examples

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

Example 1: Basic Card Tokenization

Same full body as Payment Request API. Focus fields: action: "AUTH_REVERSAL" and customer_details.m_customer_id (required).

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_REVERSAL",
        "capture_method": "AUTOMATIC",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "CUST-1234",
            "name": "John Doe",
            "email": "[email protected]",
            "mobile": "9876543210",
            "code": "91"
        },
        "order_details": {
            "m_order_id": "TOKEN-2024-001",
            "amount": 1,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Card tokenization",
            "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/token/success",
            "cancel": "https://yourdomain.com/token/cancel",
            "failure": "https://yourdomain.com/token/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
            }
        ]
    }
}'

Response — Success (200)

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

Webhook Response

After the customer completes tokenization on the hosted payment page, PayOrc POSTs a webhook to your urls.webhook_url (or dashboard webhook). Store m_payment_token for Pay by Token.

{
    "action": "AUTH_REVERSAL",
    "status": "SUCCESS",
    "order_status": "AUTHORISED",
    "m_order_id": "TOKEN-2026-001",
    "p_order_id": "1000032496",
    "p_request_id": "1000071977",
    "psp_ref_id": "25681014",
    "transaction_id": "1000058955",
    "is_live": false,
    "terminal_label": "",
    "remark": "",
    "reason": "",
    "currency": "AED",
    "amount": "1.00",
    "channel": "Flutter SDK",
    "channel_id": "",
    "shipping_fee": "0.00",
    "convenience_fee": "0.00",
    "customer_details": {
        "name": "John Doe",
        "email": "[email protected]",
        "code": "971",
        "mobile": "945464952",
        "m_customer_id": "1"
    },
    "billing_address": {
        "address_line_1": "Dubai Marina",
        "address_line_2": "",
        "city": "Dubai",
        "state": "",
        "country": "AE",
        "pincode": ""
    },
    "shipping_address": {
        "address_line_1": "",
        "address_line_2": "",
        "city": "Dubai",
        "state": "",
        "country": "",
        "pincode": ""
    },
    "ip_country": "IN",
    "psp": "PAYMOB",
    "payment_method": "DEBIT CARD",
    "m_payment_token": "SlhOQTM2SWNNWjVYNVdacXhzcWxmZz09",
    "transaction_time": "03-08-2026 09:44:40",
    "payment_method_data": {
        "scheme": "VISA",
        "card_country": "POLAND",
        "card_type": "DEBIT",
        "mask_card_number": "4111****1111",
        "expiry_month": "12",
        "expiry_year": "2045"
    },
    "apm_name": "",
    "apm_identifier": "",
    "sub_merchant_identifier": "0000001181",
    "parameters": [
        { "alpha": "" },
        { "beta": "" },
        { "gamma": "" },
        { "delta": "" },
        { "epsilon": "" }
    ],
    "custom_data": [
        { "alpha": "" },
        { "beta": "" },
        { "gamma": "" },
        { "delta": "" },
        { "epsilon": "" }
    ]
}

This is the same webhook shape as Webhooks Notification. For AUTH REVERSAL, action is "AUTH_REVERSAL" and m_payment_token is present when tokenization succeeds. Store the token securely and pass it as payment_token with class: "CAUTH" on Pay by Token.

Response — Error (4xx)

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

Using the Token for Future Payments

Once you have the m_payment_token, charge the card with Pay by Token (class: "CAUTH"):

{
    "data": {
        "class": "CAUTH",
        "action": "SALE",
        "capture_method": "",
        "payment_token": "SlhOQTM2SWNNWjVYNVdacXhzcWxmZz09",
        "customer_details": {
            "m_customer_id": "1",
            "name": "John Doe",
            "email": "[email protected]",
            "mobile": "945464952",
            "code": "971"
        },
        "order_details": {
            "m_order_id": "ORDER-2026-002",
            "amount": 99.99,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Monthly subscription",
            "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": "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": []
    }
}

Use class: "CAUTH" with payment_token (the webhook m_payment_token). customer_details.m_customer_id must match the value used during AUTH REVERSAL. Billing and shipping collected at tokenization may be reused by the PSP — still send the required objects on create (values may be "").

Add Card - AUTH REVERSAL

On this page