Process GPay Payment Callback

Processes the callback returned by the Garanti Pay gateway after the customer completes the payment on the provider's hosted form.

The gateway posts its result to this endpoint. Query parameters present on the incoming callback URL are automatically merged with the POST body before validation, so fields returned via redirect query string are handled transparently alongside form-encoded fields.

The submitted payload is verified server-side using a gateway-specific HMAC hash. The gpinstallment value is resolved against the card's active instalment records and stored on the pre-order before order finalisation.

Preconditions:

• A payment option with payment_type: gpay must be selected on the pre-order

• A transaction identifier must be present on the pre-order

Processing Flow:

1. Merges GET query parameters from the callback URL into the submitted data

2. Validates gpay: true and success: true flags from the gateway

3. Resolves gpinstallment against the active instalment options for the pre-order's card and stores the resolved instalment on the pre-order

4. Verifies the full payload against the gateway's HMAC hash to confirm authenticity

5. Creates a return transaction record (transaction_type: return_back) with the payment outcome; the transaction identifier follows the format GPAY_{order_number}_{suffix}

6. On success: finalises the order, submits the basket, sends order confirmation email and SMS notifications, then advances to ThankYouPage

7. On failure: performs a full rollback — clears transaction_id and the redirect state, resets the order number, and sets card_info to null, returning the pre-order to the state it held at GPaySelectionPage

No dynamic settings apply to this page. All behaviour is determined by the static configuration of the Garanti Pay gateway.

post

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

Callback payload posted by the Garanti Pay gateway after the customer completes the payment on the provider's hosted form. All three fields are required. gpay and success must both be true for the payment to be accepted. gpinstallment carries the instalment count selected by the customer on the Garanti Pay form and is resolved against the active instalment options for the pre-order's card. The full payload (including any additional fields returned by the gateway) is also verified against a gateway-specific HMAC hash. Payloads that fail hash verification are rejected regardless of the gpay and success values.

gpayboolean · enumRequired

Garanti Pay authorisation flag returned by the gateway. Must be true; any other value is treated as a failed transaction.

Possible values:

successboolean · enumRequired

Payment success flag returned by the gateway. Must be true; any other value is treated as a failed transaction.

Possible values:

gpinstallmentstringRequired

Instalment count selected by the customer on the Garanti Pay hosted form (e.g. "1" for a single payment, "3" for three instalments). The value is resolved against the active instalment records for the pre-order's card. If no matching active instalment is found the resolved instalment on the pre-order is set to null.

Example: 3

Responses

200

GPay callback processed. On success the order is finalised and the flow advances to ThankYouPage. On failure a full rollback is performed and a validation error is returned so the customer may retry from the payment selection step.

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

post/orders/checkout/?page=GPayCompletePage

POST /orders/checkout/?page=GPayCompletePage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 48

"gpay=true&success=true&gpinstallment='3'"

{
  "context_list": [
    {
      "page_name": "ThankYouPage",
      "page_slug": "thankyoupage",
      "page_context": {
        "order_number": "ORD-20240101-00003",
        "redirect_url": "",
        "new_user": false
      }
    }
  ],
  "pre_order": {
    "number": "ORD-20240101-00003",
    "payment_option": {
      "pk": 12,
      "name": "Garanti Pay",
      "slug": "garanti-pay",
      "payment_type": "gpay"
    },
    "total_amount": "249.90",
    "installment": {
      "pk": 7,
      "installment_count": 3,
      "label": "3 Installments"
    },
    "is_guest": false,
    "is_post_order": false
  },
  "errors": null,
  "template_name": ""
}