On This Page
FILTER BY TAG

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"
}
RELATED TO THIS PAGE