Preauthorizations

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.

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.

For a pre-authorization on all processors, except for China Union Pay and National Payment Gateway:

The authorization amount is greater than zero.
Submit the authorization for capture within 30 calendar days of its request.
When you do not capture the authorization, reverse it. In the US, Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed. In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations.
Chargeback protection is in effect for 30 days after the authorization.

For a pre-authorization:

The authorization amount is greater than zero.
Submit the authorization for capture within 30 calendar days of its request.
When you do not capture the authorization, reverse it. In the US, Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed. In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations.
Chargeback protection is in effect for 30 days after the authorization.

Supported Processors

AIBMS
American Express Direct
Banque de France et Tresor Public
Barclays
BNP Paribas France
Chase Paymentech Solutions
China UnionPay
Cielo
Comercio Latino
Credit Mutuel-CIC
Elavon
Elavon Americas
FDC Compass
FDC Nashville Global
FDI Australia
FDMS Nashville
Getnet
GPN
HBoS
HSBC
JCN Gateway
Lloyds-OmniPay
LloydsTSB Cardnet
Moneris
National Payment Gateway
OmniPay Direct
Prosa
Rede
RuPay
SIX
Streamline
TSYS Acquiring Solutions
Vero
Worldpay VAP

Supported Processors

Elavon Americas
FDC Nashville Global
Chase Paymentech Solutions
Streamline
Worldpay VAP

Processor-Specific Information

Visa Platform Connect: all supported card types can process pre-authorizations.

National Payment Gateway: 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. National Payment Gateway requires 3-D Secure authentication data in pre-authorization requests.

China UnionPay: For a pre-authorization:

The authorization amount is greater than zero.
Submit the authorization for capture within 30 calendar days of its request.
After 30 calendar days, the customer bank (issuer) releases the hold on the authorized amount. Send a new authorization request to claim the amount.
Send a new authorization request to claim the amount.

Use these services to manage pre-authorizations:

Capture service to process a pre-authorization completion. See Captures.
Authorization reversal service to reverse a pre-authorization. See Authorization Reversal.
Refund service to reverse a pre-authorization completion or sale. See Refunds.

JCN Gateway: These are the maximum amounts that can be processed:

The maximum amount that can be processed in an authorization is limited to 8 digits: 99,999,999.
The maximum amount that can be processed in a capture or credit is limited to 7 digits: 9,999,999.
The maximum amount that can be processed in a sale is limited to 7 digits: 9,999,999 (due to the capture limitation).

FDC Nashville Global Merchant Category Codes: when your business signs up with , assigns your account a merchant category code (MCC) based on your primary business type. sends this MCC to the card networks with every transaction you process. If you process a transaction that is unrelated to your usual goods or services, include the merchantInformation.categoryCode field and set it to the relevant MCC. and FDC Nashville Global do not validate the MCC you send. Using an incorrect MCC can result in increased decline rates, interchange downgrades, or fines. To verify the correct MCC, contact your account manager.

Endpoints

POST /pts/v2/payments

Preauthorization Examples

Standard Example

{  "clientReferenceInformation" : {    "code" : "Pre-Auth"  },  "orderInformation" : {    "billTo" : {      "country" : "US",      "lastName" : "Doe",      "address1" : "201 S. Division St.",      "postalCode" : "48104-2201",      "locality" : "Ann Arbor",      "administrativeArea" : "MI",      "firstName" : "Joan",      "phoneNumber" : "999999999",      "email" : "[email protected]"    },    "amountDetails" : {      "totalAmount" : "100.00",      "currency" : "usd"    }  },  "paymentInformation" : {    "card" : {      "expirationYear" : "2031",      "number" : "CARD_NUMBER",      "securityCode" : "123",      "expirationMonth" : "12",      "type" : "001"    }  },  "processingInformation": {    "authorizationOptions": {      "authIndicator": "0"    }  }}

{  "_links" : {    "authReversal" : {      "method" : "POST",      "href" : "/pts/v2/payments/7709386742016723603091/reversals"    },    "self" : {      "method" : "GET",      "href" : "/pts/v2/payments/7709386742016723603091"    },    "capture" : {      "method" : "POST",      "href" : "/pts/v2/payments/7709386742016723603091/captures"    }  },  "clientReferenceInformation" : {    "code" : "Pre-Auth"  },  "id" : "7709386742016723603091",  "orderInformation" : {    "amountDetails" : {      "authorizedAmount" : "100.00",      "currency" : "usd"    }  },  "paymentAccountInformation" : {    "card" : {      "type" : "001"    }  },  "paymentInformation" : {    "tokenizedCard" : {      "type" : "001"    },    "card" : {      "type" : "001"    }  },  "pointOfSaleInformation" : {    "terminalId" : "04980992"  },  "processorInformation" : {    "paymentAccountReferenceNumber" : "V0010013018036776997406844475",    "merchantNumber" : "6817027800",    "approvalCode" : "100",    "cardVerification" : {      "resultCodeRaw" : "3",      "resultCode" : "2"    },    "merchantAdvice" : {      "code" : "00",      "codeRaw" : "0"    },    "networkTransactionId" : "123456789012345",    "transactionId" : "123456789012345",    "responseCode" : "0",    "avs" : {      "code" : "U",      "codeRaw" : "00"    }  },  "status" : "AUTHORIZED",  "submitTimeUtc" : "2026-02-12T23:24:34Z"}

{  "clientReferenceInformation": {    "code": "TC50171_3"  },  "errorInformation": {    "reason": "PROCESSOR_ERROR",    "message": "Invalid account"  },  "id": "6583553837826789303954",  "paymentInsightsInformation": {    "responseInsights": {      "categoryCode": "01",      "category": "ISSUER_WILL_NEVER_APPROVE"    }  },  "pointOfSaleInformation": {    "amexCapnData": "1009S0600100"  },  "processorInformation": {    "systemTraceAuditNumber": "004544",    "merchantNumber": "1231231222",    "networkTransactionId": "431736869536459",    "transactionId": "431736869536459",    "responseCode": "111",    "avs": {      "code": "Y",      "codeRaw": "Y"    }  },  "status": "DECLINED"}

American Express Direct Example

{  "clientReferenceInformation" : {    "code" : "Pre-Auth"  },  "orderInformation" : {    "billTo" : {      "country" : "US",      "lastName" : "Doe",      "address1" : "201 S. Division St.",      "postalCode" : "48104-2201",      "locality" : "Ann Arbor",      "administrativeArea" : "MI",      "firstName" : "Joan",      "phoneNumber" : "999999999",      "email" : "[email protected]"    },    "amountDetails" : {      "totalAmount" : "100.00",      "currency" : "usd"    }  },  "paymentInformation" : {    "card" : {      "expirationYear" : "2031",      "number" : "CARD_NUMBER",      "securityCode" : "123",      "expirationMonth" : "12",      "type" : "003"    }  },  "processingInformation": {    "authorizationOptions": {      "authIndicator": "0"    }  }}

{  "_links" : {    "authReversal" : {      "method" : "POST",      "href" : "/pts/v2/payments/7709386742016723603091/reversals"    },    "self" : {      "method" : "GET",      "href" : "/pts/v2/payments/7709386742016723603091"    },    "capture" : {      "method" : "POST",      "href" : "/pts/v2/payments/7709386742016723603091/captures"    }  },  "clientReferenceInformation" : {    "code" : "Pre-Auth"  },  "id" : "7709386742016723603091",  "orderInformation" : {    "amountDetails" : {      "authorizedAmount" : "100.00",      "currency" : "usd"    }  },  "paymentAccountInformation" : {    "card" : {      "type" : "001"    }  },  "paymentInformation" : {    "tokenizedCard" : {      "type" : "003"    },    "card" : {      "type" : "003"    }  },  "pointOfSaleInformation" : {    "terminalId" : "04980992"  },  "processorInformation" : {    "paymentAccountReferenceNumber" : "V0010013018036776997406844475",    "merchantNumber" : "6817027800",    "approvalCode" : "100",    "cardVerification" : {      "resultCodeRaw" : "3",      "resultCode" : "2"    },    "merchantAdvice" : {      "code" : "00",      "codeRaw" : "0"    },    "networkTransactionId" : "123456789012345",    "transactionId" : "123456789012345",    "responseCode" : "0",    "avs" : {      "code" : "U",      "codeRaw" : "00"    }  },  "status" : "AUTHORIZED",  "submitTimeUtc" : "2026-02-12T23:24:34Z"}

China UnionPay Example

{    "orderInformation": {        "billTo": {            "country": "US",            "lastName": "Kim",            "address1": "201 S. Division St.",            "postalCode": "48104-2201",            "locality": "Ann Arbor",            "administrativeArea": "MI",            "firstName": "Kyong-Jin",            "email": "[email protected]"        },        "amountDetails": {            "totalAmount": "100.00",            "currency": "USD"        }    },    "paymentInformation": {        "card": {            "expirationYear": "2025",            "number": "62509470XXXXXXXX",            "expirationMonth": "12",            "type": "062"        }    },    "processingInformation": {        "commerceIndicator": "internet"    }}

{  "_links" : {    "authReversal" : {      "method" : "POST",      "href" : "/pts/v2/payments/6461731521426399003473/reversals"    },    "self" : {      "method" : "GET",      "href" : "/pts/v2/payments/6461731521426399003473"    },    "capture" : {      "method" : "POST",      "href" : "/pts/v2/payments/6461731521426399003473/captures"    }  },  "clientReferenceInformation" : {    "code" : "1646173152047"  },  "id" : "6461731521426399003473",  "orderInformation" : {    "amountDetails" : {      "authorizedAmount" : "100.00",      "currency" : "CNY"    }  },  "paymentAccountInformation" : {    "card" : {      "type" : "062"    }  },  "paymentInformation" : {    "tokenizedCard" : {      "type" : "062"    },    "card" : {      "type" : "062"    }  },  "paymentInsightsInformation" : {    "responseInsights" : {      "categoryCode" : "01"    }  },  "processorInformation" : {    "systemTraceAuditNumber" : "862481",    "approvalCode" : "831000",    "merchantAdvice" : {      "code" : "01",      "codeRaw" : "M001"    },    "responseDetails" : "ABC",    "networkTransactionId" : "016153570198200",    "consumerAuthenticationResponse" : {      "code" : "2",      "codeRaw" : "2"    },    "transactionId" : "016153570198200",    "responseCode" : "00",    "avs" : {      "code" : "Y",      "codeRaw" : "Y"    }  },  "reconciliationId" : "6461731521426399003473",  "status" : "AUTHORIZED",  "submitTimeUtc" : "2022-03-01T22:19:12Z"}

National Payment Gateway MOTO Example

{  "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"    }  }}

{  "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"}

{  "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"    }  }}

{  "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"}

National Payment Gateway 3-D Secure Example 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"  },  "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"    }  }}

{  "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"}

Required Fields

Use these required fields for processing a pre-authorization.

Default Required Fields

Field	Description
`orderInformation.amountDetails.currency`	For RuPay HDFC, set the value to `INR`.
`orderInformation.amountDetails.totalAmount`	—
`orderInformation.billTo.address1`	—
`orderInformation.billTo.administrativeArea`	—
`orderInformation.billTo.country`	—
`orderInformation.billTo.email`	—
`orderInformation.billTo.firstName`	—
`orderInformation.billTo.lastName`	—
`orderInformation.billTo.locality`	—
`orderInformation.billTo.postalCode`	—
`paymentInformation.card.expirationMonth`	—
`paymentInformation.card.expirationYear`	—
`paymentInformation.card.number`	—
`processingInformation.authorizationOptions.authIndicator`	Set the value to `0`.

Processor-Specific Required Fields

China UnionPay

Field	Description
`consumerAuthenticationInformation.cavv`	Required for 3-D Secure transactions.
`paymentInformation.card.type`	—
`processingInformation.commerceIndicator`	Set the value to `internet`.

National Payment Gateway

Field	Description
`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`.

Country-Specific Required Fields

Use these country-specific required fields to process a pre-authorization.

Argentina

Field	Description
`merchantInformation.taxId`	Required for Mastercard transactions.
`merchantInformation.transactionLocalDateTime`	Required in Argentina when the time zone is not included in your account. Otherwise, this field is optional.

Brazil

Field	Description
`paymentInformation.card.sourceAccountType`	Required for combo card transactions.
`paymentInformation.card.sourceAccountTypeDetails`	Required for combo card line-of-credit and prepaid-card transactions.

Chile and Paraguay

Field	Description
`merchantInformation.taxId`	Required for Mastercard transactions.

Egypt

Field	Description
`paymentInformation.card.cardType`	Required for Meeza transactions. Set the value to `067`.
`merchantInformation.merchantDescriptor.country`	Required for Meeza transactions. Set the value to `EG`.

Saudi Arabia

Field	Description
`processingInformation.authorizationOptions.transactionMode`	Required only for merchants in Saudi Arabia.

Taiwan

Field	Description
`paymentInformation.card.hashedNumber`	Required only for merchants in Taiwan.

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.

Supported Processor

National Payment Gateway

Example

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"    }  }}

{  "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"  }}

National Payment Gateway Required Fields

These fields are required when processing a pre-authorization bundled with the Payer Authentication Enroll service on National Payment Gateway:

Field	Description
`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`	—

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.

Supported Processor

National Payment Gateway

Example

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"    }  }}

{  "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"  },  "reconciliationId": "7013657600822661348823",  "status": "COMPLETED",  "id": "7013657600822661348823",  "submitTimeUtc": "2023-11-30T17:36:00Z"}

National Payment Gateway Required Fields

These fields are required when processing a pre-authorization bundled with the Payer Authentication Validate service on National Payment Gateway:

Field	Description
`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`	—

Was this page helpful?

Last published: September 29, 2026