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 email@example.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:
|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.|
The following table lists the regional availability for CyberSource Payments. To view availability of all products, refer to the Availability Matrix.
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:
This diagram shows how real-time electronic card processing works using CyberSource Payments.
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.
CyberSource is part of the Visa network.
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.
The following figure shows the steps that occur when you request an online credit card authorization.
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.
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:
In the authorization request under paymentInformation 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:
For MasterCard requests:
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.
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.
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:
In the authorization request under paymentInformation object:
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:
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:
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.
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:
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:
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.
POST the authorization information to the REST API capture resource.
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.
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.
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.
POST the ID of the capture, credit, or refund to the REST API void resource. For details, refer to Void A Sale.
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.
POST the ID of the capture to our REST API refund resource. For details, refer to Retrieve A Refund.
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.
POST the customer card information to the REST API credit resource. For details, refer to Create A Credit.
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.
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:
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.
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.
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.
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.
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.