> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payglocal.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth Reversal

> Reverse (void) an authorized payment before it is captured.

## When to Use

Void an `AUTHORIZED` transaction that has not yet been captured. This releases the hold on the customer's card.

<Note>
  Only **full reversals** are supported. If the payment has already been captured, use the [Refund](/api-reference/payment/refund) service instead.
</Note>


## OpenAPI

````yaml POST /gl/v1/payments/{gid}/auth-reversal
openapi: 3.0.3
info:
  title: PayGlocal API
  description: >
    PayGlocal REST API covering merchant onboarding, payment initiation,
    refunds,

    capture, reversal, and standing-instruction (subscription) flows.
  version: '2.0'
  contact:
    name: PayGlocal Support
    email: merchant.support@payglocal.in
    url: https://payglocal.in
servers:
  - url: https://api.onboard.payglocal.in
    description: Onboarding — Production
  - url: https://api.onboard.uat.payglocal.in
    description: Onboarding — Sandbox
  - url: https://api.payglocal.in
    description: Payments — Production
  - url: https://api.uat.payglocal.in
    description: Payments — Sandbox
  - url: https://gcc.prod.payglocal.in
    description: MCA — Production
  - url: https://gcc.uat.payglocal.in
    description: MCA — Sandbox
security:
  - ApiKeyAuth: []
    DigestAuth: []
tags:
  - name: Merchant Onboarding
    description: Endpoints to create and manage merchant onboarding records.
  - name: Reference Data
    description: Lookup endpoints for static reference data (categories, codes).
  - name: Payment
    description: Payment initiation, refund, capture, reversal, and status endpoints.
  - name: Standing Instructions
    description: Subscription / recurring-payment mandate operations.
  - name: MCA
    description: >-
      Merchant Collection Account — virtual account fetch and transaction
      document upload.
paths:
  /gl/v1/payments/{gid}/auth-reversal:
    servers:
      - url: https://api.payglocal.in
        description: Production
      - url: https://api.uat.payglocal.in
        description: Sandbox
    post:
      tags:
        - Payment
      summary: Reverse Authorized Transaction
      description: >
        Voids an authorization-only transaction before it's captured. Full
        reversal only —

        no partial. Not valid against captured transactions (use Refund
        instead).
      operationId: reverseAuthorization
      parameters:
        - name: gid
          in: path
          required: true
          schema:
            type: string
          description: PayGlocal `gid` of the authorized transaction.
          example: gl_9c2645ed09edb22e
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
            example: {}
      responses:
        '200':
          description: Authorization reversed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                gid: gl_9c2645ed09edb22e
                status: REVERSED
                timestamp: 10/01/2026 15:00:00
                reasonCode: ''
                data:
                  gid: gl_9c2645ed09edb22e
                  status: REVERSED
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - JwsTokenAuth: []
components:
  schemas:
    TransactionRequest:
      type: object
      description: >
        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.
      properties:
        merchantTxnId:
          type: string
          description: >-
            Merchant's unique transaction identifier. Required for `/initiate`
            and SI sale.
          example: order_1712345678
        merchantUniqueId:
          type: string
          description: Merchant's secondary unique reference.
        refundType:
          type: string
          description: Full or partial refund indicator (used on refund calls).
          enum:
            - F
            - P
          example: F
        refundAction:
          type: string
          description: Refund lifecycle action.
        captureType:
          type: string
          description: Full or partial capture indicator (used on capture calls).
          enum:
            - F
            - P
          example: F
        captureTxn:
          type: boolean
          description: If true on `/initiate`, the transaction is auto-captured post-auth.
        paymentData:
          $ref: '#/components/schemas/Payment'
        riskData:
          $ref: '#/components/schemas/Risk'
        standingInstruction:
          $ref: '#/components/schemas/StandingInstruction'
          description: >
            **Mandatory** when registering a standing instruction on initiate.
            Omit for GPI-only sales without a mandate.
        merchantCallbackURL:
          type: string
          format: uri
          description: URL PayGlocal redirects to after payment completion.
        merchantCustomPayload:
          type: object
          additionalProperties:
            type: string
          description: Opaque merchant metadata echoed back in callbacks.
        dcc_indicator:
          type: boolean
          description: Set true to enable Dynamic Currency Conversion.
        dccReferenceGid:
          type: string
          description: PayGlocal DCC quote reference (when `dcc_indicator=true`).
    ApiResponse:
      type: object
      description: Standard PayGlocal response envelope (`GlocalApiResponse`).
      properties:
        gid:
          type: string
          description: PayGlocal global transaction ID.
          example: gl_9c2645ed09edb22e
        status:
          type: string
          description: High-level status of this API response.
          example: SUCCESS
        message:
          type: string
          description: Human-readable message.
        timestamp:
          type: string
          description: Response timestamp (DD/MM/YYYY HH:MM:SS).
          example: 10/01/2026 15:00:00
        reasonCode:
          type: string
          description: Empty on success; populated on failure.
          example: ''
        data:
          type: object
          description: Operation-specific payload. Shape varies by endpoint.
          additionalProperties: true
        errors:
          type: object
          additionalProperties:
            type: string
          description: Field-level validation errors (populated on 4xx).
    Payment:
      type: object
      description: Payment instrument + amount details for a transaction.
      required:
        - totalAmount
        - txnCurrency
      properties:
        totalAmount:
          type: string
          description: Transaction amount as a string (preserves decimal precision).
          example: '100.00'
        txnCurrency:
          type: string
          description: ISO 4217 currency code.
          example: INR
        cardData:
          $ref: '#/components/schemas/Card'
        billingData:
          $ref: '#/components/schemas/Billing'
        authenticationData:
          $ref: '#/components/schemas/Authentication'
    Risk:
      type: object
      description: Risk & analytics payload forwarded to fraud engines.
      properties:
        customerData:
          $ref: '#/components/schemas/Customer'
        shippingData:
          $ref: '#/components/schemas/Shipping'
        orderData:
          type: array
          items:
            $ref: '#/components/schemas/RiskItem'
    StandingInstruction:
      type: object
      description: >-
        Required on initiate when registering a mandate. Used on SI sale/status
        with `mandateId`.
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/SIData'
        action:
          type: string
          description: SI lifecycle action.
          enum:
            - REVOKE
            - PAUSE
            - RESUME
        mandateId:
          type: string
          description: PayGlocal-issued mandate identifier.
        schedulerId:
          type: string
        scheduledId:
          type: string
    CommonErrorResponse:
      type: object
      properties:
        gid:
          type: string
          example: gl_9c2645ed09edb22e
        timestamp:
          type: string
          example: 10/01/2026 15:00:00
        reasonCode:
          type: string
          example: VALIDATION_ERROR
        data:
          type: object
        errors:
          type: object
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    Card:
      type: object
      description: >-
        Raw card data. Required when initiating a card transaction with
        `paymentType=CARD`.
      properties:
        number:
          type: string
          description: Primary Account Number (PAN). Digits only.
          example: '4111111111111111'
        expiryMonth:
          type: string
          description: Two-digit expiry month.
          example: '12'
        expiryYear:
          type: string
          description: Four-digit expiry year.
          example: '2030'
        securityCode:
          type: string
          description: CVV / CVC.
          example: '123'
        type:
          type: string
          description: Card network (derived by PayGlocal if omitted).
          example: VISA
    Billing:
      type: object
      description: Billing address + contact details of the payer.
      properties:
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        emailId:
          type: string
          format: email
          example: john.doe@example.com
        callingCode:
          type: string
          example: '+91'
        phoneNumber:
          type: string
          example: '9999999999'
        addressStreet1:
          type: string
          example: 221B Baker Street
        addressStreet2:
          type: string
        addressCity:
          type: string
          example: Bengaluru
        addressState:
          type: string
          example: Karnataka
        addressStateCode:
          type: string
          example: KA
        addressPostalCode:
          type: string
          example: '560001'
        addressCountry:
          type: string
          description: ISO 3166-1 alpha-3 country code.
          example: IND
    Authentication:
      type: object
      description: 3DS / payer authentication preference.
      properties:
        type:
          type: string
          description: Authentication mode.
          enum:
            - 3DS
            - NO_THREE_DS
          example: 3DS
    Customer:
      type: object
      description: Payer identity for risk evaluation.
      properties:
        merchantAssignedCustomerId:
          type: string
          example: cust_12345
        firstName:
          type: string
        lastName:
          type: string
        emailId:
          type: string
          format: email
        callingCode:
          type: string
        mobileNumber:
          type: string
    Shipping:
      type: object
      description: Shipping address for physical-goods orders.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        emailId:
          type: string
          format: email
        addressStreet1:
          type: string
        addressStreet2:
          type: string
        addressCity:
          type: string
        addressState:
          type: string
        addressPostalCode:
          type: string
        addressCountry:
          type: string
          example: IND
    RiskItem:
      type: object
      description: Single line-item in the cart for risk analytics.
      properties:
        itemId:
          type: string
        itemName:
          type: string
        itemQuantity:
          type: integer
        itemPrice:
          type: string
        itemCategory:
          type: string
    SIData:
      type: object
      description: Mandate configuration in `standingInstruction.data`.
      required:
        - numberOfPayments
        - frequency
        - type
        - mode
      properties:
        maxAmount:
          type: string
          description: >-
            Maximum debit amount for recurring transactions. Only when `type` is
            `VARIABLE`.
          example: '15000'
        amount:
          type: string
          description: Fixed mandate debit amount. Mandatory when `type` is `FIXED`.
          example: '15000'
        numberOfPayments:
          type: string
          description: >-
            Total recurring debits allowed. Positive integer or `"N"` for
            unlimited.
          example: 'N'
        frequency:
          type: string
          description: >
            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.
          enum:
            - ONDEMAND
            - WEEKLY
            - BIWEEKLY
            - MONTHLY
            - QUARTERLY
            - HALFYEARLY
            - YEARLY
        type:
          type: string
          description: '`VARIABLE` (≤ `maxAmount`) or `FIXED` (exact `amount` each debit).'
          enum:
            - FIXED
            - VARIABLE
        mode:
          type: string
          enum:
            - REGISTER
            - PAYREGISTER
          description: '`REGISTER` or `PAYREGISTER`.'
          example: REGISTER
        startDate:
          type: string
          description: >-
            Mandate start date (`yyyyMMdd`). Must be after current date.
            Required for auto debit.
          example: '20260903'
        endDate:
          type: string
          description: Mandate end date (`yyyyMMdd`). Optional.
          example: '20280911'
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          description: Name of the field that failed validation.
          example: panNumber
        message:
          type: string
          description: Human-readable error message.
          example: Required field is missing
  responses:
    BadRequest:
      description: Validation error — missing or invalid fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
          examples:
            validationError:
              summary: Validation error example
              value:
                gid: gl_9c2645ed09edb22e
                timestamp: 10/01/2026 15:00:00
                reasonCode: VALIDATION_ERROR
                data: {}
                errors: null
                errorDetails:
                  - fieldName: paymentData.totalAmount
                    message: This field is required
    Unauthorized:
      description: Authentication failed — invalid API key or digest.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
          examples:
            unauthorizedError:
              summary: Unauthorized error example
              value:
                gid: gl_9c2645ed09edb22e
                timestamp: 10/01/2026 15:00:00
                reasonCode: UNAUTHORIZED
                data: {}
                errors: null
                errorDetails:
                  - fieldName: authorization
                    message: Invalid x-gl-token-external
    NotFound:
      description: The specified onboardingId does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-gl-auth
      description: Static API Key generated from the PayGlocal Partner Dashboard.
    DigestAuth:
      type: apiKey
      in: header
      name: x-gl-digest
      description: >
        Per-request HmacSHA256 signature, Base64-encoded, using your API Secret
        as the HMAC key.

        - For GET requests: sign the request URI path (e.g.
        `/gcc/v2/partner/merchant/onboard/business-category`), including query
        string if present.

        - For POST/PUT requests: sign the exact raw request body.
    JwsTokenAuth:
      type: apiKey
      in: header
      name: x-gl-token-external
      description: >
        RSA-signed JWS (JSON Web Signature) token carrying the request payload.

        - Header: `{ "alg": "RS256", "kid": "<merchant-key-id>", "iss":
        "<merchant-id>", "x-gl-enc": "false", "is-digested": "true" }`

        - Payload: the exact JSON body sent in the request (or its SHA-256
        digest when `is-digested=true`).

        - Signed with the merchant's RSA private key; PayGlocal verifies with
        the matching public key.

        Used by all `/gl/v1/payments/*` endpoints.

````