CAUTH (Pay by Token)

Version: 3.0.0

S2S channel API key required. IP whitelist applies.

CAUTH charges a stored card token (merchant-initiated / card-on-file). Use the same POST /s2s/v1/payment endpoint as standard S2S payment, with class: "CAUTH" and payment_token inside card_details.

This is not a minimal body with only order_id and amount. You must send the full S2S { "data": { ... } } shape (customer, order, billing, shipping, items) plus data.card_details.payment_token.

Prerequisites

CAUTH-enabled MID for the merchant (contact PayOrc support if needed).
Valid payment_token from a prior tokenization flow (e.g. hosted AUTH REVERSAL).
data.customer_details.m_customer_id — must match the customer linked to the token.
Token is validated against merchant_id from your S2S API credentials (merchant-key / merchant-secret).
Tokens are PSP-specific — the PSP is resolved from the stored card’s recurring mandate.

Supported PSPs (MIT drivers)

The PSP is picked from the token’s stored mandate, then routed to:

PSP	Driver
Telr	`telrOpenCauthDriver`
Paymob	`paymobOpenCauthDriver`
NI (Network International)	`niOpenCauthDriver`

A CAUTH MID must exist for that PSP + currency + test/live mode.

Endpoint

Method	URL
POST	`https://api.payorc.com/s2s/v1/payment`

Please use the test credentials for sandbox testing.

Headers

Header	Required
`merchant-key`	Yes
`merchant-secret`	Yes
`Content-Type`	`application/json`

Request body (key fields)

Field	Required	Description
`data.class`	Yes	Must be `CAUTH`
`data.type`	Yes	Must be `CARD`
`data.action`	Yes	`SALE` or `AUTH`
`data.capture_method`	Yes when `AUTH`	`MANUAL` or `AUTOMATIC`
`data.card_details.payment_token`	Yes	Encrypted token from Add Card / tokenization
`data.customer_details.m_customer_id`	Yes	Must match token’s customer
`data.customer_details`	Yes	name, email, mobile, code
`data.order_details`	Yes	`m_order_id`, `amount`, `currency`, `return_url`, etc.
`data.billing_details`	Yes*	Required unless valid billing is stored on the token
`data.shipping_details`	Yes	Same shape as S2S Payment
`data.items`	Yes	Line items array
`data.urls.webhook_url`	No	Per-order webhook URL (HTTPS) — see URLs

* If the token has a saved billing address on file, billing may be loaded automatically; otherwise all mandatory billing fields are required.

Do not put payment_token at the top level of data. It must be inside data.card_details. Do not send raw card number/CVV for CAUTH — only the token.

Example request

{
  "data": {
    "action": "SALE",
    "class": "CAUTH",
    "capture_method": "AUTOMATIC",
    "type": "CARD",
    "customer_details": {
      "m_customer_id": "1234",
      "name": "John Doe",
      "email": "[email protected]",
      "mobile": "9876543210",
      "code": "971"
    },
    "order_details": {
      "m_order_id": "ORD-CAUTH-001",
      "amount": "10",
      "currency": "AED",
      "convenience_fee": "0",
      "description": "Subscription charge",
      "return_url": "https://merchant.example.com/return"
    },
    "items": [
      {
        "title": "Monthly plan",
        "quantity": 1,
        "unit_price": "10.00",
        "discount_amount": "0.00",
        "is_refundable": true
      }
    ],
    "card_details": {
      "payment_token": "YOUR_PAYMENT_TOKEN_FROM_AUTH_REVERSAL"
    },
    "billing_details": {
      "address_line1": "Po Box 12322",
      "address_line2": "",
      "city": "Dubai",
      "province": "Dubai",
      "country": "AE",
      "pin": "54044"
    },
    "shipping_details": {
      "shipping_name": "John Doe",
      "shipping_email": "[email protected]",
      "shipping_code": "971",
      "shipping_mobile": "9876543210",
      "address_line1": "Po Box 12322",
      "address_line2": "",
      "city": "Dubai",
      "province": "Dubai",
      "country": "AE",
      "pin": "54044",
      "shipping_currency": "AED",
      "shipping_amount": "0"
    },
    "urls": {
      "success": "",
      "cancel": "",
      "failure": "",
      "webhook_url": "https://merchant.example.com/webhook"
    }
  }
}

Code flow (S2S)

Validation — token + m_customer_id + merchant_id scope check.
Order created (s2s_create) like ECOM.
Card routing / PSP modular path skipped for CAUTH.
cauthPaymentMiddleware → openCauthStoredTokenService → PSP driver (Telr / Paymob / NI).

Success response

MIT success returns ServerResponse.successdatamsg(webhookPayload) — envelope { status, code, message, data } where data is the full webhook-shaped payload (same as Webhook notifications / hosted Pay by Token).

{
  "status": "success",
  "code": "00",
  "message": "Transaction Successful",
  "data": {
    "action": "CAPTURE",
    "status": "SUCCESS",
    "status_code": "00",
    "order_status": "CAPTURED",
    "m_order_id": "ORD-CAUTH-001",
    "p_order_id": "1000015109",
    "p_request_id": "1000015200",
    "psp_ref_id": "8902217",
    "transaction_id": "1000021941",
    "is_live": false,
    "terminal_label": "",
    "remark": "",
    "reason": "",
    "currency": "AED",
    "amount": "10.00",
    "channel": "S2S",
    "channel_id": "",
    "shipping_fee": "0.00",
    "convenience_fee": "0.00",
    "customer_details": {
      "name": "John Doe",
      "email": "[email protected]",
      "code": "91",
      "mobile": "9876543210",
      "m_customer_id": "1234"
    },
    "billing_address": {
      "address_line_1": "Po Box 12322",
      "address_line_2": "",
      "city": "Dubai",
      "state": "Dubai",
      "country": "AE",
      "pincode": "54044"
    },
    "shipping_address": {
      "address_line_1": "",
      "address_line_2": "",
      "city": "",
      "state": "",
      "country": "",
      "pincode": ""
    },
    "ip_country": "",
    "psp": "PAYMOB",
    "payment_method": "CARD",
    "m_payment_token": "B2JmcS85UDEwZXdTVElxc0swc1JNUT09",
    "transaction_time": "03-08-2026 09:44:40",
    "payment_method_data": {
      "scheme": "VISA",
      "card_country": "POLAND",
      "card_type": "DEBIT",
      "mask_card_number": "4111****1111"
    },
    "apm_name": "",
    "apm_identifier": "",
    "sub_merchant_identifier": "0000001181",
    "parameters": [
      { "alpha": "" },
      { "beta": "" },
      { "gamma": "" },
      { "delta": "" },
      { "epsilon": "" }
    ],
    "custom_data": [
      { "alpha": "" },
      { "beta": "" },
      { "gamma": "" },
      { "delta": "" },
      { "epsilon": "" }
    ],
    "return_url": "https://merchant.example.com/status"
  }
}

MIT failure returns:

{
  "status": "failed",
  "code": "PAYMENT_FAILED",
  "message": "Transaction Failed",
  "data": {
    "action": "SALE",
    "status": "FAILED",
    "order_status": "FAILED",
    "m_order_id": "ORD-CAUTH-001",
    "p_order_id": "1000015109",
    "currency": "AED",
    "amount": "10.00",
    "m_payment_token": "B2JmcS85UDEwZXdTVElxc0swc1JNUT09"
  }
}

Common errors

Message / reason	Cause
`m_customer_id is required for CAUTH orders`	Missing customer ID
`Payment token not valid/not supplied`	Missing or invalid `card_details.payment_token`
`payment_token must be passed inside card_details`	Token sent at wrong level
`recurring_mandate_missing`	Token has no mandate for Telr/Paymob/NI
`cauth_mid_missing`	No CAUTH MID for resolved PSP + currency

See also: Pay by Token (hosted) for tokenization prerequisites and field-level detail.

CAUTH (Pay by Token)

On this page