CyberSource Payments Documentation

Ready to start coding?

Things to Know

The current RESTful APIs only support a limited set of CyberSource solutions. Stay tuned for the advanced payment options. For further information or to plan your production roll out, contact developer@visa.com.

Before moving to production and running real transactions, you must have a merchant account from an acquiring (merchant) bank that can process the credit card payments. Some banks may not be familiar with Internet Commerce and could require more time to establish your account. The merchant bank account must be configured to process card not-present or mail order/telephone order (MOTO) transactions.

The following table lists the types of fees that can be charged:

Fee Description
Discount rates Your acquiring bank charges a fee and collects a percentage of every transaction. A combination of fee and percentage is called the discount rate. These charges can be bundled (combined into a single charge) or unbundled (charged separately) depending on your acquiring bank and other factors.
Interchange fees Visa and MasterCard each have a base fee, called the interchange fee, for each type of transaction. Your acquiring bank and processor can explain how to minimize this fee.
Chargebacks When customers dispute charges to their accounts, you can incur chargebacks. A chargeback occurs when a charge on a customer’s account is reversed. Your merchant bank removes the money from your account and could charge you a fee for the chargeback.

Availability

The following table lists the regional availability for CyberSource Payments. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
CyberSource Payments
Product Name Availability Notes
CyberSource Payments
Product Name Availability Notes
CyberSource Payments
Product Name Availability Notes
CyberSource Payments
Product Name Availability Notes
CyberSource Payments

Getting Started

You can process credit, debit and gift cards across the globe and across multiple channels with scalability and security. CyberSource supports an extensive list of payment cards and offers a wide choice of gateways and acquiring banks, all through one connection.

Get started by creating a project that utilizes the CyberSource Payments API. Once the project is created, you receive a Merchant Registration Confirmation email from CyberSource. Follow the email instructions to activate your admin account and to log in to the CyberSource Enterprise Business Center (EBC). Use the EBC to search for transactions, view reports and other administration tasks.

The CyberSource Payments API uses the following RESTful API concepts:

  1. Resources: each payment function is accessed with a “resource”, such as authorizations, captures, etc. Each individual payment object, such as an authorization, can also be accessed with its unique resource id.
  2. HTTP Verbs and Status: use HTTP GET to retrieve resource details and use HTTP POST to submit requests (for example, a payment authorization request) that change the state of the resource. The HTTP status code 200 is returned for a successful API call. Other HTTP status codes, such as 400 and 500, are returned for unsuccessful calls.
  3. Hypermedia links for follow-on actions: CyberSource Payments API uses JSON Hypertext Application Language (HAL) to inform the follow-on actions that can be performed on a resource. For example, a payment capture can be performed on a successful payment authorization. If the HTTP Accept header is not found or has the value of “application/hal+json”, HAL links are returned in the response. If the HTTP Accept header has the value of “application/json”, plain JSON objects without HAL links are returned in the response.

How Does It Work?

  1. Purchaser places order.
  2. Merchant securely transfers order information to CyberSource, using the CyberSource Payments API.
  3. CyberSource formats the transaction detail appropriately and securely routes the transaction authorization request through its payment gateway to the processor.
  4. The transaction is then routed to the issuing bank (purchaser's bank) to request transaction authorization.
  5. The transaction is authorized or declined by the issuing bank or card (Discover, American Express).
  6. CyberSource returns the message to the merchant.
  7. Issuing bank approves transfer of money to acquiring bank.
  8. The acquiring bank credits the merchant's account.

This diagram shows how real-time electronic card processing works using CyberSource Payments.

Why Use It?

Global Payment Flexibility

Change and add gateway and acquirer connections as business needs evolve. Choice of bank and processor connections in over 190 countries.

Comprehensive Consolidated Reporting

Single report aggregates transaction history across card brands and processors, worldwide.

Security

CyberSource is part of the Visa network.

APIs Included

CyberSource Payments

The CyberSource Payments API provides functionality for payment processing for authorization, capture, and settlement of card transactions, worldwide.

Secure Acceptance Flexible Token API

The Secure Acceptance Flexible Token API provides the most secure method for tokenizing card data and reduces your PCI DSS burden. Card data is encrypted on the customer’s device and sent directly to CyberSource, bypassing your systems altogether. 

Processing an Online Credit Card Transaction

The following figure shows the steps that occur when you request an online credit card authorization.

  1. The customer places an order and provides the credit card number, the card expiration date, and additional information about the card.
  2. Merchant securely transfers order information to CyberSource (for example, using the CyberSource Payment API).
  3. CyberSource formats the transaction details appropriately and securely routes the transaction authorization request through its payment gateway to the processor.
  4. The transaction is then routed to the issuing bank (purchaser's bank) to request transaction authorization.
  5. The transaction is authorized or declined by the issuing bank or card (Discover or American Express).
  6. CyberSource returns the message to the merchant.
  7. Merchant captures the authorization. Issuing bank approves transfer of money to the acquiring bank.
  8. The acquiring bank credits the merchant's account.

Authorizing a Payment

CyberSource supports authorizations for all processors. Online authorization means that when you submit an order using a credit card, you receive an immediate confirmation about the availability of the funds. If the funds are available, the issuing bank reduces your customer’s open to buy, which is the amount of credit available on the card. Most of the common credit cards are processed online. For online authorizations, you typically start the process of order fulfillment soon after you receive confirmation of the order.

Online authorizations expire with the issuing bank after a specific length of time if they have not been captured and settled. Most authorizations expire within five to seven days. The issuing bank sets the length of time. When an authorization expires with the issuing bank, your bank or processor might require you to resubmit an authorization request and include a request for capture in the same message.

Note: CyberSource is not informed by the issuing bank when an authorization expires. By default, the authorization remains in the CyberSource system for 60 days after the authorization date, even after it expires with the issuing bank.

Creating an Authorization Request

POST the credit card information to the REST API Authorization resource Authorize a Credit Card.

A number of payment solutions can be used to replace sending sensitive credit card information or primary account number (PAN) in the authorization request:

  • Payment Network Tokenization: The payment network token is a token created by a token service provider that replaces the PAN. It is a unique identifier that cannot be reverse-engineered and is used throughout the financial network.
  • Apple Pay: Apple Pay is the mobile payment solution from Apple. It utilizes the payment network tokenization functionality.
  • Android Pay: Android Pay is an in-app mobile payment solution that offers customers simplicity and security when making purchases using their Android devices. It utilizes the payment network tokenization functionality.
  • Visa Checkout: Visa Checkout is the fast and secure payment solution from Visa. It utilizes the payment network tokenization functionality.

Creating an Authorization Request with Payment Network Tokenization

In the authorization request under paymentInformation Object:

  1. Obtain the payment network token value and the expiration date of the token from the token service provider.
  2. Set the number filed under tokenizedCard object to the payment network token value.
  3. Set the expirationMonth and expirationYear fields  under tokenizedCard object to the payment network token expiration date. 
  4. Include the payment network transaction type field, which is transactionType under tokenizedCard object. The only supported value is “1”, and it indicates that this is an in-app transaction.
  5. On CyberSource through VisaNet, you can choose to include the requestor ID field, which is requestorID under tokenizedCard object.

For in-app transactions, payment network tokenization uses some of the CyberSource payer authentication request fields. In this case, additional payer authentication fields need to be included for different card types as described below.

For Visa requests:

  1. Set the commerceIndicator field under processingInformation object to “vbv or internet”.
  2. Set the xid field under consumerAuthenticationInformation object to the 3D Secure cryptogram of the payment network token.
  3. Set the cavv under consumerAuthenticationInformation Object to the 3D Secure cryptogram of the payment network token.

For MasterCard requests:

  1. Set the commerceIndicator field under processingInformation object  to “spa” .
  2. Set the ucafAuthenticationData field under consumerAuthenticationInformation Object to the 3D Secure cryptogram of the payment network token.
  3. Set the ucafCollectionIndicator field under consumerAuthenticationInformation Object to “2”

For American Express requests:

For the American Express card type, the cryptogram is a 20-byte or 40-byte binary value.

For a 20-byte cryptogram, send the cryptogram in the cardholder authentication verification value (CAVV) field.

  1. Set the commerceIndicator field under processingInformation object to “aesk”.
  2. Set the cavv under consumerAuthenticationInformation Object to 3D Secure cryptogram of the payment network token.

For a 40-byte cryptogram, split the cryptogram into two 20-byte binary values (block A and block B). Send the first 20-byte value (block A) in the cardholder authentication verification value (CAVV) field. Send the second 20-byte value (block B) in the transaction ID (XID) field.

  1. Set the commerceIndicator field under processingInformation object to “aesk”.
  2. Set the cavv field under consumerAuthenticationInformation Object to block A of the 3D Secure cryptogram of the payment network token.
  3. Set the xid field under consumerAuthenticationInformation Object to block  of the 3D Secure cryptogram of the payment network token.

Creating an Authorization Request with Apple Pay

CyberSource offers merchants two options for processing Apple Pay transactions: merchant decryption or CyberSource decryption. Both options are available for In-App transactions and Web transactions. 

The merchant decryption option allows the merchant to decrypt the encrypted payment data from Apple to retrieve the Payment Network Token, the expiry date, the cryptogram and other payment data associated with the transaction. In order to use this option, you must obtain a Certificate Signing Request (CSR) directly from Apple. The merchant then submits the authorization request with the Payment Network Tokenization data as outlined above in Creating an Authorization Request with Payment Network Tokenization.

The CyberSource decryption option allows you to simplify your payment processing by allowing CyberSource to decrypt the payment data for you during processing. In order to use this option, the merchant should:

  1. Log into CyberSource EBC, enable Apple Pay in “Account Management” > “Digital Payment Solutions”, and generate a Certificate Signing Request (CSR).
  2. Submit the CSR to Apple and obtain the Apple Pay certificate which is required for creating an iOS application.

In the authorization request under paymentInformation object:

  1. Set the key  field under fluidData object to the base 64 encoded value obtained from the paymentData property of the PKPaymentToken object as described in the PassKit Framework Reference.
  2. Set the descriptor field under fluidData object to “RklEPUNPTU1PTi5BUFBMRS5JTkFQUC5QQVlNRU5U”.
  3. Set the encoding field under fluidData objectto “Base64”.
  4. Set the paymentSolution field under processingInformation object to “001”.

Creating an Authorization Request with Android Pay

CyberSource offers merchants two options for processing Android Pay transactions: merchant decryption or CyberSource decryption.

The merchant decryption option allows the merchant to decrypt the payment data from Google to retrieve the Payment Network Token, the expiry date, the cryptogram, and other payment data associated with the transaction. The merchant then submits the authorization request with the Payment Network Tokenization data as outlined above in Creating an Authorization Request with Payment Network Tokenization.

The CyberSource decryption option allows you to simplify your payment processing by allowing CyberSource to decrypt the payment data for you during processing. This method removes the complexity from your integration which enables you to process transactions without seeing the Payment Network token and transaction data. In order to use this option, the merchant should:

  1. Log into CyberSource EBC, enable Android Pay in “Account Management” > “Digital Payment Solutions”, and generate a public key.
  2. Include the public key in the paymentMethodTokenizationParameters parameter in the Android Pay Masked Wallet request (https://developers.google.com/android/reference/com/google/android/gms/wallet/MaskedWalletRequest.Builder).
  3. Use the Android Pay API to create a Masked Wallet request (https://developers.google.com/android/reference/com/google/android/gms/wallet/MaskedWallet) to retrieve the Masked Wallet information.
  4. When the customer confirms the payment, create a Full Wallet request (https://developers.google.com/android/reference/com/google/android/gms/wallet/FullWallet), and obtain the encryptedMessage from the response.
  5. Send the authorization request to the CyberSource Payments API, and in the request,
    1. Set the key field under paymentInformation --> fluidData object to the value of the encryptedMessage field that was returned in the Full Wallet response.
    2. Set the commerceIndicator field under processingInformation object to “internet” for Visa card, “spa” for MasterCard, and “aesk” for American Express card.
    3. Set the paymentSolution field under processingInformation object to “006”.

Creating an Authorization Request with Visa Checkout

You may configure Visa Checkout so that you can receive your customer's Payment Account Number (PAN) data with each Visa Checkout transaction. The PAN data must be protected in compliance with the Payment Card Industry Data Security Standard (PCI-DSS). Alternatively, CyberSource can manage the PAN data on your behalf allowing you to continue to perform payment processing without receiving the PAN data directly. In order to use this option, the merchant needs to:

  1. Log into CyberSource EBC and sign up for Visa Checkout in Account Management > Digital Payment Solutions.

    Note: You will be required to enter a valid domain URL from which your Visa Checkout transaction will originate. Accept the Visa Checkout Services Agreement.

    After this, an API key will be generated for you to integrate Visa Checkout into your checkout solution. It is important to note that this API key is only used for Visa Checkout integration. You should continue to use your Visa Developer project’s API key and shared secret to integrate with Visa Developer.

  2. Send the authorization request to the CyberSource Payments API and include the following in the request: 
    1. Set the value field under paymentInformation --> fluidData object to the encrypted payment data obtained from Visa Checkout. 
    2. Set the key field under paymentInformation --> fluidData object object to the encrypted key obtained from Visa Checkout. 
    3. Set the visaCheckoutID field under processingInformation to the callid obtained from Visa Checkout. d. Set the paymentSolution field to “visacheckout”.

Creating a Card-Present or EMV Authorization Request

When a customer uses a card that is physically present to make a purchase, the purchase is known as a card-present transaction. This type of transaction typically occurs in a retail environment where merchants use the point-of-sale (POS) terminals to accept credit or debit cards.

A card-present authorization request should:

  1. Set the cardPresent indicator to “Y” under pointOfSaleInformation object and commerceIndicator to “retail” under processingInformation object.
  2. Set the POS-related data fields under pointOfSaleInformation object: entryMode (swiped, keyed, etc.), trackData (when entryMode is swiped), catLevel (type of cardholder-activated terminal), and terminalcapability (POS terminal’s capability).
  3. Set the card data under paymentInformation --> card Obejct: cardType, cardNumber (when the entryMode is keyed), expirationMonth, expirationYear, securityCode, securityCodeIndicator(whether a CVN code was sent).
  4. Set the amount and currency of the transaction under orderInformation --> amountDetails object.

EMV (Europay, MasterCard, Visa) is a global standard for exchanging information between chip cards and POS terminals. A chip card is a credit or debit card with an embedded microchip. A chip card also has a magnetic stripe on the back of the card, which can be used for a back-up transaction when the card’s chip cannot be read. The EMV standards define the protocols for all levels of transmission between chip cards and chip card processing devices: physical, electrical, data, and application.

EMV transactions are more secure from fraud than are magnetic stripe transactions, which require a visual inspection of the card. When an EMV chip card is used in a POS environment, it generates a cryptogram that changes with each transaction. This dynamic authentication provides an extra layer of security for the POS transactions.

An EMV authorization request should:

  1. Set the cardPresent indicator to “Y” under pointOfSaleInformation object and commerceIndicator to “retail” under processingInformation object.
  2. Set the POS-related data under pointOfSaleInformation object: entryMode (contact, contactless, or msd) and capability (POS terminal’s capability). In addition, trackData is required for certain processors (Chase Paymentech and FDC Nashville Global).
  3. Set the EMV data under pointOfSaleInformation --> emv object:
    1. tags: EMV data that is transmitted from the chip card to the issuer, and from the issuer to the chip card. The EMV data is in the tag-length-value format and includes chip card tags, terminal tags, and transaction detail tags. For information about the individual tags, see the “Application Specification” section in the [EMV 4.3 Specifications] (http://emvco.com).
    2. cardSequenceNumber: Number assigned to a specific card when two or more cards are associated with the same primary account number.
    3. fallback: Indicates that a fallback method was used to enter credit card information into the POS terminal, when a technical problem prevents a successful exchange of information between a chip card and a chip-capable terminal.
  4. Set the amount and currency of the transaction under orderInformation --> amountDetails object. For details, refer to Authorize a Credit Card.

Capturing an Authorization

When you are ready to fulfill a customer’s order and transfer funds from the customer’s bank to your bank, capture the authorization for that order. If you can fulfill only part of a customer’s order, do not capture the full amount of the authorization. Capture only the cost of the items that you ship. When you ship the remaining items, request a new authorization, then capture the new authorization.

Unlike authorizations, a capture does not happen in real time. All of the capture requests for a day are placed in a batch file and sent to the processor. In most cases, the batch is settled at night. It usually takes two to four days for your acquiring bank to deposit funds in your merchant bank account.

The following figure shows the steps that occur when you request a capture or credit.

You can send a request for capture or credit (via CyberSource Payment API).

CyberSource validates the order information then stores the capture or credit request in a batch file. After midnight, CyberSource sends the batch file to your payment processor.

The processor settles the capture or credit request and transfers funds to the appropriate bank account.

Creating a Capture Request

POST the authorization information to the REST API capture resource.

Performing a Sale

A sale is a bundled authorization and capture. You can use a sale instead of a separate authorization and capture if there is no delay between taking a customer’s order and shipping the goods. A sale is typically used for electronic goods and for services that you can turn on immediately.

Creating a Sale Request

POST the authorization information to the 'payment' resource with capture Flag under processingInformation object set to true. That specifies whether to also include capture service in the submitted request or not. No additional fields are required for the capture. If the authorization is successful, CyberSource processes the capture immediately and the reply message includes results for the authorization and for the capture. If the authorization is declined, CyberSource does not process the capture and the reply message includes results only for the authorization.

Voiding a Payment

To stop a payment (capture, refund, or credit) from being completed through the nightly CyberSource batching process you can void that payment with a Void request.

Creating a Void Request

POST the ID of the capture, credit, or refund to the REST API void resource. For details, refer to Void A Sale.

Refunds

A refund (sometimes called a follow-on credit) is linked to a capture in the CyberSource system. You can request multiple refunds against a single capture. If you are using the CyberSource through VisaNet processor, you must request a follow-on credit within 180 days of the authorization. For all other processors, you must request a follow-on credit within 60 days of the authorization.

When your request for a refund is successful, the issuing bank for the credit card takes money out of your merchant bank account and returns it to the customer. It usually takes two to four days for your acquiring bank to transfer funds from your merchant bank account.

Creating a Refund Request

POST the ID of the capture to our REST API refund resource. For details, refer to Retrieve A Refund.

Credits

A credit (sometimes called a standalone or unlinked credit) is not linked to a capture. There is no time limit for requesting standalone credits. Instead of sending the capture ID, the request must include the fields for the customer’s billing and account information.

Creating a Credit Request

POST the customer card information to the REST API credit resource. For details, refer to Create A Credit.

Reversing an Authorization

You can use the authorization reversal service to reverse an unnecessary or undesired authorization. A successful authorization reversal releases the hold that the authorization placed on the customer’s credit card funds. As a best practice, you should reverse an authorization only after the associated capture has been voided.

For details, refer to Reverse a Payment Authorization.

Note: For some processors, you can use the authorization reversal service only for an authorization that has not been captured and settled. Each issuing bank has its own rules for deciding whether a full authorization reversal succeeds or fails. If your reversal fails, contact the processor or the issuing bank to find out whether it is possible to reverse the authorization using alternate means.

Processing Level II and Level III Cards

If a merchant deals with business, corporate or government purchasing cards, it can benefit from lower credit card processing fees by submitting Level II and Level III data. Level II and Level III data enable customers to easily track the amount of tax they pay and to reconcile transactions with a unique customer code. The difference between Level II and Level III is the amount of data that is captured for payment processing.

Level II data includes the following:

  1. Standard Info: credit card number and expiration, billing address, shipping address, and invoice number.
  2. Customer Code: unique reference id for the order.
  3. Tax: an amount must be submitted separately from the total transaction amount. Level III data includes the Level II data, plus the following:
  4. Freight Amount: Total freight or shipping and handling charges for the order.
  5. Duty Amount: Total charges for any import or export duties included in the order.
  6. Line Item Details, including item id, item description, quantity, unit of measure, price sold, tax, and alternate tax information.

Contact CyberSource Customer Support to have your account configured to process Level III data. If your account is not enabled, and you are trying to send live Level III transactions, you will receive an error for invalid data.

You can send Level II and Level III data in Capture, Sale, Credit, or Refund requests. Make sure the purchasingLevel field in the request is set to 3 for Level III data. The response includes the level3Enabled field that indicates whether CyberSource sent the Level III information to the processor.

Tokenizing Card Data

Storing your customer’s card data can dramatically increase your repeat-custom conversion rate, but it can also introduce additional risk along with a PCI DSS overhead. This can be mitigated by tokenizing card data. CyberSource will replace your customer’s card data with a token and store it, so it can only be used by you.

Secure Acceptance Flexible Token API provides a secure method for tokenizing card data and reduces your PCI DSS burden. Card data is encrypted on the customer’s device and sent directly to CyberSource, bypassing your systems altogether.

The API consists of two resources: keys and tokens.

Keys

Create a one-time use public key and Key ID to encrypt the card data on your customer's device (a browser or a native app). This is an authenticated request initiated from your server, prior to tokenizing the card data. 

Tokens

Create a token that represents the customer's card details. This is an unauthenticated request from your customer's device. For details, refer to Secure Acceptance Flexible Token API.

Use Error Resource API for Error Details

When the HTTP status code 200 is not received in the HTTP response, an error has occurred when processing the request. In this case, the response will have an error reason code, an error message and a correlationId which can be used to retrieve additional details, including the original request and response objects.