--- title: "Refund Transaction" method: POST path: "/gl/v1/payments/{gid}/refund" tags: ["Payment"] --- # Refund Transaction `POST /gl/v1/payments/{gid}/refund` ## Request - Base URL: `https://api.payglocal.in` - URL: `https://api.payglocal.in/gl/v1/payments/{gid}/refund` - Auth: API key in header `x-gl-token-external` - TypeScript: (a function with typed inputs; its response is checked against the schema) Initiates a full or partial refund against a captured transaction. - `refundType=F` for a full refund (omit `totalAmount`). - `refundType=P` for a partial refund (`totalAmount` required). ## Path parameters - `gid` string, required ## Request body - object: Unified request body for payment initiation, capture, refund, reversal, and SI operations. Most fields are optional — which fields are required depends on the operation. See each endpoint's `required:` list for operation-specific rules. **Note:** `required:` lists are best-effort and derived from current integration examples — validate against your integration spec or contact your PayGlocal implementation lead. - `merchantTxnId` string: Merchant's unique transaction identifier. Required for `/initiate` and SI sale. - `merchantUniqueId` string: Merchant's secondary unique reference. - `refundType` 'F' | 'P', required: Full or partial refund indicator (used on refund calls). - `refundAction` string: Refund lifecycle action. - `captureType` 'F' | 'P': Full or partial capture indicator (used on capture calls). - `captureTxn` boolean: If true on `/initiate`, the transaction is auto-captured post-auth. - `paymentData` Payment: Payment instrument + amount details for a transaction. - `totalAmount` string, required: Transaction amount as a string (preserves decimal precision). - `txnCurrency` string, required: ISO 4217 currency code. - `cardData` Card: 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). - `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. - `authenticationData` Authentication: 3DS / payer authentication preference. - `type` '3DS' | 'NO_THREE_DS': Authentication mode. - `riskData` Risk: Risk & analytics payload forwarded to fraud engines. - `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[] - `itemId` string - `itemName` string - `itemQuantity` integer - `itemPrice` string - `itemCategory` string - `standingInstruction` StandingInstruction: Required on initiate when registering a mandate. Used on SI sale/status with `mandateId`. - `data` SIData, required: Mandate configuration in `standingInstruction.data`. - `maxAmount` string: Maximum debit amount for recurring transactions. Only when `type` is `VARIABLE`. - `amount` string: Fixed mandate debit amount. Mandatory when `type` is `FIXED`. - `numberOfPayments` string, required: Total recurring debits allowed. Positive integer or `"N"` for unlimited. - `frequency` 'ONDEMAND' | 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'HALFYEARLY' | 'YEARLY', required: Frequency of mandate execution. `ONDEMAND`: merchant triggers each payment. `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `HALFYEARLY`, `YEARLY`: system auto-initiates; first payment on `startDate`, subsequent payments at the configured gap. - `type` 'FIXED' | 'VARIABLE', required: `VARIABLE` (≤ `maxAmount`) or `FIXED` (exact `amount` each debit). - `mode` 'REGISTER' | 'PAYREGISTER', required: `REGISTER` or `PAYREGISTER`. - `startDate` string: Mandate start date (`yyyyMMdd`). Must be after current date. Required for auto debit. - `endDate` string: Mandate end date (`yyyyMMdd`). Optional. - `action` 'REVOKE' | 'PAUSE' | 'RESUME': SI lifecycle action. - `mandateId` string: PayGlocal-issued mandate identifier. - `schedulerId` string - `scheduledId` string - `merchantCallbackURL` string, uri: URL PayGlocal redirects to after payment completion. - `merchantCustomPayload` object: Opaque merchant metadata echoed back in callbacks. - `dcc_indicator` boolean: Set true to enable Dynamic Currency Conversion. - `dccReferenceGid` string: PayGlocal DCC quote reference (when `dcc_indicator=true`). ## Response `200` Refund accepted. - ApiResponse: Standard PayGlocal response envelope (`GlocalApiResponse`). - `gid` string: PayGlocal global transaction ID. - `status` string: High-level status of this API response. - `message` string: Human-readable message. - `timestamp` string: Response timestamp (DD/MM/YYYY HH:MM:SS). - `reasonCode` string: Empty on success; populated on failure. - `data` object: Operation-specific payload. Shape varies by endpoint. - `errors` object: Field-level validation errors (populated on 4xx). ## Other responses - `400`: Validation error — missing or invalid fields. - `401`: Authentication failed — invalid API key or digest. - `404`: The specified onboardingId does not exist. --- [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)