Welcome to GateKey Payment Gateway

Creates a new hosted checkout session and returns a checkoutUrl to redirect your customer to.

1. Return URL

During the Create Payment request, the merchant provides the URL to which the customer should be returned after the payment flow is completed.

The return URL is provided under:

{
  "callbackUrls": {
    "returnUrl": "https://merchant.example.com/payment/response"
  }
}

After the payment is completed, failed, or cancelled, the Payment Gateway sends the payment response to the configured:

callbackUrls.returnUrl

The response is submitted using an HTTP POST form submission.

2. Response Format

The Payment Gateway sends a single POST form parameter:

payload

The payload value is encoded using Base64URL encoding.

The individual payment response fields are not sent as separate form parameters.

Conceptually, the Payment Gateway sends:

<form
    method="POST"
    action="https://merchant.example.com/payment/response">

    <input
        type="hidden"
        name="payload"
        value="<BASE64URL_ENCODED_PAYMENT_RESPONSE>" />

</form>

The form is automatically submitted to the merchant's configured callbackUrls.returnUrl.

3. Example Create Payment Request

The merchant provides the return URL while creating the payment.

{
  "transaction": {
    "type": "SALE",
    "reference": "ORD-100234",
    "amount": {
      "value": "25.000",
      "currencyCode": "OMR"
    }
  },
  "callbackUrls": {
    "returnUrl": "https://merchant.example.com/payment/response"
  }
}

The Payment Gateway stores the provided returnUrl for the payment transaction.

After completion of the payment flow, the payment result is returned to this URL using an HTTP POST form submission.

4. Example Payment Gateway Response

The merchant application receives an HTTP POST similar to the following:

POST /payment/response HTTP/1.1
Host: merchant.example.com
Content-Type: application/x-www-form-urlencoded

payload=eyJwYXltZW50UmVmIjoiUEFZLTIwMjYwODE0MDAwMSIsInJlZmVyZW5jZSI6Ik9SRC0xMDAyMzQifQ

The value of payload is a Base64URL-encoded payment response.

The merchant application must not attempt to directly parse this value as JSON.

5. Payload Decoding

After receiving the POST request, the merchant application must first retrieve the payload form parameter and perform Base64URL decoding.

The recommended processing flow is:

HTTP POST
   |
   v
Read "payload"
   |
   v
Validate payload
   |
   v
Base64URL Decode
   |
   v
UTF-8 JSON
   |
   v
Parse JSON
   |
   v
Extract Response Fields
   |
   v
Verify Signature
   |
   v
Process Payment Result

After Base64URL decoding, the decoded bytes should be converted to a UTF-8 string before parsing the JSON response.

Conceptually:

encodedPayload = POST["payload"]

decodedBytes = Base64UrlDecode(encodedPayload)

decodedPayload = UTF8Decode(decodedBytes)

paymentResponse = JsonParse(decodedPayload)

6. Base64URL vs Standard Base64

Merchants must use a Base64URL decoder rather than assuming that the payload uses standard Base64 encoding.

Base64URL is a URL-safe variation of Base64.

The main character differences are:

Standard Base64    Base64URL

+                  -
/                  _

Base64URL values may also be transmitted without trailing = padding characters.

For example:

Standard Base64:
YWJjZGVmZw==

Base64URL:
YWJjZGVmZw

The merchant should use the native Base64URL decoding capability provided by the programming language or framework.

If the selected library requires Base64 padding, the application may need to restore the required = padding before decoding.

Important: Base64URL is an encoding format only. It does not provide encryption, authentication, or integrity protection.

7. Example Decoded Payload

After successfully decoding the Base64URL value, the merchant receives the Payment Gateway response in JSON format.

Example:

{
  "paymentRef": "PAY-202608140001",
  "reference": "ORD-100234",
  "status": "SUCCESS",
  "amount": "25.000",
  "currency": "OMR",
  "traceNumber": "483920",
  "authCode": "739281",
  "maskedCard": "512345******1234",
  "timestamp": "2026-08-14T10:30:25Z",
  "nonce": "74981af8",
  "signVersion": "v1",
  "signature": "..."
}

The exact fields returned in the response depend on the Payment Gateway transaction and response specification.

The decoded JSON response should be parsed using the standard JSON parser available in the merchant's programming language.

After parsing the payload, the merchant application can extract the required transaction and signature-related fields.

For example:

paymentRef
reference
status
amount
currency
traceNumber
authCode
maskedCard
timestamp
nonce
signVersion
signature

Important: The decoded payload must not yet be considered trusted. The merchant must perform signature verification before relying on the transaction status or processing the payment result.

Confirms the outcome of a checkout session after the customer completes (or abandons) authentication. Call this from your returnUrl or notifyUrl handler.

Polls the current status of a previously initiated payment using the same reference and tokens as Verify. In the source collection this shares the /payments/verify path with the Verify operation — confirm with your backend whether a dedicated /payments/status path exists before shipping this as a separate call.