Standard Payment Processing
This section shows you how to process various authorization, capture, credit, and sales
transactions.
Basic Authorizations
This section provides the information you need in order to process a basic
authorization.
Supported Card Types
All supported card types can process basic authorizations. For a list of all
supported card types, see Payment Processors.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsAuthorizations with Line Items
This section shows you how to process an authorization with line items.
The main difference between a basic authorization and an authorization that includes
line items is that the
orderInformation.amountDetails.totalAmount
field, which is
included in a basic authorization, is substituted with one or more line items that
are included in a
.lineItem[]
arrayFields Specific to this Use Case
These
fields
are required for each line item that you use:- orderInformation.lineItems[].unitPrice
- orderInformation.lineItems[].quantity
- orderInformation.lineItems[].productCode
- orderInformation.lineItems[].productSku
- Optional whenitem_#_productCodeis set todefault,shipping_only,handling_only, orshipping_and_handling
- orderInformation.lineItems[].productName
- Optional whenitem_#_productCodeis set todefault,shipping_only,handling_only, orshipping_and_handling
At a minimum, you must include the
orderInformation.lineItems[].unitPrice
field in order to include a line item in an
authorization. When this field is the only field included in the authorization, the
system sets:- orderInformation.lineItems[].productCode:default
- orderInformation.lineItems[].quantity:1
For example, these three line items are valid.
"orderInformation": { "lineItems": [ { "unitPrice": "10.00" }, { "unitPrice": "5.99", "quantity": "3", "productCode": "shipping_only" }, { "unitPrice": "29.99", "quantity": "3", "productCode": "electronic_good", "productSku": "12384569", "productName": "receiver" } ] }
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsAuthorizations with Payment Network Tokens
This section shows you how to successfully process an authorization with payment network
tokens.
IMPORTANT
Due to mandates from the Reserve Bank of India, Indian merchants cannot
store personal account numbers (PAN). Use network tokens instead. For more information
on network tokens, see Network Tokenization in
the .
Token Management Service
Developer GuideEndpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsAuthorizations with a Card Verification Number
This section shows you how to process an authorization with a Card Verification Number
(CVN).
CVN Results
The response includes a raw response code and a mapped response code:
- The raw response code is the value returned by the processor. This value is returned in theprocessorInformation.cardVerification.resultCodeRawfield. Use this value only for debugging purposes; do not use it to determine the card verification response.
- The mapped response code is the pre-defined value that corresponds to the raw response code. This value is returned in theprocessorInformation.cardVerification.resultCodefield.
Even when the CVN does not match the expected value, the issuing bank might still authorize the transaction. You will receive a CVN decline, but you can still capture the transaction because it has been authorized by the bank. However, you must review the order to ensure that it is legitimate.
Settling authorizations that fail the CVN check might have an impact on the fees charged by your bank. Contact your bank for details about how card verification management might affect your discount rate.
When a CVN decline is received for the authorization in a sale request, the capture request is not processed unless you set the
processingInformation.authorizationOptions.ignoreCvResult
field to true
.- CVN Results for American Express
- A value of1in theprocessorInformation.cardVerification.resultCodefield indicates that your account is not configured to use card verification. Contact customer support to have your account enabled for this feature.
- CVN Results for Discover
- When the CVN does not match, Discover refuses the card and the request is declined. The reply message does not include theprocessorInformation.cardVerification.resultCodefield, which indicates that the CVN failed.
- CVN Results for Visa and Mastercard
- A CVN code ofDorNcauses the request to be declined with a reason code value of230. You can still capture the transaction, but you must review the order to ensure that it is legitimate.Cybersource, not the issuer, assigns the CVN decline to the authorization. You can capture any authorization that has a valid authorization code from the issuer, even when the request receives a CVN decline.When the issuer does not authorize the transaction and the CVN does not match, the request is declined because the card is refused. You cannot capture the transaction.
Fields Specific to this Use Case
Include this field with a standard authorization request when processing an
authorization with a CVN:
- paymentInformation.card.securityCode
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsAuthorizations with Strong Customer Authentication Exemption
This section shows you how to process an authorization with a strong customer authentication
(SCA) exemption.
You can use SCA exemptions to streamline the payment process. SCA exemptions are part of the
European second Payment Services Directive (PSD2) and allow certain types of low-risk
transactions to bypass additional authentication steps while still remaining compliant with
PSD2. You can choose which exemption can be applied to a transaction, but the card-issuing
bank actually grants an SCA exemption during card authentication.
You can process an authorization with two types of SCA exemptions:
- Exemption on Authorization: Send an authorization without payer authentication and request an SCA exemption on the authorization. If it is not approved, you may be required to request further authentication upon retry.
- Exemption on Authentication: Request an SCA exemption during payer authentication and if successful, send an authorization including the SCA exemption details.
Depending on your processor, use one of these exemption fields:
IMPORTANT
If you send more than one SCA exemption field with a single
authentication, the transaction is denied.
- Authentication Outage: Payer authentication is not available for this transaction due to a system outage.
- B2B Corporate Card: Payment cards specifically for business-to-business transactions are exempt.
- Delegated Authentication: Payer authentication was performed outside of the authorization workflow.
- Follow-On Installment Payment: Installment payments of a fixed amount are exempt after the first transaction.
- Follow-On Recurring Payment: Recurring payments of a fixed amount are exempt after the first transaction.
- Low Risk: The average fraud levels associated with this transaction are considered low.
- Low Value: The transaction value does not warrant SCA.
- Merchant Initiated Transactions: As follow-on transactions, merchant-initiated transactions are exempt.
- Stored Credential Transaction: Credentials are authenticated before storing, so stored credential transactions are exempt.
- Trusted Merchant: Merchants registered as trusted beneficiaries.
Exemption Fields Specific to the Strong Customer Authentication Use Case
Use one of these fields to request an SCA exemption:
Exemption Type | Field | Value |
---|---|---|
Authentication Outage | consumerAuthenticationInformation. strongAuthentication.
authenticationOutageExemptionIndicator | 1 |
B2B Corporate Card Transaction | consumerAuthenticationInformation. strongAuthentication.
secureCorporatePaymentIndicator | 1 |
Delegated Authentication | consumerAuthenticationInformation. strongAuthentication.
delegatedAuthenticationExemptionIndicator | 1 |
Low-Risk Transaction | consumerAuthenticationInformation. strongAuthentication.
riskAnalysisExemptionIndicator | 1 |
Low-Value Transaction | consumerAuthenticationInformation. strongAuthentication.
lowValueExemptionIndicator | 1 |
Trusted Merchant Transaction | consumerAuthenticationInformation. strongAuthentication.
trustedMerchantExemptionIndicator | 1 |
Country-Specific Requirements
These fields are specific to certain countries and regions.
Argentina
- merchantInformation.taxId
- Required for Mastercard transactions.
- merchantInformation.transactionLocalDateTime
- Required when the time zone is not included in your account. Otherwise, this field is optional.
Brazil
- paymentInformation.card.sourceAccountType
- Required for combo card transactions.
- paymentInformation.card.sourceAccountTypeDetails
- Required for combo card line-of-credit and prepaid-card transactions.
Chile
- merchantInformation.taxId
- Required for Mastercard transactions.
Paraguay
- merchantInformation.taxId
- Required for Mastercard transactions.
Saudi Arabia
- processingInformation.authorizationOptions.transactionMode
Taiwan
- paymentInformation.card.hashedNumber
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsZero Amount Authorizations
Zero Amount Authorizations
Authorizing
a payment for
a zero amount
shows whether a payment card account is valid and whether the card is lost or stolen.
You cannot capture a zero amount authorization
.This section provides the information that you need in order to process
a zero amount authorization
. Processor-Specific Information
- Visa Platform Connect
- AVS and CVN are supported.
- Supported for Internet, MOTO, and card-present transactions. Do not try to perform a zero amount authorization for a recurring payment, installment payment, or payer authorization transaction.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsPre-Authorizations
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. It is typically used for lodging, auto rental, e-commerce, and restaurant
transactions.
For a pre-authorization:
- The authorization amount must be greater than zero.
- The authorization must be submitted for capture within 30 calendar days of its request.
- When you do not capture the authorization, you must reverse it.In the U.S., 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 Card Types
All supported card types can process basic authorizations. For a list of all
supported card types, see Payment Processors.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsIncremental Authorizations
This section shows you how to process an incremental authorization.
Incremental authorizations allow merchants to add additional products and services to an
existing authorization. This section will show you how to append an original
authorization to include additional transactions.
The supported card types for incremental authorizations are Mastercard and Visa.
The incremental authorization service has these limitations:
- Maximum of 100 incremental authorizations per transaction, in addition to the initial authorization.
- Interchange optimization is not supported.
- Split shipments are not supported.
Supported Card Types
These card types support incremental authorizations:
- Mastercard
- Visa
Endpoint
Production:
PATCH
https://api.cybersource.com
/pts/v2/payments/{id}
Test:
PATCH
https://apitest.cybersource.com
/pts/v2/payments/{id}
The is the transaction ID returned in the
original authorization response.
{id}
Final Authorization Indicator
The purpose of this feature is to ensure that unused funds are reversed, so that
customer’s funds are available again when an order is not fulfilled.
For an authorization with an amount greater than zero, indicate whether the authorization
is a final authorization, a pre-authorization, or an undefined authorization.
You can set a default authorization type in your account. To set the default
authorization type in your account, contact customer support.
Chargeback protection is in effect for seven days after the authorization.
Supported Services
- Authorization
- Incremental authorization
Supported Card Types
- Co-badged Mastercard and mada. You must identify the card type as Mastercard. Supported only onVisa Platform Connect.
- Maestro (International)
- Maestro (UK Domestic)
- Mastercard
Authorization Reversals
This section provides the information you need in order to process an authorization reversal.
Reversing an authorization releases the hold on the customer’s payment card funds that the
issuing bank placed when processing the authorization.
Supported Card Types
All supported card types can process reversals.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/reversalsTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/reversalsThe is the transaction ID returned in the
authorization response.
{id}
Timeout Authorization Reversals
When you do not receive a response message after sending an authorization request, this
feature enables you to reverse the authorization that you requested.
IMPORTANT
Wait 60 seconds before requesting a timeout authorization
reversal.
Include the
clientReferenceInformation.transactionId
field in the original request for an
authorization. The value of the merchant transaction ID must be unique for 180 days.When the original transaction fails, the response message for the reversal request
includes these fields:
- reversalAmountDetails.originalTransactionAmount
- processorInformation.responseCode
Requirements
Unless your processor supports authorization reversal after void (ARAV), timeout
authorization reversals are supported only for authorizations that have not been
captured and settled.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/reversalsTest:
POST
https://apitest.cybersource.com
/pts/v2/reversalsSales
This section provides the information you need in order to process a sale
transactions.
A sale combines an authorization and a capture into a single transaction.
Supported Card Types
All supported card types can process sales.
.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsCaptures
This section provides the information you need in order to capture an authorized
transaction.
Supported Card Types
All supported card types can process captures.
.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe
{id}
is the transaction
ID returned in the authorization response.Multiple Partial Captures
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.
Fields Specific to This Use Case
These API request fields and values are specific to this use case:
Prerequisite
Contact customer support to have your account enabled for
this feature.
Limitations
Your account can be enabled for multiple partial captures or split shipments; it cannot be enabled for both features.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe
{id}
is the transaction
ID returned in the authorization response.Forced Captures
This feature allows merchants to process authorizations obtained through an organization
other than
Cybersource
. For example, a merchant might call their
processor to request a manual authorization, at which point they can request a forced
capture of the authorization.A manual authorization cannot be captured for more than the original authorization
amount, and the authorization expires after seven days.
Supported Acquirers
- Banco Safra
- Bank Sinarmas (Omise Ltd.)
- BC Card Co., Ltd.
- Citibank Malaysia
- CTBC Bank Ltd.
- Sumitomo Mitsui Card Co.
- Vietnam Technological and Commercial Joint-Stock Bank
Supported Services
- Authorization
Refunds
Refunds
This section provides the information you need in order to process a
refund
, which is linked to a capture or
sale.
You must request a
refund
within 180 days of the authorization.When your account is enabled for credit authorizations, also known as
purchase return authorizations,
Cybersource
authenticates the card and
customer during a refund or
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 the credit and the credit is voided. If your account is enabled
for credit authorizations, the credit authorization is also reversed.
Supported Card Types
All supported card types can process
refunds
. For a list of all supported card types, see Payment Processors. Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/refundsTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/refundsThe is the transaction ID
returned in the capture or sale response.
{id}
Credits
Credits
This section shows you how to process a credit, which is not linked to a capture or sale.
There is no time limit
for requesting a credit.
When your account is enabled for credit authorizations, also known as
purchase return authorizations,
Cybersource
authenticates the card and
customer during a refund or
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 the credit and the credit is voided. If your account is enabled
for credit authorizations, the credit authorization is also reversed.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/credits/Test:
POST
https://apitest.cybersource.com
/pts/v2/credits/Voids
This section describes how to void a capture or credit that was submitted but not yet
processed by the processor.
Endpoint
Void a Capture
Production:
POST
https://api.cybersource.com
/pts/v2/captures/{id}
/voidsTest:
POST
https://apitest.cybersource.com
/pts/v2/captures/{id}
/voidsVoid a Credit
Production:
POST
https://api.cybersource.com
/pts/v2/credits/{id}
/voidsTest:
POST
https://apitest.cybersource.com
/pts/v2/credits/{id}
/voidsThe is the transaction ID returned during the
request to void.
{id}
Timeout Voids for a Capture, Sale, Refund, or Credit
Refund
, or Credit
When you do not receive a response message after requesting a capture, sale, or credit,
this feature enables you to void the transaction that you requested.
Include the
clientReferenceInformation.transactionId
field in the original request for a
capture, sale, refund
, or credit
. The value of the merchant transaction ID must be unique for 180
days.When the original transaction fails, the response message for the reversal request
includes these fields:
- voidAmountDetails.originalTransactionAmount
- processorInformation.responseCode
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/voids/Test:
POST
https://apitest.cybersource.com
/pts/v2/voids/