STC Pay via Checkout.com

Accept STC Pay payments from customers in Saudi Arabia with Checkout.com as the payment service provider (PSP). The customer enters the mobile number registered to their STC Pay wallet, then confirms the payment with the one-time code that STC Pay sends by SMS.

Supported workflows

Workflow	Supported
Payrails SDK	✔
Payrails API	✔
Delayed / Manual Capture	✖
Instant Capture	✔
Cancel / Void	✖
Refund / Reverse	✔
Save Instruments	✖
Merchant Initiated Transaction (MIT)	✖

Before you begin

Complete these steps before you send your first STC Pay payment through Checkout.com:

Set up a Checkout.com integration in your workspace. Follow the Checkout.com integration setup guide if you don’t have one yet.
Ask Checkout.com support to enable STC Pay on your Checkout.com account.
In the Payrails Portal, go to Settings → Integrations, open your Checkout.com integration, select STC Pay under Payment methods, and save.
Add STC Pay as a payment option in your workflow.

Request fields for Checkout.com

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to the PSP when you include them. STC Pay sends the one-time code to the phone number in the payer fields, so send the number there. The Payrails SDK collects it for you.

Field	Status	Description
`paymentComposition[].paymentInstrumentData.payerFields.phoneCountryCode`	Required	The dialing code of the customer’s phone, digits only, for example `966`.
`paymentComposition[].paymentInstrumentData.payerFields.phoneNumber`	Required	The mobile number registered to the customer’s STC Pay wallet, without the dialing code, for example `512345678`.
`meta.customer.name`, `meta.customer.lastName`	Optional	Sent to Checkout.com as the customer name.
`meta.customer.email`	Optional	Sent to Checkout.com as the customer email.
`meta.customer.country.code`	Optional	Sent to Checkout.com as the customer country.

To confirm the payment, send the code in the confirm request:

Field	Status	Description
`data.otp`	Required	The one-time code the customer received by SMS, digits only.

Authorize an STC Pay payment

Call authorize a payment with stcPay as the paymentMethodCode.

Authorize request

{
  "amount": {
    "value": "150.00",
    "currency": "SAR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "stcPay",
      "amount": {
        "value": "150.00",
        "currency": "SAR"
      },
      "paymentInstrumentData": {
        "payerFields": {
          "phoneCountryCode": "966",
          "phoneNumber": "512345678"
        }
      }
    }
  ],
  "meta": {
    "customer": {
      "email": "noura.alqahtani@example.com",
      "name": "Noura",
      "lastName": "Al-Qahtani"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

STC Pay sends the customer a one-time code by SMS. The payment stays in authorizePending, and the execution’s requiredAction has the type collectInput with the confirm link in requiredAction.href.

Confirm the payment with the code

Ask the customer for the code, then confirm the payment with the code in data.otp. Send the request to the requiredAction.href link.

Confirm request

{
  "data": {
    "otp": "123456"
  }
}

After you send the code, the payment stays in authorizePending until Checkout.com sends the final result. Confirm the result through webhook notifications or the execution status before you fulfill the order. The Web SDK shows STC Pay when your workflow returns it as a payment option. The SDK collects the customer’s phone number, then shows a screen where the customer enters the code STC Pay sends by SMS and clicks Confirm. Follow How to accept APMs without a redirect for the full integration, including how to change the form’s appearance and texts.

STC Pay is supported in Web SDK version 6.10.0 onwards.

How Checkout.com handles STC Pay

Payrails creates the STC Pay payment through the Checkout.com Payment Setup API. Checkout.com needs no payment token for STC Pay.
Payrails checks the phone number before it calls Checkout.com, and sends it to Checkout.com on the customer.
The code is valid for 5 minutes.
Payrails sends the merchant reference to Checkout.com, cut to 80 characters.
Checkout.com sends the final result as a webhook notification.
Each STC Pay payment is a new customer-initiated payment.

Getting Started

Payment Orchestration

Merchant of Record

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

STC Pay via Checkout.com

Supported workflows

Before you begin

Request fields for Checkout.com

Authorize an STC Pay payment

Confirm the payment with the code

How Checkout.com handles STC Pay

​Supported workflows

​Before you begin

​Request fields for Checkout.com

​Authorize an STC Pay payment

​Confirm the payment with the code

​How Checkout.com handles STC Pay

Supported workflows

Before you begin

Request fields for Checkout.com

Authorize an STC Pay payment

Confirm the payment with the code

How Checkout.com handles STC Pay