--- 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` ## Request - Base URL: `https://api.onboard.payglocal.in` - URL: `https://api.onboard.payglocal.in/gl/v1/payments/initiate` - Auth: API key in header `x-gl-token-external` - TypeScript: (a function with typed inputs; its response is checked against the schema) **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.dev/payglocal/apis/payglocal-api.md) - [All operations](https://skmtc.dev/payglocal/apis/payglocal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/payglocal/apis/payglocal-api/revisions/498446abc56d?raw)