---
title: "PayDirect on-demand SI — register mandate (request body)"
method: POST
path: "/gl/v1/payments/initiate"
tags: ["Payment"]
---

# PayDirect on-demand SI — register mandate (request body)

`POST /gl/v1/payments/initiate`

**Endpoint:** `POST /gl/v1/payments/initiate` — same URL for GPI, on-demand SI, auto-debit, and authorize; only the request body differs.

For merchants with **on-demand SI** enabled on PayGlocal. **International cards only.** Request body includes `standingInstruction.data` (no `captureTxn`).

## Request body

- TransactionRequestPayDirectSIOnDemand — Standing instruction registration when on-demand SI is enabled on the MID. **International cards only** (`paymentData.cardData`).
  - `merchantTxnId` string, required — Merchant's unique transaction identifier. Alphanumeric only.
  - `merchantUniqueId` string — Optional stable merchant-side ID for idempotency and reconciliation. Alphanumeric only.
  - `riskData` RiskPayDirectInitiate — Fraud-assessment payload processed by PayGlocal's risk engine. Sending complete risk data helps prevent fraudulent transactions and improves approval rates. **Required for international card transactions.** For RuPay cards, `customerData.ipAddress`, `customerData.httpAccept`, and `customerData.httpUserAgent` are also required.
    - `customerData` Customer — Payer identity for risk evaluation.
      - `merchantAssignedCustomerId` string
      - `firstName` string
      - `lastName` string
      - `emailId` string, email
      - `callingCode` string
      - `mobileNumber` string
    - `shippingData` Shipping — Shipping address for physical-goods orders.
      - `firstName` string
      - `lastName` string
      - `emailId` string, email
      - `addressStreet1` string
      - `addressStreet2` string
      - `addressCity` string
      - `addressState` string
      - `addressPostalCode` string
      - `addressCountry` string
    - `orderData` RiskItem[] — Line items in the order. Preferred for all transactions.
      - `itemId` string
      - `itemName` string
      - `itemQuantity` integer
      - `itemPrice` string
      - `itemCategory` string
    - `flightData` RiskFlightBooking[] — Flight booking details. Required for airline / travel transactions.
      - `agentCode` string
      - `agentName` string
      - `reservationCode` string
      - `legData` RiskFlightLeg[]
        - `flightNumber` string
        - `departureAirportCode` string
        - `departureDate` string — Departure date in YYYYMMDD format.
        - `arrivalAirportCode` string
        - `carrierCode` string
      - `passengerData` RiskFlightPassenger[]
        - `firstName` string
        - `lastName` string
        - `email` string, email
  - `merchantCallbackURL` string, uri, required — Customers are redirected here post payment completion.
  - `paymentData` PaymentPayDirectInitiateCard, required — PayDirect initiate with raw card PAN (`cardData`).
    - `totalAmount` string, required — Transaction amount as a decimal string. Supports up to 4 decimal places.
    - `txnCurrency` string, required — ISO 4217 currency code. Must be uppercase (e.g. `INR`, `USD`, `EUR`).
    - `billingData` Billing — Billing address + contact details of the payer.
      - `firstName` string
      - `lastName` string
      - `emailId` string, email
      - `callingCode` string
      - `phoneNumber` string
      - `addressStreet1` string
      - `addressStreet2` string
      - `addressCity` string
      - `addressState` string
      - `addressStateCode` string
      - `addressPostalCode` string
      - `addressCountry` string — ISO 3166-1 alpha-3 country code.
    - `cardData` Card, required — Raw card data. Required when initiating a card transaction with `paymentType=CARD`.
      - `number` string — Primary Account Number (PAN). Digits only.
      - `expiryMonth` string — Two-digit expiry month.
      - `expiryYear` string — Four-digit expiry year.
      - `securityCode` string — CVV / CVC.
      - `type` string — Card network (derived by PayGlocal if omitted).
  - `standingInstruction` StandingInstructionPayDirectOnDemand, required
    - `data` SIDataPayDirectOnDemand, required — Mandate fields for standing instruction registration when **on-demand SI** is enabled on your PayGlocal MID. `frequency` is not limited to `ONDEMAND` — set the schedule you need. Do **not** send `startDate` or `endDate` — those apply only to [auto debit](/api-reference/payments-v2/paydirect/si-auto-debit).
      - `maxAmount` string, required — Maximum debit amount for recurring transactions. Numeric string. Used when `type` is `VARIABLE` (debit ≤ `maxAmount` per transaction).
      - `amount` string, required — Fixed mandate debit amount. Numeric string. Used when `type` is `FIXED` (exact amount each debit).
      - `numberOfPayments` string, required — Total recurring debits allowed. Any positive integer from `1` to `N`, or `"N"` for unlimited / infinite recurring debits.
      - `frequency` 'ONDEMAND' | 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'HALFYEARLY' | 'YEARLY', required — Mandate schedule label (`ONDEMAND`, `WEEKLY`, `MONTHLY`, etc.). When **on-demand SI** is enabled on your MID, PayGlocal does **not** auto-debit on this schedule — you trigger each subsequent payment manually via the [SI sale API](/api-reference/standing-instructions/si-subsequent-payment), regardless of `frequency`.
      - `type` 'FIXED' | 'VARIABLE', required — `VARIABLE` (≤ `maxAmount`) or `FIXED` (exact `amount` each debit).

## Response `200`

Returned immediately from initiate. Redirect the customer to `data.redirectUrl`, then poll `data.statusUrl` or [Get Transaction Status](/api-reference/payments-v2/common/get-transaction-status). When mandate registration succeeds, `data.mandateId` may be present in `data`.

- ApiResponsePayDirectInitiateSI — Response envelope for PayDirect standing instruction initiate (`200`). `data` may include `mandateId`. No fields in this envelope are marked required.
  - `gid` string — PayGlocal transaction ID. Use for status, capture, and refund APIs.
  - `status` string — High-level status. Typically `INPROGRESS` immediately after initiate.
  - `message` string — Human-readable status message.
  - `timestamp` string — Response timestamp (`DD/MM/YYYY HH:MM:SS`).
  - `reasonCode` string — Success code on initiate (e.g. `200`). See `4xx` responses for error codes.
  - `data` InitiateResponseDataSI — Standing instruction registration may also return **`mandateId`** in `data` — store it for SI sale, status, and cancel.
    - `redirectUrl` string, uri — Redirect the customer's browser here via **HTTP GET** to complete 3DS / step-up.
    - `statusUrl` string, uri — Pre-authenticated URL to poll status after the customer completes payment.
    - `merchantTxnId` string — Echo of `merchantTxnId` from the initiate request body.
    - `mandateId` string — PayGlocal mandate identifier when `standingInstruction` was sent. Not returned on later transactions.
  - `errors` object, nullable — `null` on success.

## Other responses

- `400` — Invalid request or processing error. Common `reasonCode` values on initiate: | Reason code | Typical cause | |-------------|----------------| | `GL-400-001` | Invalid request fields or error processing request | | `GL-201-020` | Card domicile or card type not set up in merchant config; merchant configuration mismatch |
- `403` — The onboardingId does not belong to the authenticated partner.
- `429` — Too many requests with the same `merchantUniqueId`. `reasonCode` is typically `GL-400-001`.

---

[API](https://skmtc.net/payglocal/apis/payglocal-api.md) · [All operations](https://skmtc.net/payglocal/apis/payglocal-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payglocal/payglocal-api/revisions/498446abc56d/schema)