On This Page
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/paymentsTest:
POST
https://apitest.sa.cybersource.com
/pts/v2/paymentsRequired 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 to2.
- consumerAuthenticationInformation.paresStatus
- Set the value toY.
- 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
3-D Secure
for a mada CardRequest
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" }