v1

latestOpenAPI 3.1.02026-07-26270268.6 KB

Merchant Initiated Transactions

post/pgw/api/v2/direct/pay/token

Request body

sessionidstring required

A session ID, is a unique identifier that a server generates as part of the create session API call and assigns to a merchant transaction for the duration of the session (15 min).

timestampstring required

payWithTokentrue | false required

callbackUrlstring

The URL where the payment gateway should send the callback after the transaction is completed. It must have a valid SSL certificate and start with 'https://'

signaturestring required

A parameter to ensure the security and authenticity of API communications. It involves generating a signature using the contents of the API request and secret keys, which is then sent along with the request.

merchantReferenceIdstring

A unique merchant identifier for the order. You can send your own reference ID using this field.

paymentOperationstring

initiatedBystring required

A value indicating whether the request is started from Merchant.

agreementIdstring required

This is a string value that represents the unique identifier of the card-on-file agreement to use. This ID must be agreed upon between the merchant and the payment gateway before the COF service can be used. It is recommended to use a unique value for each card-on-file agreement to avoid confusion or conflicts.

agreementTypestring required

This is a string value that represents the type of card-on-file agreement to use. There are different types of card-on-file agreements available, and the type of agreement used can affect how the customer's card information is stored and processed. The currently supported values are RECURRING and UNSCHEDULED.

tokenIdstring required

Response

200

responseMessagestring

detailedResponseMessagestring

languagestring

responseCodestring

detailedResponseCodestring

Example response

{
  "order": {
    "orderId": "cb6258c6-61d7-4764-c8b1-08db7c97c22f",
    "amount": 101,
    "totalAmount": 101,
    "settleAmount": 101,
    "currency": "SAR",
    "settleCurrency": "SAR",
    "language": "EN",
    "detailedStatus": "Paid",
    "status": "Success",
    "merchantId": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
    "merchantPublicKey": "a087f4ca-9890-407b-9c2f-7630836cc020",
    "parentOrderId": "d6461d2f-49ac-46c1-5a86-08db7c97ecf9",
    "merchantReferenceId": "MerchantReferenceId",
    "callbackUrl": "https://webhook.site/49bda391-8158-4bdc-a72b-ecd5607c7ad1",
    "tokenId": "03ce28f7-5a53-46d8-822e-08db663a4c5b",
    "initiatedBy": "Merchant",
    "agreementId": "123456789",
    "agreementType": "Unscheduled",
    "paymentOperation": "Pay",
    "transactions": [
      {
        "transactionId": "b964964c-cd18-4f2c-2116-08db7c97ed28",
        "type": "Pay",
        "status": "Success",
        "amount": 101,
        "currency": "SAR",
        "source": "DirectAPI",
        "authorizationCode": "200470",
        "rrn": "318807200470",
        "stan": "200470",
        "paymentMethod": {
          "type": "Card",
          "brand": "mastercard",
          "cardholderName": "sido",
          "maskedCardNumber": "512345******0008",
          "expiryDate": {
            "month": 1,
            "year": 39
          }
        },
        "codes": {
          "acquirerCode": "00",
          "acquirerMessage": "Approved",
          "responseCode": "000",
          "responseMessage": "Success",
          "detailedResponseCode": "000",
          "detailedResponseMessage": "The operation was successful"
        },
        "correlationId": "859bb1e9-5cec-4b80-9f19-b511f67bf323",
        "paymentAttemptId": "2b7231cf-a33d-4b11-8a31-c710fcc07804",
        "acquirer": {
          "batch": 20230707,
          "date": "0707",
          "id": "RIYADBANK_S2I",
          "merchantId": "3000000023",
          "settlementDate": "2023-07-07T00:00:00",
          "timeZone": "+0300",
          "transactionId": "123456789"
        },
        "authorizationResponse": {
          "commercialCard": "888",
          "commercialCardIndicator": "3",
          "financialNetworkCode": "777",
          "posData": "2034100000000",
          "posEntryMode": "102",
          "processingCode": "003000",
          "responseCode": "00",
          "transactionIdentifier": "123456789"
        },
        "createdDate": "2023-07-07T07:52:46.0803268",
        "createdBy": "PGW",
        "updatedDate": "2023-07-07T07:52:49.0314396Z",
        "updatedBy": "PGW"
      }
    ],
    "isTokenPayment": true,
    "paymentMethod": {
      "type": "Card",
      "brand": "mastercard",
      "cardholderName": "sido",
      "maskedCardNumber": "512345******0008",
      "expiryDate": {
        "month": 1,
        "year": 39
      }
    },
    "totalAuthorizedAmount": 101,
    "totalCapturedAmount": 101,
    "orderSource": "GeideaGateway",
    "paymentBrands": [
      "mastercard"
    ],
    "multiCurrency": {
      "authCurrency": "SAR",
      "authAmount": 101,
      "settleCurrency": "SAR",
      "settleAmount": 101
    },
    "isTest": true,
    "gatewayDecision": "ContinueToPayer",
    "createdDate": "2023-07-07T07:52:45.9954003Z",
    "createdBy": "PGW",
    "updatedDate": "2023-07-07T07:52:45.9954003Z"
  },
  "responseMessage": "Success",
  "detailedResponseMessage": "The operation was successful",
  "language": "EN",
  "responseCode": "000",
  "detailedResponseCode": "000"
}