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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Authorizations 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[]
array
.

Fields 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 when
item_#_productCode
is set to
default
,
shipping_only
,
handling_only
, or
shipping_and_handling
orderInformation.lineItems[].productName
Optional when
item_#_productCode
is set to
default
,
shipping_only
,
handling_only
, or
shipping_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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Authorizations 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 Guide
.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Authorizations 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 the
    processorInformation.cardVerification.resultCodeRaw
    field. 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 the
    processorInformation.cardVerification.resultCode
    field.
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 of
1
in the
processorInformation.cardVerification.resultCode
field 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 the
processorInformation.cardVerification.resultCode
field, which indicates that the CVN failed.
CVN Results for Visa and Mastercard
A CVN code of
D
or
N
causes the request to be declined with a reason code value of
230
. 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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Authorizations 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:
Types of SCA Exemptions
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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Pre-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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Incremental 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
{id}
is the transaction ID returned in the original authorization response.

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 on
    Visa 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}
/reversals
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/reversals
The
{id}
is the transaction ID returned in the authorization response.

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/reversals
Test:
POST
https://apitest.cybersource.com
/pts/v2/reversals

Sales

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/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Captures

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}
/captures
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/captures
The
{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}
/captures
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/captures
The
{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

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}
/refunds
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/refunds
The
{id}
is the transaction ID returned in the capture or sale response.

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}
/voids
Test:
POST
https://apitest.cybersource.com
/pts/v2/captures/
{id}
/voids
Void a Credit
Production:
POST
https://api.cybersource.com
/pts/v2/credits/
{id}
/voids
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits/
{id}
/voids
The
{id}
is the transaction ID returned during the request to void.

Timeout Voids for a Capture, Sale,
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/