Payments Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose: This guide is written for application developers who want to use the REST API to integrate payment card processing into an order management system.

This guide describes merchant integrations with the National Payment Gateway processor.

Implementing the Cybersource payment services requires software development skills. You must write code that uses the API request and response fields to integrate the payment card services into your existing order management system.
Conventions: These statements appear in this document:
IMPORTANT

An Important
statement contains information essential to successfully completing a task or learning a concept.

WARNING

A Warning
contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.

Related Documentation: Visit the Cybersource documentation hub to find additional processor-specific versions of this guide and additional technical documentation.

Customer Support: For support information about any service, visit the Support Center:
http://support.visaacceptance.com

Pilot Release

This document is for the pilot release of Payments for the National Payment Gateway processor.

Recent Revisions to This Document

26.09.01

Transaction Timeout Guidance: Added guidance for transaction timeouts. See Transaction Timeout Guidance.

26.05.01

This revision contains only editorial changes and no technical updates.

26.04.01

Initial pilot release for National Payment Gateway.

Introduction to Payments

This introduction provides the basic information that you need to successfully process payment transactions. It also provides an overview of the payments industry and provides workflows for each process.

With Cybersource payment services, you can process payment cards (tokenized or non-tokenized), digital payments such as Apple Pay and Google Pay, and customer ID transactions. You can process payments across the globe and across multiple channels with scalability and security. Cybersource supports a large number of payment cards and offers a wide choice of gateways and financial institutions, all through one connection.

Visit the Cybersource documentation hub to find additional processor-specific versions of this guide and additional technical documentation.

`National Payment Gateway` Processor Overview

The Saudi Arabian government requires that all payment data generated within the kingdom be stored and processed locally. To support this, they’ve introduced the National Payment Gateway (NPG). It is the central hub for all card and digital payments in Saudi Arabia.

All payment service providers—including gateways, acquiring banks, issuing banks, and fintechs—must connect to National Payment Gateway. This is a regulatory requirement enforced by Saudi Payments, under the supervision of the Saudi Arabian Monetary Authority (SAMA).

Cybersource has established a secure connection to National Payment Gateway. All domestic transactions (Visa, Mastercard, and Mada) in Saudi Arabia are routed through NPG to the respective card schemes. Other card schemes will continue using existing routes until NPG expands its coverage.

Cybersource has migrated key components of its platform—including processing, settlement, and reporting—into a private cloud data center located in Saudi Arabia. This ensures full compliance with local data residency laws. Integrations in this Saudi cloud are available only through REST APIs and for payment methods approved by the kingdom.

Financial Institutions and Payment Networks

Financial institutions and payment networks enable payment services to function. These entities work together to complete the full payment cycle.

Merchant Financial Institutions (Acquirers)

A merchant financial institution, also known as an acquirer
, offers accounts to businesses that accept payments. Before you can accept payments, you must have a merchant account from an acquirer. Your merchant account must be configured to process card-not-present or mail-order/telephone-order (MOTO) transactions.

You can expect to pay these fees:

Discount rates: your acquirer charges a fee and collects a percentage of every transaction. The combination of the fee and the percentage is called the discount rate
. These charges can be bundled
(combined into a single charge) or unbundled
(charged separately).

Interchange fees: payment networks, such as Visa or Mastercard, each have a base fee, called the interchange fee
, for each type of transaction. Your acquirer and processor can show you ways to reduce this fee.

Chargebacks: when cardholders dispute charges, you can incur chargebacks
. A chargeback occurs when a charge on a customer’s account is reversed. Your acquirer removes the money from your account and could charge you a fee for processing the chargeback.

Take these precautions to prevent chargebacks:

Use accurate merchant descriptors so that customers can recognize the transactions on their statements.

Provide good customer support.

Ensure rapid problem resolution.

Maintain a high level of customer satisfaction.

Minimize fraudulent transactions.

If excessive chargebacks or fraudulent changes occur, these actions might be taken:

You might be required to change your business processes to reduce the number chargebacks, fraud, or both.

Your acquiring institution might increase your discount rate.

Your acquiring institution might revoke your merchant account.

Contact your sales representative for information about products that can help prevent fraud.

Customer Financial Institutions (Issuers)

A customer financial institution, also known as an issuer
, provides payment cards to and underwrites lines of credit for their customers. The issuer provides monthly statements and collects payments. The issuer must follow the rules of the payment card companies to which they belong.

Payment Networks

Payment networks manage communications between acquirers and issuing banks. They also develop industry standards, support their brands, and establish fees for acquiring institutions.

Some payment networks, such as Visa and Mastercard, are trade associations that do not issue cards. Issuers are members of these associations, and they issue cards under license from the association.

Payment Processors

Payment processors connect with acquirers. Before you can accept payments, you must register with

a payment processor

.

An acquirer might require you to use a payment processor with an existing relationship with the acquirer.

Your payment processor

assigns one or more merchant ID to your business. These unique codes identify your business during payment transactions.

This table lists the processors and corresponding card types that are supported for payment services.

IMPORTANT

Only the card types explicitly listed here are supported.

Payment Processor and Supported Card Types
Payment Processor	Supported Card Types	Notes
`National Payment Gateway`	mada, Mastercard, Visa	Supported currency: Saudi Riyal (SAR)

Card Types

You can process payments with these kinds of cards:

Credit cards

Debit cards

Prepaid cards

For a list of supported card types, see Payment Processors.

Co-Badged Cards

Co-badged cards are credit and debit cards that integrate two or more payment networks.

Co-Branded Cards

Co-branded cards are credit cards that are branded with a merchant's logo, brand, or other identifier as well as the payment network logo. These cards are not limited for use at the branded merchant and can be used at any merchant that accepts credit cards.

Credit Cards

Cardholders use credit cards to borrow money from issuing banks to pay for goods and services offered by merchants that accept credit cards.

Debit Cards

A debit card is linked to a cardholder's bank account. The funds are taken out of the customer's bank account, and the transaction is included on the customer's bank account statement. The customer does not receive a credit card bill as with a regular credit card.

Transaction Types

This topic provides information about transaction types that are supported by your processor.

Card-Not-Present Transactions

When a customer provides a card number, but the card and the customer are not physically present at the merchant's location, the purchase is known as a card-not-present transaction
. National Payment Gateway card-not-present transactions can be initiated either by the cardholder or the merchant.

National Payment Gateway transactions and card types are list in this table:

	mada	Mastercard	Visa
Account Verification	NA	Yes	Yes
Pre-Authorization	Yes	Yes	Yes
Pre-Authorization Extension	Yes	Yes	Yes
Authorizatin Reversal	Yes	Yes	Yes
Sale	Yes	Yes	Yes
Refund	Yes	Yes	Yes
Capture	Yes	Yes (Offline)	Yes (Offline)
Multiple Partial Capture	Yes	Yes (Offline)	Yes (Offline)
Refund (Pre-auth Completion/Capture)	Yes	Yes (Offline)	Yes (Offline)
Refund a Sale due to timeout, format error, or authorization extension response	Yes	NA	NA

Payment Services

Various services are involved in processing payments.

These services enable customers to purchase goods and services. They also enable merchants to receive payments from customer accounts, to provide refunds, and to void transactions.

Authorization

An authorization confirms that a payment card account holds enough funds to pay for a purchase. Authorizations can be made online or offline.

Account Verification

Account verification is available for international cards only, not for mada cards.

Pre-Authorization

A pre-authorization enables you to authorize a payment when the final amount is unknown. The system places the funds on hold until you request a follow-up transaction. Pre-authorizations are typically used for lodging, auto rental, e-commerce, and restaurant transactions.

IMPORTANT

Payment Services Directive 2 (PSD2) rules in the European Union (EU) and European Economic Area (EEA) require the initial pre-authorization to use strong customer authentication for merchants or customers in PSD2-applicable countries.

When you have a specific merchant category code (MCC) assigned to your account, you are allowed to capture up to 20% more than the cumulatively authorized amount on Visa, Diners Club, Discover, and JCB cards. Contact your account manager to have your account enabled for this option.

The pre-authorization lasts for 14 calendar days unless you capture the payment, void it, or extend it. After 14 days, if you do not request a follow-up transaction, the system releases the hold and the funds become available to the cardholder again.

Pre-Authorization Extension

A pre-authorization extension is a follow-up to a pre-authorization that keeps the hold in place for an additional 14 days, giving you a maximum hold of 28 days. You are allowed to send only one extension for each pre-authorization. With Visa and Mastercard you may also change the held amount when you request the extension. With Mada you can only extend the time, not change the amount.

Authorization Workflow

This image and description show the authorization workflow:

The National Payment Gateway authorization flow includes authentication using VISA, Mastercard, or mada directory servers.

The cardholder enters card details on the merchant website or app to make a purchase. Merchant stores transaction data, including card information and PII data.

The merchant sends the authorization request to Cybersource.

Cybersource processes the authentication request using the directory servers. Cybersource also processes the payment request and sends it to National Payment Gateway.

National Payment Gateway processes the request and sends it to the card network for further processing. The card network also stores the transaction data for settlement processing.

The card network sends the authorization request to the issuer for approval. The issuer also stores the data for further settlement process.

The issuer sends the authorization response (transaction approved or rejected) to the card network.

The card network sends the response to National Payment Gateway.

National Payment Gateway stores the response data and sends it to Cybersource.

Cybersource stores the response data and sends it to the merchant.

The merchant stores the response data and sends a payment confirmation to the cardholder.

Sale

A sale is a bundled authorization and capture. Some processors and acquirers require a sale transaction instead of using separate authorization and capture requests. For other processors and acquirers, you can request a sale instead of a separate authorization and capture when you provide the goods or services immediately after taking an order.

National Payment Gateway requires payer authentication data in sale requests.

After a successful sale the only action you can take later is to issue a refund.

Single-Message Processing

Single-message processing treats the authorization and capture as a single transaction. There are important differences between dual-message processing and single-message processing:

Single-message processing treats the request as a full-financial transaction, and with a successful transaction, funds are immediately transferred from the customer account to the merchant account.

Authorization and capture amounts must be the same.

Some features cannot be used with single-message processing.

Authorization Reversal

The authorization reversal service releases the hold that an authorization placed on a customer’s payment card funds.

Each card-issuing financial institution has its own rules for deciding whether an authorization reversal succeeds or fails. When a reversal fails, contact the card-issuing financial institution to learn whether there is a different way to reverse the authorization.

An authorization reversal is a follow-on transaction that uses the request ID returned from an authorization. The main purpose of a follow-on transaction is to link two transactions. The request ID links the follow-on transaction to the original transaction. The authorization request ID is used to look up the customer’s billing and account information in the Cybersource database. You are not required to include those fields in the full authorization reversal request. The original transaction and follow-on transaction are linked in the database and in

the

Business Center.

For processors that support debit cards and prepaid cards, the full authorization reversal service works for debit cards and prepaid cards in addition to credit cards.

IMPORTANT

You cannot perform an authorization reversal if a transaction is in a review state, which can occur if you use a fraud management service. You must reject the transaction prior to authorization reversal. For more information, see the fraud management documentation in

the

Business Center.

Capture

A capture is a follow-on transaction to an authorization. It is used to transfer the authorized funds from the customer's account to the merchant account. To link the authorization transaction to the capture transaction, you include a request ID in your capture request. This request ID is returned to you in the authorization response.

The capture, also called a completion, must be sent before the 14-day hold created by the pre-authorization expires. You can request a single final capture for the full amount, or one or more partial captures for smaller amounts. When you are processing a mada card transaction, the total captured amount can not exceed the original authorization. Visa and Mastercard allow captures above the authorized amount, also known as over captures, but mada does not support this and advises acquirers to not allow merchants to use it. Over captures typically occur during a capture when merchants finalize the transaction for more than the initial authorization amount. There are strict rules and limits for over captures, and you must follow the National Payment Gateway guidelines.

When fulfilling only part of a customer’s order, do not capture the full amount of the authorization. Capture only the cost of the delivered items. When you deliver the remaining items, request a new authorization, and then capture the new authorization.

IMPORTANT

It is not possible to perform a capture if a transaction is in a review state, which can occur if you use a fraud management service. You must accept the transaction prior to capture. For more information, see the fraud management documentation in

the

Business Center.

Capture Workflow

The capture workflow begins when you send a request for a capture.

The merchant sends a request for a capture to the Cybersource gateway.

For online captures, Cybersource validates the order information then sends an online capture to the payment processor.

The processor validates the request and forwards it to the issuing bank.

The issuing bank transfers funds to the acquiring bank.

For National Payment Gateway, Cybersource handles captures for Mastercard and Visa offline through the TC33 capture file with your acquirer. National Payment Gateway handles mada card captures online with your acquirer.

IMPORTANT

The payment processor does not notify Cybersource that the money has been transferred. To ensure that all captures are processed correctly, you should reconcile your capture requests with the capture reports from your processor.

Refund

Refunds are payment refunds from a merchant to the cardholder after a cardholder pays for a product or service and that payment is captured by the merchant. When a refund request is successful, the issuer transfers funds from the merchant bank (acquirer) account to the customer's account. It typically takes 2 to 4 days for the acquirer to transfer funds from your merchant account.

There are two types of refunds: a follow-on refund
that is linked to an original capture or sale, and a stand-alone credit
that is not linked to an original capture or sale.

IMPORTANT

National Payment Gateway does not support stand-alone credits.

WARNING

You should carefully control access to your

refund and

credit services. Do not request this service directly from your customer interface. Instead, incorporate this service as part of your customer service process. This process reduces the potential for fraudulent transactions.

Follow-on Refund

For National Payment Gateway, a

refund

is the only way to reverse a payment after clearing and settlement are complete. The request must reach the issuer within 30 calendar days of the original payment date—counted from the sale date or the capture date for a pre-authorization. After 30 days, the merchant must contact its acquirer, who can work with mada through the Claim Processing System (CPS) to arrange the follow-on

refund

offline. A refund can cover the full amount or just part of it, and it must go to the same card and be in the same currency as the original transaction. Multiple follow-on

refunds

transactions are allowed as long as their total does not exceed the amount that was captured. When multiple captures exist, each capture requires its own linked refund. National Payment Gateway does not allow fees deducted from the amount returned to the customer. If a merchant shows an unusually high or repetitive follow-on

refunds

pattern, the acquirer should alert National Payment Gateway.

Refund and Credit Workflow

This workflow applies to follow-on credits, also known as refunds, and stand-alone credits. It begins when you send a request for a refund or credit.

Refunds and credits do not happen in real time. All of the credit requests for a day are typically placed in a file and sent to the processor as a single batch
transaction. In most cases, the batch transaction is settled overnight.

The merchant sends the refund or credit request to Cybersource.

For online refunds and credits, Cybersource validates the order information then sends the request to the payment processor.

For offline refunds and credits, Cybersource stores the request in a batch file and sends the batch file to the payment processor after midnight.

The processor validates the request and forwards it to the acquiring bank.

The acquiring bank transfers funds to the issuing bank.

IMPORTANT

Not all processors support stand-alone credits.

For National Payment Gateway, Cybersource processes refunds and credits for Mastercard and Visa offline. National Payment Gateway processes mada card refunds and credits online with your acquirer.

Payment Features

You can apply features to different payment services to enhance the customer payment processing experience. This section includes an overview of these features:

3-D Secure Authentication for National Payment Gateway

`3-D Secure` Authentication for `National Payment Gateway`

Cybersource supports both bundled and unbundled authentications for card transactions.

Mastercard and Visa cards: No changes to the existing authentication process.

mada cards: A dedicated mada directory server handles authentication. National Payment Gateway regulations allow only fully authenticated mada transactions. If authentication fails, the transaction will be rejected at the Cybersource level.

Co-Badged Cards (mada + Visa or Mastercard)

If the mada directory server is unavailable, authentication falls back to the co-badged card brand’s directory server (Visa or Mastercard).

In these cases, additional authentication data must be included in the authorization request so National Payment Gateway can identify which party performed the authentication.

Bundled and Unbundled Authentications

Bundled authentication: Cybersource automatically processes and maps the required authentication data to the authorization request.

Unbundled authentication: Retrieve these field values from the authentication response and include them in your authorization request:

consumerAuthenticationInformation.acsOperatorID

consumerAuthenticationInformation.acsReferenceNumber

consumerAuthenticationInformation.authenticationBrand

consumerAuthenticationInformation.dsReferenceNumber

consumerAuthenticationInformation.threeDSServerOperatorID

Use Case	Details
I include `3-D Secure` for payer authentication in authorization requests.	`Cybersource` payer authentication service maps the authentication data into the authorization request on your behalf.
I request `Cybersource` payer authentication and the payment authorization separately in unbundled requests.	The payer authentication response includes the values for these fields: consumerAuthenticationInformation.acsReferenceNumber : required for the separate authorization. consumerAuthenticationInformation.dsReferenceNumber : required for the separate authorization request. consumerAuthenticationInformation.acsOperatorID : for reference only. consumerAuthenticationInformation.threeDSServerOperatorID : for reference only. consumerAuthenticationInformation.authenticationBrand : identifies the card brand that performed authentication during fall back. Fallback occurs when the directory server is unavailable and authentication falls back to a different directory server.
I use `Cybersource` for payer authentication only. I have a different provider for authorization.	The payer authentication response includes the values for these fields: consumerAuthenticationInformation.acsReferenceNumber : required for the separate authorization. consumerAuthenticationInformation.dsReferenceNumber : required for the separate authorization request. consumerAuthenticationInformation.acsOperatorID : for reference only. consumerAuthenticationInformation.threeDSServerOperatorID : for reference only. consumerAuthenticationInformation.authenticationBrand : identifies the card brand that performed authentication during fall back. Fallback occurs when the directory server is unavailable and authentication falls back to a different directory server.
I have a direct connection to an authentication provider and use `Cybersource` for authorization only.	Provide all the authentication details required to process transaction through `National Payment Gateway` to be compliant with `National Payment Gateway` standards.

Testing the Payment Services

To ensure that requests are processed correctly, you must test the basic success and error conditions for each service you plan to use.

Requirements for Testing

Before you can test, contact customer support to activate the credit card services and configure your account for testing. You must also contact your processor to set up your processor account.

IMPORTANT

When building your connection to the Cybersource payment gateway, ensure that you have implemented controls to prevent card testing or card enumeration attacks on your platform.

For more information, see the best practices guide.

When we detect suspicious transaction activity associated with your merchant ID, including a card testing or card enumeration attack, Cybersource reserves the right to enable fraud management tools on your behalf in order to mitigate the attack. The fraud team might also implement internal controls to mitigate attack activity. These controls block traffic that is perceived as fraudulent. Additionally, if you are using one of our fraud tools and experience a significant attack, our internal team might modify or add rules to your configuration to help prevent the attack and minimize the threat to our infrastructure. However, any actions taken by Cybersource would not replace the need for you to follow industry standard best practices to protect your systems, servers, and platforms.

Follow these requirements when you test your system:

Use your regular merchant ID.

Use a real combination for the city, state, and postal code.

Use a real combination for the area code and telephone number.

Use a nonexistent account and domain name for the customer’s email address.

REST API test endpoint:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Test Card Numbers

Use these payment card numbers to test the authorization, capture, and credit services. Remove the spaces from the test card numbers when sending them to the test system. Do not use real payment card numbers. To test card types that are not included in the list, use an account number that is in the card’s BIN range. For best results, try each test with a different service request and with different test payment card numbers.

IMPORTANT

The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with these card numbers, remove the spaces and replace each X with a 0 (zero).

mada Prepaid: 9682 X873 4543 324X

mada Token: 5X69 6831 4127 7723

Visa-mada Co-badged: 42X1 3220 3021 7878

Mastercard-mada Co-badged: 5297 41X9 81X4 4847

Visa: 4111 1111 1111 1111

Mastercard: 5555 5555 5555 4444

Using Amounts to Simulate Errors

You can simulate error messages by requesting authorization, capture, or credit services with specific amounts that trigger the error messages. These triggers work only on the test server, not on the production server.

Each payment processor uses its own error messages.

For more information, see: REST API Testing Guide

Transaction Timeout Guidance

This topic provides guidance for handling scenarios in which a payment request submitted to Cybersource does not return a definitive status because of a timeout or other communication failure. It focuses on the most common timeout scenarios and describes the supported mechanisms for determining the final transaction status.

This guidance helps you minimize the operational and financial risks associated with an uncertain transaction status. It addresses two common risks: how to treat an unknown status as a failed transaction, which can result in false declines, and retrying a transaction without first validating its status, which can lead to duplicate authorizations or duplicate charges.

A timeout represents an unknown transaction status, which is not necessarily a transaction failure.

Related payment services:

Authorization Reversal

Incorrect Timeout Handling Risks

Each payment timeout creates a moment of uncertainty. How your team handles that moment determines whether it becomes a non-event, a customer complaint, a chargeback, or a lost sale. This table describes what goes wrong, the customer experience, and your business risk.

Timeout Situations
What Goes Wrong	Customer Experience	Business Risk
The timeout is misread as a failure. You retry the transaction immediately, and it is processed twice.	Customer sees two charges on their statement.	Chargeback, refund cost, trust damage, and potential dispute fees.
The timeout is misread as a failure. You present a payment-failed message, and the customer abandons checkout.	Customer believes the card was declined. The customer tries another payment method or abandons the purchase.	Lost revenue. The original payment might still be authorized on the card.
No unique transaction ID is present. As a result, duplicate detection fails and multiple authorizations occur.	Multiple holds or charges appear on the same card for one order.	Disputes, regulatory risk, and manual reconciliation overhead.
You configure the client timeout too short. As a result, you drop the connection and the transaction status is unknown.	A spinner suddenly disappears with no clear result.	Unknown order status, manual intervention, and customer contact with support.

IMPORTANT

You must systematically resolve an unknown transaction status before you take additional payment actions. Each recommendation transforms an uncertain transaction status into an additional action.

Transaction Flow and Failure Taxonomy

A single payment authorization transaction traverses multiple independent participants within the payment ecosystem. Each connection point can experience latency, communication failures, or timeout conditions.

End-to-End Authorization Flow

The transaction passes through these participants:

Cardholder to Merchant:
The cardholder initiates a payment transaction through a website, mobile application, point-of-sale system, or digital wallet.

Merchant to Cybersource:
The merchant submits the authorization request to Cybersource for routing and processing.

Processor routing:
Cybersource forwards the transaction to the appropriate processor.

Card network routing:
The processor routes the request through the applicable payment network.

Issuer decision:
The card issuer evaluates the transaction and returns an authorization decision.

The transaction must follow the same path in reverse to be successful. Any break in that return path leaves the transaction status unknown to the merchant. This image shows the end-to-end authorization flow:

These are the reason codes most relevant to timeout handling:

ESYSTEM
:
General system error or server-side failure. The transaction status is unknown. Do not treat as a definitive failure. Perform a status check before any retry or an authorization reversal.

ETIMEOUT
:
Server-side timeout. Cybersource received the request but could not return a response within the processing window. The transaction status is unknown. Reconcile before retrying.

DUPLICATE_REQUEST
:
Duplicate request declined. Cybersource identified the authorization as a duplicate of a previous request with the same merchant reference. Do not retry with the same reference, because the original transaction might have succeeded. Perform a status check first.

Timeout Scenarios and Recommended Actions

These are the four distinct timeout scenarios.

Scenario: Request Never Reached `Cybersource`

Duplicate risk:
none

Condition:
The request never reached Cybersource because of a connection issue. As a result, you received no acknowledgment or response from Cybersource.

Recommended Action:
After a few seconds, perform a transaction status lookup using the

clientReferenceInformation.code

field before you resubmit the authorization. If the lookup returns no transaction record, resubmit the original authorization request.

Scenario: `Cybersource` Internal Failure

Duplicate risk:
low

Condition:
Cybersource receives the request but cannot continue processing because a required internal service is timing out, for example Decision Manager, Token Management Service (TMS), Payer Authentication, or internal routing. Because the transaction never progresses into the downstream payment ecosystem, Cybersource does not submit an authorization to the processor, card network, or issuer.

Example: Internal Failure Response
HTTP Status Code:

502

{
  "id": "7871896614436518804807",
  "submitTimeUtc": "2026-08-20T01:34:21Z",
  "status": "SERVER_ERROR",
  "reason": "SERVICE_TIMEOUT",
  "message": "The request was received, but a service did not finish running in time"
}

Recommended Actions:

Retry the authorization after a delay of approximately 30 seconds to allow any internal transient issue to resolve.

If the error persists, place the authorization in a delayed resubmission queue if possible.

Monitor for recovery by confirming successful processing of subsequent transactions or notification that the service issue is resolved.

Once recovery is confirmed, resubmit the original authorization request from the delayed resubmission queue.

Scenario: Request Received, Processor Response Took Too Long

Duplicate risk:
high

Condition:
Cybersource accepted the request and invoked the authorization request to the processor, but did not get the response within the timeout period. As a result, the transaction might already have been approved even though the final status was not returned to you.

Example: Processor Timeout Response
HTTP Status Code:

502

{
  "id": "7871927193766252604807",
  "submitTimeUtc": "2026-08-20T02:25:49Z",
  "status": "SERVER_ERROR",
  "reason": "SERVER_TIMEOUT",
  "message": "Error - The request was received but there was a server timeout. This error does not include timeouts between the client and the server."
}

Recommended Actions:

Retry the authorization.

For the first transaction since a timeout occurred, Cybersource proactively initiates an automatic authorization reversal as a protective measure in case the original authorization was approved but the final status could not be confirmed.

Perform a status lookup using the generated request

id

returned in the first authorization response after some time, and verify the final status of the automatic authorization reversal.

If the authorization reversal status cannot be confirmed, check with the processor or contact Cybersource customer support.

Scenario: Approved, but Confirmation Never Received

Duplicate risk:
highest

Condition:
The authorization was approved, but you did not receive the response because of a connectivity or network issue, or because you use a short timeout window. This is the highest-risk scenario for duplicate charges.

Recommended Actions:

If you use a short timeout and plan to retry the authorization, wait up to 60 seconds before you take further action. Perform a transaction status lookup using the original

clientReferenceInformation.code

to determine the status of the original authorization request. If the transaction is found and approved, record the result.

If you perform a second authorization before verifying the status of the original authorization, you must reverse the original authorization. Use the merchant ID in the

clientReferenceInformation.transactionId

field from the original authorization request to submit an authorization reversal. Alternatively, use merchant reference code in the

clientReferenceInformation.code

field in transaction search to get the request ID and process the authorization reversal.

Example: Reversal Using the Transaction ID

Endpoint: POST /pts/v2/reversals

{
  "clientReferenceInformation": {
    "transactionId": "987654321"
  },
  "reversalInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "ABC"
    }
  }
}

Verifying a Transaction Status

There are three methods for determining the accurate status of a transaction before you act on a timeout.

Transaction Search API

When a timeout or communication failure occurs, use the REST API transaction search to determine whether the original authorization request was successfully processed.

Query using the request ID whenever available.

If the request ID is not available, query using the REST merchant reference code

clientReferenceInformation.code

field.

Transaction Search Best Practices

Use the minimum date range required to locate a transaction. Avoid broad date-range searches when checking transaction status unless there is a specific business need.

Do not use transaction search for high-volume or frequent status checks. This can result in rate limiting.

For ongoing transaction status monitoring, use the payment status API where appropriate.

Include only the search criteria necessary to identify the transaction.

When searching for multiple request IDs, use the dedicated request ID filter instead of free-text search fields.

Example: Transaction Search Request

Endpoint: POST /tss/v2/searches
{
  "save": "false",
  "name": "Transaction Recovery Search",
  "timezone": "America/Chicago",
  "query": "clientReferenceInformation.code:{merchant_reference_code} AND submitTimeUtc:[NOW-1HOUR TO NOW/DAY+1DAY]",
  "offset": 0,
  "limit": 100,
  "sort": "id:asc,submitTimeUtc:asc"
}

For the full request and response schema and a list of supported search fields, see the Transaction Search API reference.

`Business Center`

Use the Business Center when API-based verification is unavailable, or when a timeout requires closer manual review, for example investigating a customer-reported duplicate charge.

IMPORTANT

Transaction search results might not be available immediately after a transaction is submitted, because data propagation takes a few seconds.

Sign in to the Business Center using your credentials.

Select

Transaction Search

>

Transaction Details

.

Search using the ID returned in the Cybersource response for the internal-failure and processor- timeout scenarios. For other scenarios, when there is no response from Cybersource, search using the merchant reference number, known as the merchant reference code
in the API.

Review the returned status, reason code, and timestamp to confirm the actual status.

Apply the result exactly as an API response would be applied. Record the status, and resubmit only if no record exists.

Searching by request ID returns the failed authorization for the
internal-failure scenario (Card Payments, Authorization,
Failed). — Searching by Request ID for a Failed Authorization

Searching by Request ID for a Failed Authorization and Its Automatic Authorization Reversal

Automated Payment Status Notifications

The payment events service uses a webhook to publish automated notifications for transaction statuses to your endpoint. This reduces reliance on the original synchronous response. This is a safety net that complements, and does not replace, the transaction status verifications described in this section.

Setup

Enroll in the payment events service and create a webhook subscription.

Provide a secure URL that is capable of receiving inbound POST notifications in real time.

Acknowledge receipt of the notification immediately and process the event data asynchronously.

Behavior

You submit a transaction and the synchronous response is delayed or lost.

The transaction completes on the Cybersource side, and Cybersource publishes the transaction status as a payment event.

Your webhook endpoint receives the notification, including the transaction ID, merchant reference code, and final transaction status.

Reconcile the event payload against your own records.

For more information about the webhooks service, see Webhooks Developer Guide
.

Layered Timeout Model

Cybersource follows a layered timeout model based on a monotonic timeout hierarchy, where each outer layer waits slightly longer than the layer it depends on. This ensures that when an inner component times out first, Cybersource receives a clear timeout response and can take appropriate action. If you reverse the timeout order, you might abandon a request that is still being processed. This creates the risk that you incorrectly treat a completed transaction as a failure and retry it. Cybersource determines timeout values based on observed production latency, processor performance characteristics, and operational behavior, and periodically adjusts them.

This table describes each timeout layer, typical wait times, and rationale for the each time setting.

Layer or Control	Typical Wait Time	Rationale
Merchant to `Cybersource`	60 seconds or more	Your timeout should be longer than the `Cybersource` processing timeout to ensure that `Cybersource` can return a definitive response before you abandon the request.
`Cybersource` internal service	5 to 10 seconds	The Payment Orchestrator uses these timeouts to call internal services such as Decision Manager and Token Management Service.
`Cybersource` to processor	30 seconds	`Cybersource` implements a fail-fast strategy for processor communications. `Cybersource` establishes timeout thresholds on a per-processor basis and evaluates them using processor response times, timeout rates, transaction volumes, and processor-specific operational characteristics. This approach aligns with processor guidance and enables `Cybersource` to quickly identify unreachable endpoints while minimizing unnecessary processing delays.

Retry and Duplicate Transaction Prevention

Payment timeouts and communication failures can create uncertainty about the status of a transaction. You might receive a timeout response even though the transaction was successfully processed by Cybersource, the processor, or the issuer. In these situations, immediately resubmitting the original request can result in duplicate authorizations, captures, or charges. Implementing retry mechanisms are therefore essential to balance transaction recovery with duplicate prevention. Before retrying a payment operation, determine the transaction status whenever possible and apply controlled retry practices to minimize the risk of duplicate processing.

To reduce this risk, use these methods:

Merchant reference codes to support authorization duplicate detection.

Transaction IDs to support timeout recovery, transaction lookups, authorization reversals, voids, and reconciliation.

Merchant Reference Code and Duplicate Transaction Detection

For authorization processing, Cybersource uses the

clientReferenceInformation.code

field that you provided to identify duplicate authorization requests. A duplicate authorization might be declined with reason code

104

.

For the API field description, see API Fields: Merchant Reference Code.

Enabling Block Duplicate Merchant Reference Numbers

Where the capability is supported for your configuration, you can enable your account to block duplicate merchant reference codes, also known as merchant reference numbers, rather than submitting a customer support request. This prevents duplicate authorization requests with the same merchant reference code submitted within 15 minutes of the original authorization.

Follow these configuration steps in the Business Center:

Log in to the Business Center.

Go to Template Management or Manage Merchants.

Locate the Block Duplicate Merchant Reference Number
setting.

Set

enableDuplicateMerchantReferenceNumberBlocking

to

true

.

Save and apply the configuration to the merchant profile.

You can also manage this capability programmatically through the Merchant Boarding API. For more information, see Merchant Boarding Developer Guide

Transaction ID for Timeout Recovery and Lifecycle Management

The transaction ID in the

clientReferenceInformation.transactionId

field restricts duplicate transaction processing, locates transactions after a timeout, supports authorization reversal and void requests, and assists with reconciliation and operational investigations. Unlike the merchant reference code, which is used primarily for authorization duplicate detection, the transaction ID remains associated with the transaction throughout its lifecycle and recovery processes.

The transaction ID applies to:

Authorization

Credit

Refund

Sale

For the API field description, see Cybersource API Fields reference: Transaction ID.

IMPORTANT

This capability is broadly available across most payment processors, except these processors:

AIBMS

Barclays

Cielo

Comercio Latino

Elavon

FDC Compass

FDC Nashville Global

Fiserv RapidConnect

HSBC

LloydsTSB Cardnet

Moneris

Lloyds-OmniPay

Rede

Worldpay VAP

Client Retry Backoff

When a request fails because of a temporary network or service issue, avoid immediately resubmitting the same request multiple times. Instead, space retry attempts with progressively longer delays between each attempt. This approach helps reduce pressure on downstream systems during periods of degraded performance, allows them time to recover, and helps prevent additional load that could worsen the disruption.

A typical retry backoff strategy includes:

Initial delay:
Wait a short period before the first retry attempt.

Increasing delays:
Increase the wait time between successive retries rather than retrying at a fixed interval.

Maximum delay:
Limit the maximum wait time between retries to avoid excessively long delays.

Randomized timing (jitter):
Introduce small random variations in retry timing to prevent large numbers of clients from retrying simultaneously.

Retry limits:
Cap the number of retry attempts or the overall retry duration before escalating to status validation, reconciliation, or operational review.

Use retry backoff only for transient failures where a subsequent attempt might succeed. When the status of a payment transaction is unknown, determine the final transaction status before submitting another payment request.

Reversal Strategy and Recovery Failure Handling

When the status of a payment transaction cannot be fully determined, the objective is to prevent duplicate charges while ensuring that the final transaction status is accurately resolved. This happens in two stages: first, choosing and executing the correct recovery action for the original transaction; second, recognizing that the recovery action itself is a network operation subject to the same failures, and handling that possibility the same way.

Select the Correct Recovery Method

Each recovery method applies to a specific point in the transaction lifecycle:

Authorization reversal
releases an approved authorization that has not yet been captured.

Void
cancels a transaction that exists but has not yet been submitted for settlement.

Refund
returns funds for a transaction that has already been captured or settled.

Consider the Transaction Lifecycle

Base your recovery choice on the current transaction lifecycle stage:

If the transaction is authorized but not captured, an authorization reversal is typically appropriate.

If the transaction is captured but not yet settled, a void might be supported.

If the transaction has been settled, a refund is required.

Confirm Transaction Status Before Reversing

Follow these steps before you reverse a transaction:

Determine whether the original transaction was processed.

Confirm the current transaction status.

Execute the appropriate recovery action.

Verify that the recovery action completed successfully.

`Cybersource` Automatic Authorization Reversal

For supported processor integrations, Cybersource might automatically submit an authorization reversal when the authorization status cannot be determined because of issuer, network, or processor communication failures.

IMPORTANT

When a timeout occurs, Cybersource designs recovery mechanisms to preserve Level II and Level III and currency-related transaction data, reducing the risk of interchange impacts caused by incomplete or lost transaction attributes. You must include Level II and Level III fields on the original authorization request so that this data is available in case of an automatic authorization reversal.

When the Status of an Authorization Reversal or Void Request Is Unknown

When the status of a recovery operation is unknown because of a timeout or communication failure, validate the transaction status using the original transaction ID and merchant reference code before taking additional action.

This lookup is read-only against Cybersource transaction records and does not require resubmission of the original payment request.

Authorization Reversal or Void

Cybersource permits only one successful authorization reversal or void per transaction, so a retried request produces one of these results:

If Cybersource accepts a retried authorization reversal or void request, it did not successfully process the original authorization or void.

If Cybersource rejects a retried authorization reversal or void request because the transaction has already been reversed or voided, it already successfully processed the original authorization reversal or void and correctly prevented the duplicate request.

In this scenario, no additional authorization reversal or void action is required.

Refund

Refund processing requires additional care to avoid supporting multiple refunds against the same captured transaction. Consider these points:

Unlike authorization reversals and voids, a successfully processed refund does not prevent a subsequent refund from being submitted.

Therefore, when the status of a refund request is unknown, validate the transaction status before submitting another refund.

Failure to perform a status check might result in an unintended duplicate refund.

If a duplicate refund is identified before settlement, you might be able to void the refund, subject to processor capabilities and settlement timing.

Reconciliation Sweep

The reconciliation sweep process acts as the final safety net for transactions that cannot be conclusively resolved through online recovery mechanisms. Reconcile Cybersource records against authorization, capture, reversal, refund, and settlement records using available correlation data such as merchant reference number, transaction ID, amount, currency, and available payment reference values.

Identify unresolved transactions, duplicate processing activity, and recovery operations in which the transaction status cannot be confirmed. Based on the transaction status and processor capabilities, perform one of these actions:

Initiate an automated late recovery action where permitted.

Route unresolved cases to an operational review queue for manual investigation and resolution.

Reconciliation provides the final confirmation of transaction status and serves as the last line of defense against unresolved duplicates, failed recovery actions, and communication failures.

Recommended Approach

Cybersource recommends pairing bounded, status-checked retries with an automated reconciliation sweep against settlement. This combination catches lost authorization s without requiring manual intervention. Retrying alone, without a reconciliation process behind it, leaves genuinely charged but unresolved cases unaddressed.

Preventing Queue Cascades and System Overload

Correct handling of individual transaction timeouts is only part of a resilient payment architecture. Under sustained latency or downstream service degradation, requests can accumulate across multiple layers.

`Cybersource` Controls

Cybersource protects its system stability with bounded queues and connection pools, circuit breakers that pause traffic to a struggling downstream dependency and resume it only after recovery, and load shedding that returns

HTTP 429

or

HTTP 503

with

Retry-After

guidance rather than accepting more work than it can handle. Each response indicates whether an operation is safe to retry, and Cybersource is set up to avoid a request to hold a processing resource beyond its allocated timeout.

Your Controls

Apply these controls on your side:

Implement bounded queues and connection pools for all payment traffic.

Use circuit breakers to protect your applications from Cybersource slowdowns.

Respect

Retry-After

and other retry guidance.

Apply exponential backoff with jitter to all retry operations.

Cap concurrent in-flight requests during degraded operating conditions.

Move recovery workflows to asynchronous processing queues rather than user-facing request threads.

Avoiding the Asymmetric Recovery Trap

Apply these safeguards:

Rate limit recovery operations.

Control retry traffic independently from new transaction traffic.

Bound background recovery queue throughput.

Prioritize correctness over speed in recovery processing.

IMPORTANT

The objective is not to retry failed transactions indefinitely. The objective is to maintain system stability while enabling safe recovery through controlled retries, reconciliation, and recovery workflows.

Exception Handling Recommendations

These tables provide detailed, transaction-type-specific guidance for handling exceptions, timeouts, and recovery scenarios during authorization, capture, authorization reversal or void, and credit or refund processing. They are operational reference material intended for engineering, support, and operations teams who are resolving live exceptions.

Authorizations
Scenario	Expected Behavior	Recommended Actions
The authorization request never reaches `Cybersource` because of a network, Domain Name System (DNS), or Transport Layer Security (TLS) failure.	No transaction record is created at `Cybersource`. No downstream authorization is submitted.	Confirm that the failure is client-side. Wait for connectivity. Perform a status lookup to confirm no record exists. Retry safely using the same transaction ID.
A `Cybersource` internal dependency fails (`Decision Manager`, `Token Management Service`, or payer authentication).	A hard decline is returned immediately. The transaction never reaches the processor, network, or issuer.	No status check is needed, because the transaction status is known. Verify the failed dependency, then resubmit with the same transaction ID.
A timeout occurs before the processor, network, or issuer responds.	`Cybersource` returns 151 or ETIMEOUT . The status is unknown. An automatic authorization reversal might be triggered.	Do not retry immediately. Wait for the `Cybersource` processing window. Perform a status lookup through the transaction search API. Reconcile if unresolved.
The authorization is approved by the issuer, but the response is lost.	The authorization exists and is valid on the card, but you never received confirmation. The status is already known and approved. No automatic authorization reversal condition applies here because automatic authorization reversal addresses the case where the status is unknown to `Cybersource`.	Do not resubmit. Perform a status lookup using the original transaction ID. Record the result after you confirm it.
The authorization is declined by the issuer, but the response is lost.	No charge exists. This is a safe end-state, but you are unaware.	Perform a status lookup to confirm the decline. Once confirmed, it is safe to request an alternate payment method.
You submitted a duplicate authorization before the original is resolved.	Two authorizations might exist on the card simultaneously.	Verify the duplicate transaction using a transaction ID or merchant reference code match. Reverse the duplicate transaction, never the original.
The automatic authorization reversal confirmation is lost.	The reversal might have succeeded or failed at the processor. The status is unknown to `Cybersource` and you.	Apply the recovery pattern described earlier in this topic: validate the transaction status on the reversal itself, then submit the transaction for reconciliation to determine its final status.

Captures
Scenario	Expected Behavior	Recommended Actions
The capture request never reaches `Cybersource`.	No capture record is created. The authorization remains open or uncaptured.	Confirm the client-side failure. Perform a status lookup. If no record exists, retry with the same transaction ID.
The capture times out downstream.	The settlement status is unknown. The authorization might or might not have been captured.	Do not retry immediately. Perform a status lookup. Confirm using the settlement report if still unresolved. Reconcile.
The capture succeeds, but confirmation is lost.	Funds are captured. Only the response is missing.	A status lookup confirms the captured state. Record the result. No retry or authorization reversal is needed.
The capture fails because the authorization expired or the amount mismatched, and the response is lost.	A real decline occurred, but you see only a timeout.	A status lookup reveals the true decline reason. Address the root cause before you resubmit.
The authorization is approved, but the capture timed out.	This is an ambiguous state. The authorization is valid, but the capture status is unconfirmed.	Treat as approved but unsettled. It might settle or reverse depending on the downstream status. Verify using the settlement report, then choose retry-capture or reverse-authorization.
The capture is retried without a status check.	There is a risk of duplicate capture, or double billing, on the customer's card.	Always perform a status check before you retry. If a duplicate occurs, refund or void only the later capture.
The capture succeeds, but the settlement report shows a later discrepancy.	The settlement record is different from the status you expected.	Route to the reconciliation sweep. Match on the merchant ID, amount, currency, and card reference.

Authorization Reversals and Voids
Scenario	Expected Behavior	Recommended Actions
The reversal or void request never reaches `Cybersource`.	No reversal record is created. The original authorization remains active and open.	Confirm that the failure is client-side. Perform a status lookup on the reversal. If no record exists, resubmit the reversal using the same transaction IDs.
The reversal times out downstream (processor, network, or issuer).	The status of the reversal is unknown. The original authorization might or might not have been released.	Do not retry immediately. Perform a status lookup through the transaction search API on the reversal itself. Reconcile, if unresolved.
The reversal succeeds, but confirmation is lost.	The authorization was successfully released. Only the response is missing.	A status lookup confirms the release. Record the result. No further action is needed.
The reversal fails because you already captured or settled the transaction, or the authorization expired, and the response is lost.	The reversal was rejected outright, a real decline of the reversal itself, but you see only a timeout.	A status lookup reveals the true rejection reason. If the transaction has since settled, use refund or credit instead of a reversal.
You retry the reversal without a status check.	There is a risk of a duplicate reversal attempt against the same authorization.	Always perform a status check before you retry.
An automatic authorization reversal is already in progress when you submitted a manual reversal.	Two reversal attempts, one automatic and one manual, might race against the same authorization.	Confirm the automatic authorization reversal status before you submit a manual reversal. Avoid duplicate reversal attempts on the same authorization.
You cannot confirm the reversal status after the recovery window.	This is a genuinely unresolved state, with a risk that the authorization remains held on the cardholder's account indefinitely.	Submit the transaction for reconciliation to determine its final status. If still unresolved, route to a manual operational review.

Refunds
Scenario	Expected Behavior	Recommended Actions
The refund request never reaches `Cybersource`.	No refund record is created. The settled transaction remains unrefunded.	Confirm that the failure is client-side. Perform a status lookup. If no record exists, retry the refund using the same transaction ID.
The refund times out downstream.	The refund status is unknown. It is unclear whether funds were returned to the cardholder.	Do not retry immediately. Perform a status lookup. Confirm using the settlement report if unresolved. Reconcile.
The refund succeeds, but confirmation is lost.	Funds were returned. Only the response is missing.	A status lookup confirms the refunded state. Record the result. No further refund is needed.
The refund fails because it was already refunded or the amount exceeds the captured amount, and the response is lost.	A real decline occurred, such as a duplicate or over-limit refund attempt, but you see only a timeout.	A status lookup reveals the true decline reason before you attempt any further recovery action.
The refund is retried without a status check.	There is a risk of a duplicate refund, with funds returned to the cardholder twice.	Always perform a status check before you retry, using the same refund reference.

Your Integration Responsibilities

This checklist defines your responsibilities for timeout handling. Use it as a verification checklist during implementation reviews, quality assurance sign-off, and go-live assessments:

Set the client read timeout to 60 seconds or more, allowing sufficient time for Cybersource to return a definitive response before you terminate the request.

Assign a unique merchant reference code in the

clientReferenceInformation.code

field to each transaction and use that reference consistently for transaction processing, status validation, recovery activities, and reconciliation to support end-to-end traceability.

On an unknown status, use the transaction search API and reporting or reconciliation data to determine the final transaction status before submitting another payment request. Avoid immediate resubmission and apply controlled retries with increased delays between attempts. Honor the

Retry-After

reason code and other retry guidance provided by Cybersource.

When a duplicate is identified, reverse the duplicate, not the original. Select void versus refund based on the current transaction lifecycle state. Confirm the charge exists before reversing.

Implement appropriate resiliency controls, such as bounded concurrency, request throttling, circuit breakers, or asynchronous recovery processing, to prevent recovery activities from affecting customer-facing transaction flows.

Treat reason codes

151

,

ETIMEOUT

, and

267

(deferred or pending timeout) as unknown, never as a definite failure or a definite success.

Best Practices

Always verify the transaction status through the Transaction Search API or the Business Center before you retry, reverse, or communicate the transaction status to the customer. If you identify duplicate transactions, apply an authorization reversal to the duplicate transaction.

Timeout events can occur because different participants in the payment ecosystem use different timeout values.

Do not resubmit a transaction after a timeout without first searching or assessing the potential cause.

Perform a transaction search to determine the actual status.

Based on the search results, reverse duplicate transactions if you identify multiple successful transactions, and take no action if the transaction was completed successfully and no duplicate exists.

Standard Payment Processing

This section shows you how to process various authorization, capture, credit, and sales transactions.

Account Verification with a Zero Amount Authorization

Account verification with zero amount authorization is a standard e-commerce practice where you send a zero amount transaction to verify a card is valid and whether the card is lost or stolen. You cannot capture a zero amount authorization.

Most card networks refer to card account validation as zero amount authorization (ZAA). These card networks have their own names for the service:

Discover Zero Dollar Authorization

Visa Account Verification

Processor-Specific Information

National Payment Gateway: AVS and CVN are supported.; Card types: Mastercard and Visa international cards. Not available for mada cards.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for Account Verification with Zero Amount Authorization

clientReferenceInformation.code
consumerAuthenticationInformation.acsReferenceNumber
consumerAuthenticationInformation.acsTransactionId
consumerAuthenticationInformation.authenticationDate
consumerAuthenticationInformation.cavv
consumerAuthenticationInformation.directoryServerTransactionId
consumerAuthenticationInformation.dsReferenceNumber
consumerAuthenticationInformation.paresStatus
consumerAuthenticationInformation.paSpecificationVersion
consumerAuthenticationInformation.xid
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount: Set the value to
0
.
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.authorizationOptions.cardVerificationIndicator: Set the value to
true
.
processingInformation.commerceIndicator: Set the value to one of these:
internet
mada
moto
moto_cc
spa
vbv
vbv_attempted
vbv_failure

REST Example: Account Verification with `3-D Secure`

Request

This example includes optional fields.

{
  "clientReferenceInformation" : {
    "code" : "TC_SPG_FE_VI-2"
  },
  "consumerAuthenticationInformation" : {
    "cavv" : "107b965bd3e20645afa84e63b91c03cc05050409",
    "dsReferenceNumber" : "dsReferenceNumber-3DS-mada123",
    "paresStatus" : "Y",
    "acsReferenceNumber" : "3DS_LOA_ACS_201_13579",
    "paSpecificationVersion" : "2",
    "xid" : "lEmYpm61EduaVZjPG1/HsgkAAQc=",
    "authenticationDate" : "20230413121212",
    "directoryServerTransactionId" : "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
    "acsTransactionId" : "f25084f0-5b16-4c0a-ae5d-b248083334b2"
  },
  "processingInformation" : {
    "commerceIndicator" : "vbv",
    "authorizationOptions" : {
      "cardVerificationIndicator": true
    },
    "industryDataType" : "auto_rental"
  },
  "orderInformation" : {
    "billTo" : {
      "firstName" : "Abdullah",
      "lastName" : "Muhammad",
      "phoneNumber" : "01-4844094",
      "address2" : "P.O.Box: 16335",
      "address1" : "Al Dariyah Dist.",
      "postalCode" : "22028",
      "email" : "[email protected]"
    },
    "amountDetails" : {
      "totalAmount" : "0",
      "currency" : "SAR"
    }
  },
  "merchantInformation" : {
    "transactionLocalDateTime" : "20991212121212",
    "categoryCode" : 4999,
    "merchantDescriptor" : {
      "country" : "SA",
      "address1" : "Kharj Road",
      "postalCode" : "12211",
      "locality" : "Riyadh",
      "name" : "Al Madina"
    }
  },
  "paymentInformation" : {
    "card" : {
      "expirationYear" : "2025",
       "number": "CARD_NUMBER",
      "securityCode" : "123",
      "expirationMonth" : "12",
      "type" : "001"
    }
  }
}

Response to a Successful Request

{
    "paymentInformation": {
        "bin": "411111",
        "issuer": "CONOTOXIA SP. Z O.O",
        "binCountry": "PL",
        "accountType": "Visa Classic",
        "cardBrand": "VISA",
        "cardType": "001"
    },
    "submitTimeUtc": "2025-08-29T05:46:12Z",
    "processorInformation": {
        "paymentAccountReferenceNumber": "ZEqueBNWFY660ddzGPTL9oz2WetSx",
        "approvalCode": "830SPG",
        "transactionId": "NE6VFfD5vsl4jj7",
        "merchantAdvice": {
            "code": "01",
            "codeRaw": "01"
        },
        "consumerAuthenticationResponse": {
            "code": "2",
            "codeRaw": "2"
        },
        "cardVerification": {
            "resultCodeRaw": "N",
            "resultCode": "N"
        },
        "settlementDate": "220915",
        "avs": {
            "code": "M",
            "codeRaw": "M"
        },
        "retrievalReferenceNumber": "524105500232",
        "responseCode": "00"
    },
    "_links": {
        "extension": {
            "method": "POST",
            "href": "/pts/v2/payments"
        },
        "void": {
            "method": "POST",
            "href": "/v2/payments/7564463720976144703812/reversals"
        },
        "captures": {
            "method": "POST",
            "href": "/v2/payments/7564463720976144703812/captures"
        },
        "self": {
            "method": "GET",
            "href": "/pts/v2/payments/7564463720976144703812"
        }
    },
    "paymentAccountInformation": {
        "card": {
            "type": "001"
        }
    },
    "clientReferenceInformation": {
        "code": "TC_SPG_FE_VI-1"
    },
    "consumerAuthenticationInformation": {
        "token": "7564463720976144703812",
        "eciRaw": "05A"
    },
    "id": "7564463720976144703812",
    "orderInformation": {
        "amountDetails": {
            "currency": "SAR"
        }
    },
    "reconciliationId": "7564463720976144703812",
    "status": "AUTHORIZED"
}

Pre-Authorization

This section provides the information you need in order to process a pre-authorization.

A pre-authorization enables you to authorize a payment when the final amount is unknown. The system places the funds on hold until you request a follow-up transaction. Pre-authorizations are typically used for lodging, auto rental, e-commerce, and restaurant transactions.

IMPORTANT

Payment Services Directive 2 (PSD2) rules in the European Union (EU) and European Economic Area (EEA) require the initial pre-authorization to use strong customer authentication for merchants or customers in PSD2-applicable countries.

When you have a specific merchant category code (MCC) assigned to your account, you are allowed to capture up to 20% more than the cumulatively authorized amount on Visa, Diners Club, Discover, and JCB cards. Contact your account manager to have your account enabled for this option.

The pre-authorization lasts for 14 calendar days unless you capture the payment, void it, or extend it. After 14 days, if you do not request a follow-up transaction, the system releases the hold and the funds become available to the cardholder again.

Processor-Specific Information

National Payment Gateway requires 3-D Secure authentication data in pre-authorization requests.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Pre-Authorization

Use these required fields for processing a pre-authorization.

clientReferenceInformation.code
consumerAuthenticationInformation.acsReferenceNumber
consumerAuthenticationInformation.acsTransactionId
consumerAuthenticationInformation.authenticationDate
consumerAuthenticationInformation.cavv
consumerAuthenticationInformation.directoryServerTransactionId
consumerAuthenticationInformation.dsReferenceNumber
consumerAuthenticationInformation.paSpecificationVersion: Set the value to
2
.
consumerAuthenticationInformation.paresStatus: Set the value to
Y
.
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.commerceIndicator: Set the value to one of these:
internet
mada
moto
moto_cc
spa
vbv
vbv_attempted
vbv_failure

REST Example: Processing a MOTO Pre-Authorization

Request for a Mastercard

{
  "clientReferenceInformation": {
    "code": "TC_SPG_FE_MC-3"
  },
  "processingInformation": {
    "commerceIndicator": "moto",
    "industryDataType": "auto_rental",
    "transactionTypeIndicator": "209"
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "(PO)Box 16335",
      "address1": "Al Dariyah Dist",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "20101.00",
      "currency": "SAR"
    }
  },
  "merchantInformation": {
    "categoryCode": 4999,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "Kharj Road",
      "postalCode": "12211",
      "locality": "Riyadh",
      "name": "Al Madina"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2026",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "002"
    }
  }
}

Response to a Successful Request for a Mastercard

{
  "paymentInformation": {
    "bin": "555555",
    "issuer": "CONOTOXIA SP. Z O.O",
    "binCountry": "PL",
    "accountType": "MASTERCARD",
    "cardBrand": "MASTERCARD",
    "cardType": "002"
  },
  "submitTimeUtc": "2025-08-29T05:46:12Z",
  "processorInformation": {
    "paymentAccountReferenceNumber": "ZEqueBNWFY660ddzGPTL9oz2WetSx",
    "approvalCode": "830SPG",
    "transactionId": "NE6VFfD5vsl4jj7",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "01"
    },
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "cardVerification": {
      "resultCodeRaw": "N",
      "resultCode": "N"
    },
    "settlementDate": "220915",
    "avs": {
      "code": "M",
      "codeRaw": "M"
    },
    "retrievalReferenceNumber": "524105500232",
    "responseCode": "00"
  },
  "_links": {
    "extension": {
      "method": "POST",
      "href": "/pts/v2/payments"
    },
    "void": {
      "method": "POST",
      "href": "/v2/payments/7564463720976144703812/reversals"
    },
    "captures": {
      "method": "POST",
      "href": "/v2/payments/7564463720976144703812/captures"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7564463720976144703812"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "002"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_FE_VI-1"
  },
  "consumerAuthenticationInformation": {
    "token": "7564463720976144703812",
    "eciRaw": "05A"
  },
  "id": "7564463720976144703812",
  "orderInformation": {
    "amountDetails": {
      "currency": "SAR",
      "authorizedAmount": "20100.00"
    }
  },
  "reconciliationId": "7564463720976144703812",
  "status": "AUTHORIZED"
}

Request a Visa Card

{
  "clientReferenceInformation": {
    "code": "TC_SPG_FE_VI-1"
  },
  "processingInformation": {
    "commerceIndicator": "moto",
    "capture": false,
    "industryDataType": "auto_rental"
  },
  "aggregatorInformation": {
    "subMerchant": {
      "id": "SubMerId123"
    }
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "(PO)Box 16335",
      "address1": "Al Dariyah Dist",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "20100.00",
      "currency": "SAR"
    }
  },
  "merchantInformation": {
    "categoryCode": 4999,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "Kharj Road",
      "postalCode": "12211",
      "locality": "Riyadh",
      "name": "Al Madina"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2026",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "001"
    }
  }
}

Response to a Successful Request for a Visa Card

{
  "paymentInformation": {
    "bin": "411111",
    "issuer": "CONOTOXIA SP. Z O.O",
    "binCountry": "PL",
    "accountType": "Visa Classic",
    "cardBrand": "VISA",
    "cardType": "001"
  },
  "submitTimeUtc": "2025-08-29T05:46:12Z",
  "processorInformation": {
    "paymentAccountReferenceNumber": "ZEqueBNWFY660ddzGPTL9oz2WetSx",
    "approvalCode": "830SPG",
    "transactionId": "NE6VFfD5vsl4jj7",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "01"
    },
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "cardVerification": {
      "resultCodeRaw": "N",
      "resultCode": "N"
    },
    "settlementDate": "220915",
    "avs": {
      "code": "M",
      "codeRaw": "M"
    },
    "retrievalReferenceNumber": "524105500232",
    "responseCode": "00"
  },
  "_links": {
    "extension": {
      "method": "POST",
      "href": "/pts/v2/payments"
    },
    "void": {
      "method": "POST",
      "href": "/v2/payments/7564463720976144703812/reversals"
    },
    "captures": {
      "method": "POST",
      "href": "/v2/payments/7564463720976144703812/captures"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7564463720976144703812"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "001"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_FE_VI-1"
  },
  "consumerAuthenticationInformation": {
    "token": "7564463720976144703812",
    "eciRaw": "05A"
  },
  "id": "7564463720976144703812",
  "orderInformation": {
    "amountDetails": {
      "currency": "SAR",
      "authorizedAmount": "20100.00"
    }
  },
  "reconciliationId": "7564463720976144703812",
  "status": "AUTHORIZED"
}

REST Example: Processing a Pre-Authorization with `3-D Secure` for a mada Card

Request

This example includes optional fields.

{
  "clientReferenceInformation": {
    "code": "SPG_REQ_01"
  },
  "consumerAuthenticationInformation": {
    "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=",
    "dsReferenceNumber": "dsReferenceNumber-3DS-mada123",
    "paresStatus": "Y",
    "acsReferenceNumber": "3DS_LOA_ACS_201_13579",
    "paSpecificationVersion": "2",
    "authenticationDate": "20230413121212",
    "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
    "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2"
  },
  "processingInformation": {
    "commerceIndicator": "mada"
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "P.O.Box: 16335",
      "address1": "Al Dariyah Dist.",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "3001",
      "currency": "SAR"
    },
    "invoiceDetails": {
      "purchaseOrderNumber": "PurchaseOrderNumber123"
    }
  },
  "aggregatorInformation": {
    "subMerchant": {
      "id": "001"
    }
  },
  "merchantInformation": {
    "categoryCode": 5411,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "API Address",
      "postalCode": "12987-7318",
      "locality": "Riyadh",
      "name": "API Merchant-Name1"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2031",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "060"
    }
  }
}

Response to a Successful Request

{
  "paymentInformation": {
    "bin": "968208",
    "issuer": "Al Bank Al Saudi Al Fransi",
    "binCountry": "SA",
    "cardBrand": "MADA",
    "cardType": "PREPAID"
  },
  "paymentAccountInformation": {
    "card": {
      "currency": "SAR",
      "type": "060"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "currency": "SAR",
      "authorizedAmount": "100.00"
    }
  },
  "processorInformation": {
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "334210123456",
    "cardVerification": {
      "resultCode": "M",
      "resultCodeRaw": "M"
    },
    "responseCode": "00",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "settlementDate": "220915"
  },
  "_links": {
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7020303222541234567890"
    },
    "refund": {
      "method": "POST",
      "href": "/pts/v2/payments/7020303222541234567890/refunds"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_BASIC-1"
  },
  "consumerAuthenticationInformation": {
    "token": "abc"
  },
  "reconciliationId": "7020303222541234567890",
  "status": "AUTHORIZED",
  "id": "7020303222541234567890",
  "submitTimeUtc": "2023-12-08T10:12:02Z"
}

Pre-Authorization Bundled with Payer Authentication Enroll Service

When a customer is authenticated without a challenge, the transaction can be authorized either in the same request or in a separate authorization request. Whether authorization occurs in the same request or a separate request, the values from the check enrollment response must be passed to the authorization request to qualify for a liability shift. This section provides information on how to process a pre-authorization combined with authentication of the cardholder that does not require additional authentication.

For more information about Payer Authentication, see the Payer Authentication Developer Guide
.

Processor-Specific Information

National Payment Gateway requires payer authentication data in customer-initiated transactions.

When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Pre-Authorization with Payer Authentication Enroll Service

clientReferenceInformation.code
consumerAuthenticationInformation.challengeCode
consumerAuthenticationInformation.deviceChannel
consumerAuthenticationInformation.overrideCountryCode
consumerAuthenticationInformation.referenceId
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.actionList

REST Example: Pre-Authorization with Payer Authentication Enroll Service

Request

This example includes optional fields.

{
  "clientReferenceInformation": {
    "code": "SPG_REQ_01"
  },
  "consumerAuthenticationInformation": {
    "referenceId": "CybsCruiseTester-da287c74",
    "overrideCountryCode": "SA",
    "deviceChannel": "Browser",
    "challengeCode": "04"
  },
  "processingInformation": {
    "actionList": [
      "CONSUMER_AUTHENTICATION"
    ],
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "P.O.Box: 16335",
      "address1": "Al Dariyah Dist.",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "3001",
      "currency": "SAR"
    },
    "invoiceDetails": {
      "purchaseOrderNumber": "PurchaseOrderNumber123"
    }
  },
  "aggregatorInformation": {
    "subMerchant": {
      "id": "001"
    }
  },
  "merchantInformation": {
    "categoryCode": 5411,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "API Address",
      "postalCode": "12987-7318",
      "locality": "Riyadh",
      "name": "API Merchant-Name1"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2031",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "060"
    }
  }
}

Response to a Successful Request

{
  "paymentInformation": {
    "bin": "968208",
    "issuer": "Al Bank Al Saudi Al Fransi",
    "binCountry": "SA",
    "cardBrand": "MADA",
    "cardType": "PREPAID"
  },
  "consumerAuthenticationInformation": {
    "challengeRequired": "N",
    "authenticationTransactionId": "rx39Q8ZN7aPE0bHxoSe1",
    "strongAuthentication": {
      "OutageExemptionIndicator": "0"
    },
    "acsUrl": "https://1merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
    "acsReferenceNumber": "Cardinal ACS",
    "stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
    "pareq": "eyJtZXNzYWdl-short-example",
    "directoryServerTransactionId": "b435dda8-a2b0-490e-ae39-1b7e01d1dc4e",
    "veresEnrolled": "Y",
    "threeDSServerTransactionId": "0cd884bb-c8ef-4dfc-97e1-a78b741c42b8",
    "acsOperatorID": "MerchantACS",
    "specificationVersion": "2.2.0",
    "acsTransactionId": "1231149d-299b-4a64-ba89-3ab10e538b48"
  },
  "embeddedActions": {
    "CONSUMER_AUTHENTICATION": {
      "reason": "CONSUMER_AUTHENTICATION_REQUIRED",
      "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.",
      "status": "PENDING_AUTHENTICATION"
    }
  },
  "submitTimeUtc": "2024-01-29T14:43:14Z",
  "id": "7065393947881234567890",
  "errorInformation": {
    "reason": "CONSUMER_AUTHENTICATION_REQUIRED",
    "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction."
  },
  "status": "PENDING_AUTHENTICATION",
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-159"
  }
}

Pre-Authorization Bundled with Payer Authentication Validate Service

When a customer is authenticated after a challenge, the transaction can be authorized in the same request or in a separate authorization request. Whether authorization is combined with validation or occurs in a separate request, the values from the validation response must be passed to the authorization request to qualify for a liability shift to the issuing bank. This section provides information on how to process that type of transaction.

For more information about Payer Authentication, see the Payer Authentication Developer Guide
.

Processor-Specific Information

National Payment Gateway requires payer authentication data in customer-initiated transactions.

When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Pre-Authorization with Payer Authentication Validate Service

clientReferenceInformation.code
consumerAuthenticationInformation.authenticationTransactionId
consumerAuthenticationInformation.challengeCode
consumerAuthenticationInformation.deviceChannel
consumerAuthenticationInformation.overrideCountryCode
consumerAuthenticationInformation.referenceId
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.actionList

REST Example: Pre-Authorization with Payer Authentication Validate Service

Request

This example includes optional fields.

{
  "clientReferenceInformation": {
    "code": "SPG_REQ_01"
  },
  "consumerAuthenticationInformation": {
    "referenceId": "CybsCruiseTester-d47f8d5c",
    "overrideCountryCode": "SA",
    "deviceChannel": "Browser",
    "authenticationTransactionId": "8HuyDYiugte0I1RxiRU1",
    "challengeCode": "04"
  },
  "processingInformation": {
    "actionList": [
      "VALIDATE_CONSUMER_AUTHENTICATION"
    ],
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "P.O.Box: 16335",
      "address1": "Al Dariyah Dist.",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "3001",
      "currency": "SAR"
    },
    "invoiceDetails": {
      "purchaseOrderNumber": "PurchaseOrderNumber123"
    }
  },
  "aggregatorInformation": {
    "subMerchant": {
      "id": "001"
    }
  },
  "merchantInformation": {
    "categoryCode": 5411,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "API Address",
      "postalCode": "12987-7318",
      "locality": "Riyadh",
      "name": "API Merchant-Name1"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2031",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "060"
    }
  }
}

Response to a Successful Request

{
  "paymentInformation": {
    "bin": "968208",
    "issuer": "AlBankAlSaudiAlFransi",
    "binCountry": "SA",
    "cardBrand": "MADA",
    "cardType": "PREPAID"
  },
  "consumerAuthenticationInformation": {
    "eciRaw": "05",
    "authenticationTransactionId": "fggOjcMXWKXFpxzAI0N1",
    "strongAuthentication": {
      "OutageExemptionIndicator": "0"
    },
    "effectiveAuthenticationType": "FR",
    "authorizationPayload": "eyJjb250YWluZXJWZXJ-short-example",
    "eci": "05",
    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "paresStatus": "Y",
    "acsReferenceNumber": "Cardinal ACS",
    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "directoryServerTransactionId": "e6a43429-7310-4ea1-b903-6a35941d9150",
    "veresEnrolled": "Y",
    "threeDSServerTransactionId": "827d03b1-e93b-4b81-9086-f0d257640e8b",
    "acsOperatorID": "MerchantACS",
    "ecommerceIndicator": "mada",
    "specificationVersion": "2.2.0",
    "acsTransactionId": "33c16320-5b5c-4569-9703-fb1a4c6f8858"
  },
  "embeddedActions": {
    "CONSUMER_AUTHENTICATION": {
      "status": "AUTHENTICATION_SUCCESSFUL"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "currency": "SAR",
      "type": "060"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "currency": "SAR",
      "authorizedAmount": "100.00"
    }
  },
  "processorInformation": {
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "333417123456",
    "cardVerification": {
      "resultCode": "M",
      "resultCodeRaw": "M"
    },
    "responseCode": "00",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "settlementDate": "220915"
  },
  "_links": {
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7013657600822661348823"
    },
    "refund": {
      "method": "POST",
      "href": "/pts/v2/payments/7013657600822661348823/refunds"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-54"
  },
  "consumerAuthenticationInformation": {
    "token": "abc"
  },
  "reconciliationId": "7013657600822661348823",
  "status": "COMPLETED",
  "id": "7013657600822661348823",
  "submitTimeUtc": "2023-11-30T17:36:00Z"
}

Pre-Authorization Extension

A pre-authorization extension is a follow-up to a pre-authorization that keeps the hold in place for another 14 days. This gives you a maximum hold of 28 days in total. You are allowed to send only one extension for each pre-authorization. For Mastercard and Visa cards, you can also change the held amount when you request the extension. For mada cards, you can only extend the hold time, not adjust the amount.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Pre-Authorization Extension

clientReferenceInformation.code
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
processingInformation.authorizationOptions.extendAuthIndicator: Set the value to
true
.
processingInformation.originalPaymentId: Set the value to the request ID of the pre-authorization.

REST Example: Pre-Authorization Extension with Zero Amount

Request

{
  "clientReferenceInformation" : {
    "code" : "Test"
  },
  "processingInformation" : {
    "authorizationOptions" : {
      "extendAuthIndicator" : "true"
    },
    "originalPaymentId" : "7429112613411234567890"
  },
  "orderInformation" : {
    "amountDetails" : {
      "totalAmount" : "0",
      "currency" : "SAR"
    }
  }
}

Response to a Successful Request

{
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "SAR",
      "authorizedAmount": "0.00"
    }
  },
  "processorInformation": {
    "paymentAccountReferenceNumber": "KUMsXUeemNQ4ylkiiOBhP8TfQUgFX",
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "424009035276",
    "responseCode": "00",
    "settlementDate": "220915"
  },
  "_links": {
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7247511738451234567890/captures"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7247511926041234567890"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-64"
  },
  "consumerAuthenticationInformation": {
    "token": "7247511926041234567890"
  },
  "reconciliationId": "7247511738451234567890",
  "status": "AUTHORIZED",
  "id": "7247511926041234567890",
  "submitTimeUtc": "2024-08-27T09:33:13Z"
}

Authorization Reversal

This section provides the information about how to process an authorization reversal.

For National Payment Gateway, the authorization reversal is sometimes referred to as a pre-authorization void. National Payment Gateway supports full and partial reversals.

Reversing an authorization releases the hold on the customer’s payment card funds that the issuing bank placed when processing the authorization.

For a debit card or prepaid card in which only a partial amount was approved, the amount of the reversal must be the amount that was authorized, not the amount that was requested.

All supported card types can process authorization reversals.

IMPORTANT

Wait 60 seconds before requesting a timeout authorization reversal. For guidance on timeout scenarios, see Transaction Timeout Guidance

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments/{id}
/reversals

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments/{id}
/reversals

The {id}
is the transaction ID returned in the authorization response.

Required Fields for Processing an Authorization Reversal

reversalInformation.amountDetails.currency
reversalInformation.amountDetails.totalAmount: The amount of the reversal must be the same as the authorization amount that was included in the authorization response message. Do not use the amount that was requested in the authorization request message.

REST Example: Processing an Authorization Reversal

Request

{ 
    "reversalInformation" : { 
        "amountDetails" : { 
            "totalAmount" : "100.00"
        } 
    } 
}

Response to a Successful Request

{
  "processorInformation": {
    "paymentAccountReferenceNumber": "QHD47E209drPQ9yJD9ddnaFZuSUXu",
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "424009035280",
    "responseCode": "00",
    "settlementDate": "220915"
  },
  "reversalAmountDetails": {
    "currency": "SAR",
    "reversedAmount": "100.00"
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-64"
  },
  "consumerAuthenticationInformation": {
    "token": "7247516416161234567890"
  },
  "reconciliationId": "7247516248131234567890",
  "status": "REVERSED",
  "id": "7247516416161234567890",
  "submitTimeUtc": "2024-08-27T09:40:42Z"
}

Sale

This section provides the information you need in order to process a sale transaction.

A sale combines an authorization and a capture into a single transaction.

Processor-Specific Information

National Payment Gateway requires payer authentication data in customer-initiated transactions.

When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Sale
with `3-D Secure`

clientReferenceInformation.code
consumerAuthenticationInformation.acsReferenceNumber: Required for 3-D Secure transactions.
consumerAuthenticationInformation.acsTransactionId: Required for 3-D Secure transactions.
consumerAuthenticationInformation.authenticationDate: Required for 3-D Secure transactions.
consumerAuthenticationInformation.cavv: Required for 3-D Secure transactions.
consumerAuthenticationInformation.directoryServerTransactionId: Required for 3-D Secure transactions.
consumerAuthenticationInformation.dsReferenceNumber: Required for 3-D Secure transactions.
consumerAuthenticationInformation.paresStatus: Required for 3-D Secure transactions. Set the value to
Y
.
consumerAuthenticationInformation.specificationVersion: Required for 3-D Secure transactions. Set the value to
2
.
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.capture: Set the value to
true
.
processingInformation.commerceIndicator: Set the value to one of these:
internet
moto
vbv
spa
mada

REST Example: Sale with `3-D Secure`

Request for a mada Card

This example includes optional fields.

{
    "clientReferenceInformation": {
        "code": "SPG_REQ_01"
    },
    "consumerAuthenticationInformation": {
        "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=",
        "dsReferenceNumber": "dsReferenceNumber-3DS-mada123",
        "paresStatus": "Y",
        "acsReferenceNumber": "3DS_LOA_ACS_201_13579",
        "paSpecificationVersion": "2",
        "authenticationDate": "20230413121212",
        "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2"
    },
    "processingInformation": {
        "commerceIndicator": "mada",
        "capture": true
    },
    "orderInformation": {
        "billTo": {
            "firstName": "Abdullah",
            "lastName": "Muhammad",
            "phoneNumber": "01-4844094",
            "address2": "P.O.Box: 16335",
            "address1": "Al Dariyah Dist.",
            "postalCode": "22028",
            "email": "[email protected]"
        },
        "amountDetails": {
            "totalAmount": "3001",
            "currency": "SAR"
        },
        "invoiceDetails": {
            "purchaseOrderNumber": "PurchaseOrderNumber123"
        }
    },
    "aggregatorInformation": {
        "subMerchant": {
            "id": "001"
        }
    },
    "travelInformation": {
        "transit": {
            "airline": {
                "ticketNumber": "PNR123"
            }
        }
    },
    "merchantInformation": {
        "categoryCode": 5411,
        "merchantDescriptor": {
            "country": "SA",
            "address1": "API Address",
            "postalCode": "12987-7318",
            "locality": "Riyadh",
            "name": "API Merchant-Name1"
        }
    },
    "paymentInformation": {
        "card": {
            "expirationYear": "2031",
            "number": "CARD_NUMBER",
            "securityCode": "123",
            "expirationMonth": "12",
            "type": "060"
        }
    }
}

Response to a Successful Request for a mada Card

{
    "paymentInformation": {
        "bin": "968208",
        "issuer": "Al Bank Al Saudi Al Fransi",
        "binCountry": "SA",
        "cardBrand": "MADA",
        "cardType": "PREPAID"
    },
    "paymentAccountInformation": {
        "card": {
            "currency": "SAR",
            "type": "060"
        }
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "SAR",
            "authorizedAmount": "100.00"
        }
    },
    "processorInformation": {
        "approvalCode": "830SPG",
        "retrievalReferenceNumber": "334210123456",
        "cardVerification": {
            "resultCode": "M",
            "resultCodeRaw": "M"
        },
        "responseCode": "00",
        "consumerAuthenticationResponse": {
            "code": "2",
            "codeRaw": "2"
        },
        "settlementDate": "220915"
    },
    "_links": {
        "self": {
            "method": "GET",
            "href": "/pts/v2/payments/7020303222541234567890"
        },
        "refund": {
            "method": "POST",
            "href": "/pts/v2/payments/7020303222541234567890/refunds"
        }
    },
    "clientReferenceInformation": {
        "code": "TC_SPG_BASIC-1"
    },
    "consumerAuthenticationInformation": {
        "token": "abc"
    },
    "reconciliationId": "7020303222541234567890",
    "status": "COMPLETED",
    "id": "7020303222541234567890",
    "submitTimeUtc": "2023-12-08T10:12:02Z"
}

Request for a Mastercard

This example includes optional fields.

{
  "clientReferenceInformation" : {
    "code" : "TC_SPG_FE_MC-3"
  },
  "consumerAuthenticationInformation" : {
    "dsReferenceNumber" : "dsReferenceNumber-3DS-vbv123",
    "paresStatus" : "Y",
    "acsReferenceNumber" : "3DS_LOA_ACS_201_13579",
    "authenticationDate" : "20230413121212",
    "ucafCollectionIndicator" : "2",
    "ucafAuthenticationData" : "EHuWW9PiBkWvqE5juRwDzAUFBAk=",
    "directoryServerTransactionId" : "f25084f05b164c0aae5db24808a95e4b",
    "specificationVersion" : "2",
    "acsTransactionId" : "f25084f0-5b16-4c0a-ae5d-b248083334b2"
  },
  "processingInformation" : {
    "commerceIndicator" : "spa",
    "capture" : true,
    "industryDataType" : "auto_rental",
    "transactionTypeIndicator" : "209"
  },
  "orderInformation" : {
    "billTo" : {
      "firstName" : "Abdullah",
      "lastName" : "Muhammad",
      "phoneNumber" : "01-4844094",
      "address2" : "(PO)Box 16335",
      "address1" : "Al Dariyah Dist",
      "postalCode" : "22028",
      "email" : "[email protected]"
    },
    "amountDetails" : {
      "totalAmount" : "20101.00",
      "currency" : "SAR"
    }
  },
  "merchantInformation" : {
    "categoryCode" : 4999,
    "merchantDescriptor" : {
      "country" : "SA",
      "address1" : "Kharj Road",
      "postalCode" : "12211",
      "locality" : "Riyadh",
      "name" : "Al Madina"
    }
  },
  "paymentInformation" : {
    "card" : {
      "expirationYear" : "2026",
       "number": "CARD_NUMBER",
      "securityCode" : "123",
      "expirationMonth" : "12",
      "type" : "002"
    }
  }
}

Response to a Successful Request for a Mastercard

{
    "paymentInformation": {
        "bin": "555555",
        "issuer": "CONOTOXIA SP. Z O.O",
        "binCountry": "PL",
        "accountType": "MASTERCARD Classic",
        "cardBrand": "MASTERCARD",
        "cardType": "002"
    },
    "submitTimeUtc": "2025-08-28T11:40:39Z",
    "processorInformation": {
        "paymentAccountReferenceNumber": "8atcUKA55teOnsvajmkfaY8Rosg2Z",
        "approvalCode": "830SPG",
        "transactionId": "WsPI4kVYXSlXPPK",
        "merchantAdvice": {
            "code": "01",
            "codeRaw": "01"
        },
        "consumerAuthenticationResponse": {
            "code": "2",
            "codeRaw": "2"
        },
        "cardVerification": {
            "resultCodeRaw": "N",
            "resultCode": "N"
        },
        "settlementDate": "220915",
        "avs": {
            "code": "M",
            "codeRaw": "M"
        },
        "retrievalReferenceNumber": "524011500230",
        "responseCode": "00"
    },
    "_links": {
        "self": {
            "method": "GET",
            "href": "/pts/v2/payments/7563812390036731704807/captures"
        },
        "refund": {
            "method": "POST",
            "href": "/pts/v2/payments/7563812390036731704807/refunds"
        },
        "void": {
            "method": "POST",
            "href": "/pts/v2/captures/7563812390036731704807/voids"
        }
    },
    "paymentAccountInformation": {
        "card": {
            "type": "002"
        }
    },
    "clientReferenceInformation": {
        "code": "TC_SPG_FE_VI-1"
    },
    "consumerAuthenticationInformation": {
        "token": "7563812390036731704807",
        "eciRaw": "05A"
    },
    "id": "7563812390036731704807",
    "orderInformation": {
        "amountDetails": {
            "currency": "SAR",
            "authorizedAmount": "20100.00",
            "totalAmount": "20100.00"
        }
    },
    "reconciliationId": "7563812390036731704807",
    "status": "PENDING",
    "embeddedActions": {
        "CAPTURE": {
            "status": "PENDING"
        }
    }
}

Request for a Visa Card

This example includes optional fields.

{
  "clientReferenceInformation" : {
    "code" : "TC_SPG_FE_VI-1"
  },
  "consumerAuthenticationInformation" : {
    "cavv" : "107b965bd3e20645afa84e63b91c03cc05050409",
    "dsReferenceNumber" : "dsReferenceNumber-3DS-vbv123",
    "paresStatus" : "Y",
    "acsReferenceNumber" : "3DS_LOA_ACS_201_13579",
    "xid" : "lEmYpm61EduaVZjPG1/HsgkAAQc=",
    "authenticationDate" : "20230413121212",
    "directoryServerTransactionId" : "f25084f05b164c0aae5db24808a95e4b",
    "specificationVersion" : "2",
    "acsTransactionId" : "f25084f0-5b16-4c0a-ae5d-b248083334b2"
  },
  "processingInformation" : {
    "commerceIndicator" : "vbv",
    "capture" : true,
    "industryDataType" : "auto_rental"
  },
  "aggregatorInformation" : {
    "subMerchant" : {
      "id" : "SubMerId123"
    }
  },
  "orderInformation" : {
    "billTo" : {
      "firstName" : "Abdullah",
      "lastName" : "Muhammad",
      "phoneNumber" : "01-4844094",
      "address2" : "(PO)Box 16335",
      "address1" : "Al Dariyah Dist",
      "postalCode" : "22028",
      "email" : "[email protected]"
    },
    "amountDetails" : {
      "totalAmount" : "20100.00",
      "currency" : "SAR"
    }
  },
  "merchantInformation" : {
    "transactionLocalDateTime" : "20991212121212",
    "categoryCode" : 4999,
    "merchantDescriptor" : {
      "country" : "SA",
      "address1" : "Kharj Road",
      "postalCode" : "12211",
      "locality" : "Riyadh",
      "name" : "Al Madina"
    }
  },
  "paymentInformation" : {
    "card" : {
      "expirationYear" : "2026",
       "number": "CARD_NUMBER",
      "securityCode" : "123",
      "expirationMonth" : "12",
      "type" : "001"
    }
  }
}

Response to a Successful Request for a Visa Card

{
    "paymentInformation": {
        "bin": "411111",
        "issuer": "CONOTOXIA SP. Z O.O",
        "binCountry": "PL",
        "accountType": "Visa Classic",
        "cardBrand": "VISA",
        "cardType": "001"
    },
    "submitTimeUtc": "2025-08-28T11:40:39Z",
    "processorInformation": {
        "paymentAccountReferenceNumber": "8atcUKA55teOnsvajmkfaY8Rosg2Z",
        "approvalCode": "830SPG",
        "transactionId": "WsPI4kVYXSlXPPK",
        "merchantAdvice": {
            "code": "01",
            "codeRaw": "01"
        },
        "consumerAuthenticationResponse": {
            "code": "2",
            "codeRaw": "2"
        },
        "cardVerification": {
            "resultCodeRaw": "N",
            "resultCode": "N"
        },
        "settlementDate": "220915",
        "avs": {
            "code": "M",
            "codeRaw": "M"
        },
        "retrievalReferenceNumber": "524011500230",
        "responseCode": "00"
    },
    "_links": {
        "self": {
            "method": "GET",
            "href": "/pts/v2/payments/7563812390036731704807/captures"
        },
        "refund": {
            "method": "POST",
            "href": "/pts/v2/payments/7563812390036731704807/refunds"
        },
        "void": {
            "method": "POST",
            "href": "/pts/v2/captures/7563812390036731704807/voids"
        }
    },
    "paymentAccountInformation": {
        "card": {
            "type": "001"
        }
    },
    "clientReferenceInformation": {
        "code": "TC_SPG_FE_VI-1"
    },
    "consumerAuthenticationInformation": {
        "token": "7563812390036731704807",
        "eciRaw": "05A"
    },
    "id": "7563812390036731704807",
    "orderInformation": {
        "amountDetails": {
            "currency": "SAR",
            "authorizedAmount": "20100.00",
            "totalAmount": "20100.00"
        }
    },
    "reconciliationId": "7563812390036731704807",
    "status": "PENDING",
    "embeddedActions": {
        "CAPTURE": {
            "status": "PENDING"
        }
    }
}

Response to a Timed Out Request

{
  "reason": "SERVER_TIMEOUT",
  "message": "Error - The request was received but there was a server timeout. This error does not include timeouts between the client and the server.",
  "status": "SERVER_ERROR",
  "id": "7020508046881234567890",
  "submitTimeUtc": "2027-06-06T15:20:39Z"
}

Sale Bundled with Payer Authentication Enroll Service

When a customer is authenticated without a challenge, the transaction can be authorized either in the same request or in a separate authorization request. Whether authorization occurs in the same request or a separate request, the values from the check enrollment response must be passed to the authorization request to qualify for a liability shift. This section provides information on how to process a transaction combined with authentication of the cardholder that does not require additional authentication.

For more information about Payer Authentication, see the Payer Authentication Developer Guide
.

Processor-Specific Information

National Payment Gateway requires payer authentication data in customer-initiated transactions.

When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Sale with Payer Authentication Enroll Service

clientReferenceInformation.code
consumerAuthenticationInformation.challengeCode
consumerAuthenticationInformation.deviceChannel
consumerAuthenticationInformation.overrideCountryCode
consumerAuthenticationInformation.referenceId
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.actionList
processingInformation.capture

REST Example: Sale with Payer Authentication Enroll Service

Request

This example includes optional fields.

{
  "clientReferenceInformation": {
    "code": "SPG_REQ_01"
  },
  "consumerAuthenticationInformation": {
    "referenceId": "CybsCruiseTester-da287c74",
    "overrideCountryCode": "SA",
    "deviceChannel": "Browser",
    "challengeCode": "04"
  },
  "processingInformation": {
    "actionList": [
      "CONSUMER_AUTHENTICATION"
    ],
    "capture": true
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "P.O.Box: 16335",
      "address1": "Al Dariyah Dist.",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "3001",
      "currency": "SAR"
    },
    "invoiceDetails": {
      "purchaseOrderNumber": "PurchaseOrderNumber123"
    }
  },
  "aggregatorInformation": {
    "subMerchant": {
      "id": "001"
    }
  },
  "merchantInformation": {
    "categoryCode": 5411,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "API Address",
      "postalCode": "12987-7318",
      "locality": "Riyadh",
      "name": "API Merchant-Name1"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2031",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "060"
    }
  }
}

Response to a Successful Request

{
  "paymentInformation": {
    "bin": "968208",
    "issuer": "Al Bank Al Saudi Al Fransi",
    "binCountry": "SA",
    "cardBrand": "MADA",
    "cardType": "PREPAID"
  },
  "consumerAuthenticationInformation": {
    "challengeRequired": "N",
    "authenticationTransactionId": "rx39Q8ZN7aPE0bHxoSe1",
    "strongAuthentication": {
      "OutageExemptionIndicator": "0"
    },
    "acsUrl": "https://1merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
    "acsReferenceNumber": "Cardinal ACS",
    "stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
    "pareq": "eyJtZXNzYWdl-short-example",
    "directoryServerTransactionId": "b435dda8-a2b0-490e-ae39-1b7e01d1dc4e",
    "veresEnrolled": "Y",
    "threeDSServerTransactionId": "0cd884bb-c8ef-4dfc-97e1-a78b741c42b8",
    "acsOperatorID": "MerchantACS",
    "specificationVersion": "2.2.0",
    "acsTransactionId": "1231149d-299b-4a64-ba89-3ab10e538b48"
  },
  "embeddedActions": {
    "CONSUMER_AUTHENTICATION": {
      "reason": "CONSUMER_AUTHENTICATION_REQUIRED",
      "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.",
      "status": "PENDING_AUTHENTICATION"
    }
  },
  "submitTimeUtc": "2024-01-29T14:43:14Z",
  "id": "7065393947881234567890",
  "errorInformation": {
    "reason": "CONSUMER_AUTHENTICATION_REQUIRED",
    "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction."
  },
  "status": "PENDING_AUTHENTICATION",
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-159"
  }
}

Sale Bundled with Payer Authentication Validate Service

When a customer is authenticated after a challenge, the transaction can be authorized in the same request or in a separate authorization request. Whether authorization is combined with validation or occurs in a separate request, the values from the validation response must be passed to the authorization request to qualify for a liability shift to the issuing bank. This section provides information on how to process that type of transaction.

For more information about Payer Authentication, see the Payer Authentication Developer Guide
.

Processor-Specific Information

National Payment Gateway requires payer authentication data in customer-initiated transactions.

When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments

Required Fields for a Sale with Payer Authentication Validate Service

clientReferenceInformation.code
consumerAuthenticationInformation.authenticationTransactionId
consumerAuthenticationInformation.challengeCode
consumerAuthenticationInformation.deviceChannel
consumerAuthenticationInformation.overrideCountryCode
consumerAuthenticationInformation.referenceId
merchantInformation.merchantDescriptor.locality
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
processingInformation.actionList
processingInformation.capture

REST Example: Sale with Payer Authentication Validate Service

Request

This example includes optional fields.

{
  "clientReferenceInformation": {
    "code": "SPG_REQ_01"
  },
  "consumerAuthenticationInformation": {
    "referenceId": "CybsCruiseTester-d47f8d5c",
    "overrideCountryCode": "SA",
    "deviceChannel": "Browser",
    "authenticationTransactionId": "8HuyDYiugte0I1RxiRU1",
    "challengeCode": "04"
  },
  "processingInformation": {
    "actionList": [
      "VALIDATE_CONSUMER_AUTHENTICATION"
    ],
    "capture": true
  },
  "orderInformation": {
    "billTo": {
      "firstName": "Abdullah",
      "lastName": "Muhammad",
      "phoneNumber": "01-4844094",
      "address2": "P.O.Box: 16335",
      "address1": "Al Dariyah Dist.",
      "postalCode": "22028",
      "email": "[email protected]"
    },
    "amountDetails": {
      "totalAmount": "3001",
      "currency": "SAR"
    },
    "invoiceDetails": {
      "purchaseOrderNumber": "PurchaseOrderNumber123"
    }
  },
  "aggregatorInformation": {
    "subMerchant": {
      "id": "001"
    }
  },
  "merchantInformation": {
    "categoryCode": 5411,
    "merchantDescriptor": {
      "country": "SA",
      "address1": "API Address",
      "postalCode": "12987-7318",
      "locality": "Riyadh",
      "name": "API Merchant-Name1"
    }
  },
  "paymentInformation": {
    "card": {
      "expirationYear": "2031",
      "number": "CARD_NUMBER",
      "securityCode": "123",
      "expirationMonth": "12",
      "type": "060"
    }
  }
}

Response to a Successful Request

{
  "paymentInformation": {
    "bin": "968208",
    "issuer": "AlBankAlSaudiAlFransi",
    "binCountry": "SA",
    "cardBrand": "MADA",
    "cardType": "PREPAID"
  },
  "consumerAuthenticationInformation": {
    "eciRaw": "05",
    "authenticationTransactionId": "fggOjcMXWKXFpxzAI0N1",
    "strongAuthentication": {
      "OutageExemptionIndicator": "0"
    },
    "effectiveAuthenticationType": "FR",
    "authorizationPayload": "eyJjb250YWluZXJWZXJ-short-example",
    "eci": "05",
    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "paresStatus": "Y",
    "acsReferenceNumber": "Cardinal ACS",
    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "directoryServerTransactionId": "e6a43429-7310-4ea1-b903-6a35941d9150",
    "veresEnrolled": "Y",
    "threeDSServerTransactionId": "827d03b1-e93b-4b81-9086-f0d257640e8b",
    "acsOperatorID": "MerchantACS",
    "ecommerceIndicator": "mada",
    "specificationVersion": "2.2.0",
    "acsTransactionId": "33c16320-5b5c-4569-9703-fb1a4c6f8858"
  },
  "embeddedActions": {
    "CONSUMER_AUTHENTICATION": {
      "status": "AUTHENTICATION_SUCCESSFUL"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "currency": "SAR",
      "type": "060"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "currency": "SAR",
      "authorizedAmount": "100.00"
    }
  },
  "processorInformation": {
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "333417123456",
    "cardVerification": {
      "resultCode": "M",
      "resultCodeRaw": "M"
    },
    "responseCode": "00",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "settlementDate": "220915"
  },
  "_links": {
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7013657600822661348823"
    },
    "refund": {
      "method": "POST",
      "href": "/pts/v2/payments/7013657600822661348823/refunds"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-54"
  },
  "consumerAuthenticationInformation": {
    "token": "abc"
  },
  "reconciliationId": "7013657600822661348823",
  "status": "COMPLETED",
  "id": "7013657600822661348823",
  "submitTimeUtc": "2023-11-30T17:36:00Z"
}

Capture

This section describes how to capture an authorized transaction.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments/{id}
/captures

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments/{id}
/captures

The {id}
is the transaction ID returned in the authorization response.

Required Fields for Capturing an Authorization

clientReferenceInformation.code: This field value maps from the original authorization, sale, or credit transaction.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

REST Example: Capturing an Authorization

Request

This example includes optional fields.

{
  "clientReferenceInformation": {
    "code": "SPG_REQ_02"
  },
  "processingInformation": {
    "captureOptions": {
      "captureSequenceNumber": 1,
      "totalCaptureCount": 5
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "SAR"
    }
  }
}

Response to a Successful Request

{
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "SAR"
    }
  },
  "processorInformation": {
    "paymentAccountReferenceNumber": "ZnUYuZUWBZbZVsNI0CEsKW75QleZ8",
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "424009035277",
    "responseCode": "00",
    "settlementDate": "220915"
  },
  "_links": {
    "self": {
      "method": "GET",
      "href": "/v2/payments/7247512943611234567890"
    },
    "refund": {
      "method": "POST",
      "href": "/pts/v2/payments/7247512943611234567890/refunds"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_SPG_REQUEST_PB-64"
  },
  "consumerAuthenticationInformation": {
    "token": "7247512943611234567890"
  },
  "reconciliationId": "7247511738451234567890",
  "status": "PENDING",
  "id": "7247512943611234567890",
  "submitTimeUtc": "2024-08-27T09:34:54Z"
}

Multiple Partial Capture

This section shows you how to process multiple partial captures for an authorization.

This feature enables you to request multiple partial captures for one authorization. A multiple partial capture allows you to incrementally settle authorizations over time. Ensure that the total amount of all the captures does not exceed the authorized amount.

After the final capture, Cybersource automatically releases any remaining authorized amount.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments/{id}
/captures

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments/{id}
/captures

The {id}
is the transaction ID returned in the authorization response.

Required Fields for Processing Multiple Partial Captures

clientReferenceInformation.code: Set to
clientReferenceInformation.code
value used in corresponding authorization request.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
processingInformation.captureOptions. captureSequenceNumber: For the final capture request, set this field and
processingInformation.captureOptions.totalCaptureCount
to the same value.
processingInformation.captureOptions. totalCaptureCount: When you do not know the total number of captures that you are going to request, set this field to at least one more than the
processingInformation.captureOptions. captureSequenceNumber
field until you reach the final capture. For the final capture request, set this field and
processingInformation.captureOptions. captureSequenceNumber
to the same value.

REST Example: Processing Multiple Partial Captures

Request

{
    "clientReferenceInformation": {
        "code": "SPG_REQ_02"
    },
      "processingInformation": {
    "captureOptions": {
      "captureSequenceNumber": 1,
      "totalCaptureCount": 5
    }
  },
    "orderInformation": {
        "amountDetails": {
            "totalAmount": "10",
            "currency": "SAR"
        }
    }
}

Response to a Successful Request

{
    "orderInformation": {
        "amountDetails": {
            "totalAmount": "100.00",
            "currency": "SAR"
        }
    },
    "processorInformation": {
        "paymentAccountReferenceNumber": "ZnUYuZUWBZbZVsNI0CEsKW75QleZ8",
        "approvalCode": "830SPG",
        "retrievalReferenceNumber": "424009035277",
        "responseCode": "00",
        "settlementDate": "220915"
    },
    "_links": {
        "self": {
            "method": "GET",
            "href": "/v2/payments/7247512943611234567890"
        },
        "refund": {
            "method": "POST",
            "href": "/pts/v2/payments/7247512943611234567890/refunds"
        }
    },
    "clientReferenceInformation": {
        "code": "TC_SPG_REQUEST_PB-64"
    },
    "consumerAuthenticationInformation": {
        "token": "7247512943611234567890"
    },
    "reconciliationId": "7247511738451234567890",
    "status": "PENDING",
    "id": "7247512943611234567890",
    "submitTimeUtc": "2024-08-27T09:34:54Z"
}

Follow-On
Refund

This section provides the information you need in order to process a follow-on

refund

, which is linked to a capture or sale. You must request a follow-on

refund

within 180 days of the authorization or sale.

When your account is enabled for credit authorizations, also known as purchase return authorizations, Cybersource authenticates the card and customer during a follow-on refund or stand-alone credit request. Every credit request is automatically authorized.

Credit authorization results are returned in these response fields:

processorInformation.approvalCode

processorInformation.networkTransactionId

processorInformation.responseCode

When you request a void for a refund or credit before settlement, the refund or credit is voided. If your account is enabled for credit authorizations, the credit authorization is also reversed.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments/{id}
/refunds

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments
{id}
/refunds

The

{id}

is the transaction ID returned in the capture or sale response.

Required Fields for Processing a
Refund

clientReferenceInformation.code
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

REST Example: Processing a Refund

Request

{
    "clientReferenceInformation" : {
        "code" : "SPG_REQ_012"
    },
    "orderInformation": {
        "amountDetails": {
            "totalAmount": "10.00",
            "currency": "SAR"
        }
    }
}

Response to a Successful Request

{
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "currency": "SAR"
    }
  },
  "processorInformation": {
    "responseCode": "00",
    "approvalCode": "830SPG",
    "retrievalReferenceNumber": "334210123456",
    "settlementDate": "220915"
  },
  "clientReferenceInformation": {
    "code": "SPG_REQ_012"
  },
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7020304334211234567890/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7020304334211234567890/refunds"
    }
  },
  "reconciliationId": "7020303222541234567890",
  "status": "COMPLETED",
  "id": "7020304334211234567890",
  "submitTimeUtc": "2025-06-06T15:20:39Z"
}

Void a Payment

This section describes how to void a payment that was submitted but not yet processed by the processor. A payment is also known as a sale, which is an authorization and capture in one API request. Include the payment ID in the void request endpoint to cancel the payment.

Endpoint

Production:

POST https://api.sa.cybersource.com/pts/v2/payments/{id}
/voids

Test:

POST https://apitest.sa.cybersource.com/pts/v2/payments/{id}
/voids

The

{id}

is the transaction ID returned in the sale response.

Required Fields for Voiding a Payment

clientReferenceInformation.code

REST Example: Voiding a Payment

Request

{
    "clientReferenceInformation": {
        "code": "123456789012"
    }
}

Response to a Successful Request

{
    "submitTimeUtc": "2025-03-11T16:39:30Z",
    "processorInformation": {
        "approvalCode": "OK1272",
        "responseCode": "000"
    },
    "consumerAuthenticationResponse": {
        "systemTraceAuditNumber": "500036"
    },
    "orderInformation": {
        "amountDetails": {
            "authorizedAmount": "110.00"
        }
    },
    "message": "Successful transaction.",
    "clientReferenceInformation": {
        "code": "123456789012"
    },
    "reconciliationId": "000000050000771",
    "id": "7417111702443232235535",
    "_links": {
        "self": {
            "method": "GET",
            "href": "/pts/v2/voids/7417111702443232235535"
        }
    },
    "status": "VOIDED"
}

Pre-Authorizations

A pre-authorization enables you to authorize a payment when the final amount is unknown. The system places the funds on hold until you request a follow-up transaction. Pre-authorizations are typically used for lodging, auto rental, e-commerce, and restaurant transactions.

IMPORTANT

Payment Services Directive 2 (PSD2) rules in the European Union (EU) and European Economic Area (EEA) require the initial pre-authorization to use strong customer authentication for merchants or customers in PSD2-applicable countries.

When you have a specific merchant category code (MCC) assigned to your account, you are allowed to capture up to 20% more than the cumulatively authorized amount on Visa, Diners Club, Discover, and JCB cards. Contact your account manager to have your account enabled for this option.

The pre-authorization lasts for 14 calendar days unless you capture the payment, void it, or extend it. After 14 days, if you do not request a follow-up transaction, the system releases the hold and the funds become available to the cardholder again.

Payments Developer Guide

Pilot Release

Recent Revisions to This Document

26.09.01

26.05.01

26.04.01

Introduction to Payments

National Payment Gateway Processor Overview

Financial Institutions and Payment Networks

Merchant Financial Institutions (Acquirers)

Customer Financial Institutions (Issuers)

Payment Networks

Payment Processors

Card Types

Co-Badged Cards

Co-Branded Cards

Credit Cards

Debit Cards

Transaction Types

Card-Not-Present Transactions

Payment Services

Authorization

Account Verification

Pre-Authorization

Pre-Authorization Extension

Authorization Workflow

Sale

Single-Message Processing

Authorization Reversal

Capture

Capture Workflow

Refund

Follow-on Refund

Refund and Credit Workflow

Payment Features

3-D Secure Authentication for National Payment Gateway

Bundled and Unbundled Authentications

Testing the Payment Services

Requirements for Testing

Test Card Numbers

Using Amounts to Simulate Errors

Transaction Timeout Guidance

Incorrect Timeout Handling Risks

Transaction Flow and Failure Taxonomy

End-to-End Authorization Flow

Timeout Scenarios and Recommended Actions

Scenario: Request Never Reached Cybersource

Scenario: Cybersource Internal Failure

Scenario: Request Received, Processor Response Took Too Long

Scenario: Approved, but Confirmation Never Received

Verifying a Transaction Status

Transaction Search API

Business Center

Figure:

Figure:

Figure:

Automated Payment Status Notifications

Layered Timeout Model

Retry and Duplicate Transaction Prevention

Merchant Reference Code and Duplicate Transaction Detection

Enabling Block Duplicate Merchant Reference Numbers

Transaction ID for Timeout Recovery and Lifecycle Management

Client Retry Backoff

Reversal Strategy and Recovery Failure Handling

Select the Correct Recovery Method

Consider the Transaction Lifecycle

Confirm Transaction Status Before Reversing

Cybersource Automatic Authorization Reversal

When the Status of an Authorization Reversal or Void Request Is Unknown

Reconciliation Sweep

Recommended Approach

Preventing Queue Cascades and System Overload

Cybersource Controls

Your Controls

Avoiding the Asymmetric Recovery Trap

Exception Handling Recommendations

Your Integration Responsibilities

Best Practices

Standard Payment Processing

Account Verification with a Zero Amount Authorization

`National Payment Gateway` Processor Overview

`3-D Secure` Authentication for `National Payment Gateway`

Scenario: Request Never Reached `Cybersource`

Scenario: `Cybersource` Internal Failure

`Business Center`

`Cybersource` Automatic Authorization Reversal

`Cybersource` Controls

REST Example: Account Verification with `3-D Secure`

REST Example: Processing a Pre-Authorization with `3-D Secure` for a mada Card

Required Fields for a Sale
with `3-D Secure`

REST Example: Sale with `3-D Secure`

Follow-On
Refund

Required Fields for Processing a
Refund