Skip to content

STC Pay Beta

Last updated: 31st August 2022

Start accepting payments using STC Pay, a favorite payment method in Saudi Arabia.

To learn more, reach out to your Customer Success Manager or support@checkout.com.

Model

Gateway

Payment flow

Redirect

Payment method type

Wallet

One-step payment

Authorization

Capture

Refund

Partial refund

Chargeback

Recurring payment

STC Pay has a 2-step process:


Request a payment

For the full API specification, see the API reference.

    post

    https://api.checkout.com/payments

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    {
    "amount": 1,
    "currency": "SAR",
    "source": {
    "type": "stcpay"
    },
    "success_url": "https://google.com/success",
    "failure_url": "https://google.com/failure",
    "reference": "ORD-5023-4E89",
    "capture": "true",
    "customer": {
    "email": "test@test.com",
    "name": "Louis Smith",
    "phone": {
    "country_code": "055",
    "number": "7877988"
    }
    },
    "processing_channel_id": "pc_ekaubqrravqupfxde7kxvd2t3i"
    }

    Response example

    If you receive a 202 Success response containing a status field set to Pending, your request was successful.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    {
    "id": "pay_zc6gq2wzgcauhhjxsltdmsudri",
    "status": "Pending",
    "reference": "ORD-5023-4E89",
    "customer": {
    "id": "cus_xxx",
    "email": "test@test.com",
    "name": "Louis Smith",
    "phone": {
    "country_code": "055",
    "number": "7877988"
    }
    },
    "_links": {
    "self": {
    "href": "http://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri"
    }
    }
    }

    Capture a payment

    Only full captures are supported.

    Endpoints

    For the full API specification, see the API reference.

      post

      https://api.checkout.com/payments/{id}/captures

      Request example

      1
      2
      3
      4
      5
      {
      "processing": {
      "otp_value": "966557877988"
      }
      }

      Response example

      1
      2
      3
      4
      5
      6
      7
      8
      {
      "action_id": "act_saksxakpjahuhjltfv654qoaim",
      "_links": {
      "payment": {
      "href": "http://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji"
      }
      }
      }

      Get details about a payment

      You can retrieve details about an existing STC Pay payment with the following endpoint.

      Use the details below to set up your request.

      Endpoints

      For the full API specification, see the API reference.

        get

        https://api.checkout.com/payments/{id}

        Response example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        {
        "id": "pay_fysbbiwwomyebab5afvewiytji",
        "requested_on": "2022-08-05T07:37:04.4237199Z",
        "source": {
        "type": "stcpay"
        },
        "amount": 1,
        "currency": "SAR",
        "payment_type": "Regular",
        "reference": "ORD-5023-4E89",
        "status": "Authorized",
        "approved": true,
        "balances": {
        "total_authorized": 1,
        "total_voided": 0,
        "available_to_void": 1,
        "total_captured": 0,
        "available_to_capture": 1,
        "total_refunded": 0,
        "available_to_refund": 0
        },
        "customer": {
        "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
        "email": "test@test.com",
        "name": "Louis Smith",
        "phone": {
        "country_code": "055",
        "number": "7877988"
        }
        },
        "_links": {
        "self": {
        "href": "https://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji"
        },
        "actions": {
        "href": "https://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji/actions"
        },
        "capture": {
        "href": "https://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji/captures"
        }
        }
        }

        Refund a payment

        STC Pay supports full, partial, and multiple partial refunds. You can refund a payment through the Dashboard or by using the refund API.

        Endpoints

        For the full API specification, see the API reference.

          post

          https://api.checkout.com/payments/{id}/refunds

          Request example

          1
          2
          3
          {
          "amount": 100
          }

          Response example

          1
          2
          3
          4
          5
          6
          7
          8
          {
          "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
          "_links": {
          "payment": {
          "href": "https://api.sandbox.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
          }
          }
          }

          Webhooks

          You may receive the following webhooks when using STC Pay.

          WebhookDescription

          payment_pending

          Sent when a merchant initiates the payment request.

          payment_approved

          Sent when the payment authorization is approved and the payment is ready for capture.

          payment_captured

          Sent when the payment has been successfully captured.

          payment_capture_declined

          Occurs when a capture is declined.

          payment_refunded

          Sent when the payment has been (fully or partially) refunded.

          payment_refund_declined

          Sent when a refund has been declined.

          View all of our webhook notifications.


          Testing STC Pay

          To start testing, contact your Customer Success Manager or Implementation Engineer to activate STC Pay payments in the sandbox environment.

          1. Create an STC Pay transaction as above, using the same customer.phone test values as shown in the payment request example.
          2. Capture the payment, using the same proccesing.otp_value test value provided in the payment capture example.