Payments Developer Guide {#payments-about-guide} ================================================ This section describes how to use this guide and where to find further information. Audience and Purpose : This guide is written for application developers who want to use the `REST API` to integrate payment card processing into an order management system. Implementing the `Cybersource` payment services requires software development skills. You must write code that uses the API request and response fields to integrate the payment card services into your existing order management system. Conventions : These statements appear in this document: > IMPORTANT > An *Important* statement contains information essential to successfully completing a task or learning a concept. > WARNING > A *Warning* contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both. Related Documentation : Visit the [`Cybersource` documentation hub](https://developer.cybersource.com/docs.md "") to find additional processor-specific versions of this guide and additional technical documentation. Customer Support : For support information about any service, visit the Support Center: Recent Revisions to This Document {#payments-doc-revisions} =========================================================== 26.04.01 -------- Added related reference information (Related to this Page) to applicable topics. Added [Void a Payment](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-sale-void-intro.md ""). 26.02.01 -------- Pre-Authorization : Added an important note about using strong customer authentication. See [Pre-Authorization](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-pre-auth-intro.md ""). : Updated required fields and examples. See [Required Fields for a Pre-Authorization](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-pre-auth-intro/payments-processing-pre-auth-required.md ""). 26.01.02 -------- This revision contains only editorial changes and no technical updates. 26.01.01 -------- This revision contains only editorial changes and no technical updates. 25.09.02 -------- This revision contains only editorial changes and no technical updates. 25.09.01 -------- This revision contains only editorial changes and no technical updates. 25.08.01 -------- This revision contains only editorial changes and no technical updates. 25.07.01 -------- This revision contains only editorial changes and no technical updates. 25.05.01 -------- Pre-Authorizations : Added information about releasing the hold on authorized amounts after 30 days. See [Pre-Authorization](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-pre-auth-intro.md ""). Introduction to Payments {#payments-intro} ========================================== This introduction provides the basic information that you need to successfully process payment transactions. It also provides an overview of the payments industry and provides workflows for each process. With `Cybersource` payment services, you can process payment cards (tokenized or non-tokenized), digital payments such as Apple Pay and Google Pay, and customer ID transactions. You can process payments across the globe and across multiple channels with scalability and security. `Cybersource` supports a large number of payment cards and offers a wide choice of gateways and financial institutions, all through one connection. Visit the [`Cybersource` documentation hub](https://developer.cybersource.com/docs.md "") to find additional processor-specific versions of this guide and additional technical documentation. Financial Institutions and Payment Networks {#payments-intro-banks-overview} ============================================================================ Financial institutions and payment networks enable payment services to function. These entities work together to complete the full payment cycle. The `China UnionPay` payment processor is a direct connection to the UnionPay ISO endpoint. `China UnionPay` is for financial institutions that are located outside of China to process transactions directly with UnionPay. Merchant Financial Institutions (Acquirers) {#payments-intro-banks-acquiring} ============================================================================= A merchant financial institution, also known as an *acquirer*, offers accounts to businesses that accept payments. Before you can accept payments, you must have a merchant account from an acquirer. Your merchant account must be configured to process card-not-present or mail-order/telephone-order (MOTO) transactions. Each acquirer has connections to a limited number of payment processors. You must choose a payment processor that your acquirer supports. You can expect to pay these fees: * Discount rates: your acquirer charges a fee and collects a percentage of every transaction. The combination of the fee and the percentage is called the *discount rate* . These charges can be *bundled* (combined into a single charge) or *unbundled* (charged separately). * Interchange fees: payment networks, such as Visa or Mastercard, each have a base fee, called the *interchange fee*, for each type of transaction. Your acquirer and processor can show you ways to reduce this fee. * Chargebacks: when cardholders dispute charges, you can incur *chargebacks*. A chargeback occurs when a charge on a customer's account is reversed. Your acquirer removes the money from your account and could charge you a fee for processing the chargeback. Take these precautions to prevent chargebacks: * Use accurate merchant descriptors so that customers can recognize the transactions on their statements. * Provide good customer support. * Ensure rapid problem resolution. * Maintain a high level of customer satisfaction. * Minimize fraudulent transactions. If excessive chargebacks or fraudulent changes occur, these actions might be taken: * You might be required to change your business processes to reduce the number chargebacks, fraud, or both. * Your acquiring institution might increase your discount rate. * Your acquiring institution might revoke your merchant account. Contact your sales representative for information about products that can help prevent fraud. Customer Financial Institutions (Issuers) {#payments-intro-banks-issuing} ========================================================================= A customer financial institution, also known as an *issuer*, provides payment cards to and underwrites lines of credit for their customers. The issuer provides monthly statements and collects payments. The issuer must follow the rules of the payment card companies to which they belong. Payment Networks {#payments-intro-card-companies} ================================================= Payment networks manage communications between acquirers and issuing banks. They also develop industry standards, support their brands, and establish fees for acquiring institutions. Some payment networks, such as Visa and Mastercard, are trade associations that do not issue cards. Issuers are members of these associations, and they issue cards under license from the association. Payment Processors {#payments-intro-processors} =============================================== Payment processors connect with acquirers. Before you can accept payments, you must register with a payment processor. An acquirer might require you to use a payment processor with an existing relationship with the acquirer. Your payment processor assigns one or more merchant IDs (MIDs) to your business. These unique codes identify your business during payment transactions. Card Types {#payments-intro-cards-types} ======================================== You can process payments with these kinds of cards: * Domestic debit cards * Domestic credit cards * International debit cards * International credit cards For `China UnionPay`, domestic cards are payment cards that are issued within China and international cards are payment cards that are issued outside China. For a list of supported card types, see [Payment Processors](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-intro/payments-intro-banks-overview/payments-intro-processors.md ""). Co-Badged Cards {#payments-intro-cobadge-cards} =============================================== Co-badged cards are credit and debit cards that integrate two or more payment networks. `China UnionPay` supports cards co-badged with other payment networks, such as Visa, Mastercard, and Discover. Co-Branded Cards {#payments-intro-cobrand-cards} ================================================ Co-branded cards are credit cards that are branded with a merchant's logo, brand, or other identifier as well as the payment network logo. These cards are not limited for use at the branded merchant and can be used at any merchant that accepts credit cards. China UnionPay card transactions are processed through the `China UnionPay` gateway. Visa and Mastercard transactions are processed through the `Visa Platform Connect` gateway. For co-branded cards, the routing is determined by the value set for the card type field paymentInformation.card.type in the transaction request. When the card type value is `001` for a Visa card, the transaction is routed through the `Visa Platform Connect` gateway. When the card type value is `062` for a China UnionPay card, the transaction is routed through the `China UnionPay` gateway. When you do not include the card type field, the system defaults to the primary card brand for the card's bank identification number (BIN). `Cybersource` automatically manages the system default process, eliminating the need for additional integration by resellers or merchants. Credit Cards {#payments-intro-credit-cards} =========================================== Cardholders use credit cards to borrow money from issuing banks to pay for goods and services offered by merchants that accept credit cards. Debit Cards {#payments-intro-debit-cards} ========================================= A debit card is linked to a cardholder's bank account. The funds are taken out of the customer's bank account, and the transaction is included on the customer's bank account statement. The customer does not receive a credit card bill as with a regular credit card. `China UnionPay` ---------------- Process debit cards using the credit card services. See [Standard Payment Processing](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro.md ""). Most domestic debit cards issued before 2016 do not have a card verification number (CVN) and expiration date. The `China UnionPay` processor does not support payment processing for cards that do not have a CVN and expiration date. Transaction Types {#payments-intro-transactions-overview} ========================================================= This topic provides information about transaction types that are supported by your processor. Card-Not-Present Transactions {#payments-intro-transactions-card-not-present} ============================================================================= When a customer provides a card number, but the card and the customer are not physically present at the merchant's location, the purchase is known as a *card-not-present transaction*. Typical card-not-present transactions are internet and phone transactions. Card-not-present transactions pose an additional level of risk to your business because the customer's identification cannot be verified. You can reduce that risk by using features such as the Address Verification System (AVS) and Card Verification Numbers (CVNs). The AVS and CVNs provide additional protection from fraud by verifying the validity of the customer's information and notifying you when discrepancies occur. Payment Services {#payments-services-intro} =========================================== Various services are involved in processing payments. These services enable customers to purchase goods and services. They also enable merchants to receive payments from customer accounts, to provide refunds, and to void transactions. Contact your acquirer to confirm the specific capabilities they support. Authorization {#payments-intro-processing-auth} =============================================== An authorization confirms that a payment card account holds enough funds to pay for a purchase. Authorizations can be made online or offline. Online Authorization {#payments-intro-processing-auth-online} ============================================================= Online authorizations provide immediate confirmation of funds availability. The customer's financial institution also reduces the amount of credit available in the customer's account, setting aside the authorized funds for the merchant to capture at a later time. Authorizations for most payment cards are processed online. Typically, it is safe to start fulfilling the order when you receive an authorization confirmation. AnAn online authorization confirmation and the subsequent hold on funds expire after a specific length of time. Therefore it is important to capture funds in a timely manner. The issuing bank sets the expiration time interval, but most authorizations expire within 5 to7 days. The issuing bank does not inform `Cybersource` when an authorization confirmation expires. By default, the authorization information for each transaction remains in the `Cybersource` database for 180 days after the authorization date. To capture an authorization that expired with the issuing bank, you can resubmit the authorization request. Pre-Authorization {#payments-intro-pre-auths} ============================================= A pre-authorization enables you to authorize a payment when the final amount is unknown. The system places the funds on hold until you request a follow-up transaction. Pre-authorizations are typically used for lodging, auto rental, e-commerce, and restaurant transactions. IMPORTANT Payment Services Directive 2 (PSD2) rules in the European Union (EU) and European Economic Area (EEA) require the initial pre-authorization to use strong customer authentication for merchants or customers in PSD2-applicable countries. When you have a specific merchant category code (MCC) assigned to your account, you are allowed to capture up to 20% more than the cumulatively authorized amount on Visa, Diners Club, Discover, and JCB cards. Contact your account manager to have your account enabled for this option. For a pre-authorization: * The authorization amount is greater than zero. * Submit the authorization for capture within 30 calendar days of its request. * After 30 calendar days, the customer bank (issuer) releases the hold on the authorized amount. * Send a new authorization request to claim the amount. Authorization Workflow {#payments-intro-processing-auth-workflow} ================================================================= This image and description show the authorization workflow: ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/Authorization2.svg/jcr:content/renditions/original) 1. The customer purchases goods or services from the merchant using a payment card. 2. You send an authorization request over secure internet connection to `Cybersource`. When the customer buys a digitally delivered product or service, you can request both the authorization and the capture at the same time. When the customer buys a physically fulfilled product, do not request the capture until you ship the product. 3. `Cybersource` validates the order information then contacts your payment processor and requests authorization. 4. The processor sends the transaction to the payment card company, which routes it to the issuing bank for the customer's payment card. Some card companies, including Discover, act as their own issuing banks. 5. The issuing bank approves or declines the request. * If funds are available, the issuing bank reserves the amount of the authorization request and returns an authorization approval to `Cybersource`. * If the issuing bank denies the request, it returns an authorization denial to `Cybersource`. {#payments-intro-processing-auth-workflow_ul_smg_gg5_rbc} 6. `Cybersource` runs its own tests then tells you whether the authorization succeeded. Sale {#payments-intro-processing-sales} ======================================= A sale is a bundled authorization and capture. Some processors and acquirers require a sale transaction instead of using separate authorization and capture requests. For other processors and acquirers, you can request a sale instead of a separate authorization and capture when you provide the goods or services immediately after taking an order. There are two types of sale processing: dual-message processing and single-message processing. Authorization Reversal {#payments-intro-processing-reversal} ============================================================ The authorization reversal service releases the hold that an authorization placed on a customer's payment card funds. Each card-issuing financial institution has its own rules for deciding whether an authorization reversal succeeds or fails. When a reversal fails, contact the card-issuing financial institution to learn whether there is a different way to reverse the authorization. An authorization reversal is a follow-on transaction that uses the request ID returned from an authorization. The main purpose of a follow-on transaction is to link two transactions. The request ID links the follow-on transaction to the original transaction. The authorization request ID is used to look up the customer's billing and account information in the `Cybersource` database. You are not required to include those fields in the full authorization reversal request. The original transaction and follow-on transaction are linked in the database and in the `Business Center`. For processors that support debit cards and prepaid cards, the full authorization reversal service works for debit cards and prepaid cards in addition to credit cards. > IMPORTANT > You cannot perform an authorization reversal if a transaction is in a review state, which can occur if you use a fraud management service. You must reject the transaction prior to authorization reversal. For more information, see the fraud management documentation in the ` Business Center `. Capture {#payments-intro-processing-capture} ============================================ A capture is a follow-on transaction to an authorization. It is used to transfer the authorized funds from the customer's account to the merchant account. To link the authorization transaction to the capture transaction, you include a request ID in your capture request. This request ID is returned to you in the authorization response. When fulfilling only part of a customer's order, do not capture the full amount of the authorization. Capture only the cost of the delivered items. When you deliver the remaining items, request a new authorization, and then capture the new authorization. > IMPORTANT > It is not possible to perform a capture if a transaction is in a review state, which can occur if you use a fraud management service. You must accept the transaction prior to capture. For more information, see the fraud management documentation in the ` Business Center `. Capture Workflow {#payments-intro-processing-capture-workflow} ============================================================== The capture workflow begins when you send a request for a capture. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/payments-capture-flow-660x225.svg/jcr:content/renditions/original) 1. The merchant sends a request for a capture to the `Cybersource` gateway. 2. For online captures, `Cybersource` validates the order information then sends an online capture to the payment processor. 3. The processor validates the request and forwards it to the issuing bank. 4. The issuing bank transfers funds to the acquiring bank. > IMPORTANT > The payment processor does not notify ` Cybersource ` that the money has been transferred. To ensure that all captures are processed correctly, you should reconcile your capture requests with the capture reports from your processor. Refund {#payments-intro-processing-credit} ========================================== Refunds are payment refunds from a merchant to the cardholder after a cardholder pays for a product or service and that payment is captured by the merchant. When a refund request is successful, the issuer transfers funds from the merchant bank (acquirer) account to the customer's account. It typically takes 2 to 4 days for the acquirer to transfer funds from your merchant account. There are two types of refunds: a *follow-on refund* that is linked to an original capture or sale, and a *stand-alone credit* that is not linked to an original capture or sale. > WARNING > You should carefully control access to your refund and credit services. Do not request this service directly from your customer interface. Instead, incorporate this service as part of your customer service process. This process reduces the potential for fraudulent transactions. Follow-on Refund ---------------- Refund and Credit Workflow {#payments-intro-processing-credit-workflow} ======================================================================= This workflow applies to follow-on credits, also known as refunds, and stand-alone credits. It begins when you send a request for a refund or credit. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/payments-credit-660x225.svg/jcr:content/renditions/original) 1. The merchant sends the refund or credit request to `Cybersource`. 2. For online refunds and credits, `Cybersource` validates the order information then sends the request to the payment processor. 3. The processor validates the request and forwards it to the acquiring bank. 4. The acquiring bank transfers funds to the issuing bank. IMPORTANT Not all processors support stand-alone credits. Void {#payments-intro-processing-void} ====================================== A void cancels a capture or credit request that you submitted to `Cybersource` but has not already been submitted to your processor. Capture and credit requests are usually submitted to your processor once a day, so your window for successfully voiding a capture or credit request is small. A void request is declined when the capture or credit request has already been sent to the processor. After a void is processed, you cannot credit or capture the funds. You must perform a new transaction to capture or credit the funds. Further, when you void a capture, a hold remains on the authorized funds. If you are not going to re-capture the authorization, and if your processor supports authorization reversal after void (ARAV), you should request an authorization reversal to release the hold on the unused funds. A void uses the capture or credit request ID to link the transactions. The authorization request ID is used to look up the customer's billing and account information, so there is no need to include those fields in the void request. You cannot perform a follow-on credit against a capture that has been voided. Testing the Payment Services {#payments-testing-services} ========================================================= To ensure that requests are processed correctly, you must test the basic success and error conditions for each service you plan to use. Requirements for Testing {#payments-testing-requirements} ========================================================= Before you can test, contact customer support to activate the credit card services and configure your account for testing. You must also contact your processor to set up your processor account. > IMPORTANT > When building your connection to the ` Cybersource ` payment gateway, ensure that you have implemented controls to prevent card testing or card enumeration attacks on your platform. For more information, see the [best practices guide](https://www.cybersource.com/content/dam/documents/en/payment-card-testing-bot-attacks.pdf ""). When we detect suspicious transaction activity associated with your merchant ID, including a card testing or card enumeration attack, ` Cybersource ` reserves the right to enable fraud management tools on your behalf in order to mitigate the attack. The fraud team might also implement internal controls to mitigate attack activity. These controls block traffic that is perceived as fraudulent. Additionally, if you are using one of our fraud tools and experience a significant attack, our internal team might modify or add rules to your configuration to help prevent the attack and minimize the threat to our infrastructure. However, any actions taken by ` Cybersource ` would not replace the need for you to follow industry standard best practices to protect your systems, servers, and platforms. > Follow these requirements when you test your system: * Use your regular merchant ID. * Use a real combination for the city, state, and postal code. * Use a real combination for the area code and telephone number. * Use a nonexistent account and domain name for the customer's email address. * REST API test endpoint: `POST ``https://apitest.cybersource.com``/pts/v2/payments`{#payments-testing-requirements_restauth-test} Test Card Numbers {#payments-testing-cards} =========================================== Use these payment card numbers to test the authorization, capture, and credit services. Remove the spaces from the test card numbers when sending them to the test system. Do not use real payment card numbers. To test card types that are not included in the list, use an account number that is in the card's BIN range. For best results, try each test with a different service request and with different test payment card numbers. > IMPORTANT The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with these card numbers, remove the spaces and replace each X with a 0 (zero). * American Express---3782 8224 631X XX5 * Discover---6X11 1111 1111 1117 * JCB---3566 1111 1111 1113 * Maestro (International) * 5X33 9619 89X9 17 * 5868 2416 0825 5333 38 {#payments-testing-cards_ul_1} * Maestro (UK Domestic)---the issue number is not required for Maestro (UK Domestic) transactions. * 6759 4111 XXXX XXX8 * 6759 56XX 45XX 5727 054 * 5641 8211 1116 6669 {#payments-testing-cards_ul_2} * Mastercard * 2222 42XX XXXX 1113 * 2222 63XX XXXX 1125 * 5555 5555 5555 4444 {#payments-testing-cards_ul_3} * Visa---4111 1111 1111 1111 Using Amounts to Simulate Errors {#payments-testing-amounts} ============================================================ You can simulate error messages by requesting authorization, capture, or credit services with specific amounts that trigger the error messages. These triggers work only on the test server, not on the production server. Each payment processor uses its own error messages. For more information, see: [REST API Testing Guide](https://developer.cybersource.com/hello-world/testing-guide.md "") `China UnionPay` Test Cards {#payments-ref-test-cards-cup} ========================================================== Use these `China UnionPay` cards to test services. Replace each X with a 0 (zero). before using the card numbers. Card-not-present 3-D Secure enabled card : * Card: `625X947XXXXXXX14` * Expiration date (YYMM): `3312` * CVV2:`123` Card-not-present 3-D Secure 2.2 enabled card : * Frictionless: * `81XXX1XXXXXXX142` * `621XX3823532713X` * Challenge: * `81XXX1XXXXXXX688` * `621XX3257857442` Domestic China-issued card : * Card: `6222X4XXXXX3XX12` * Expiration date (YYMM): `4912` * CVV2: `123` International-issued card : * Card: `625X94X5XXXXXXX6` * Expiration date (YYMM): `4912` * CVV2: `123` UnionPay International and Visa co-branded card : * Card: `44278X2641XX4797` * Expiration date (YYMM): `4912` * CVV2: `123` UnionPay International and Mastercard co-branded card : * Card: `552XX123456789X3` * Expiration date (YYMM): `4912` * CVV2: `123` Test American Express Card Verification {#payments-testing-amex} ================================================================ Before using CVN with American Express, it is strongly recommended that you follow these steps: 1. Contact customer support to have your account configured for CVN. Until you do this, you will receive a `1` in the processorInformation.cardVerification.resultCode response field. 2. Test your system in production using a small currency amount, such as one currency unit. Instead of using the test account numbers, use a real payment card account number, and send an incorrect CVN in the request for authorization. The card should be refused and the request declined. Standard Payment Processing {#payments-processing-basic-intro} ============================================================== This section shows you how to process various authorization, capture, credit, and sales transactions. Pre-Authorization {#payments-processing-pre-auth-intro} ======================================================= 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. The system places the funds on hold until you request a follow-up transaction. Pre-authorizations are typically used for lodging, auto rental, e-commerce, and restaurant transactions. IMPORTANT Payment Services Directive 2 (PSD2) rules in the European Union (EU) and European Economic Area (EEA) require the initial pre-authorization to use strong customer authentication for merchants or customers in PSD2-applicable countries. When you have a specific merchant category code (MCC) assigned to your account, you are allowed to capture up to 20% more than the cumulatively authorized amount on Visa, Diners Club, Discover, and JCB cards. Contact your account manager to have your account enabled for this option. For a pre-authorization: * The authorization amount is greater than zero. * Submit the authorization for capture within 30 calendar days of its request. * After 30 calendar days, the customer bank (issuer) releases the hold on the authorized amount. * Send a new authorization request to claim the amount. For `China UnionPay`, use these services to manage pre-authorizations: * Capture service to process a pre-authorization completion. See [Capture](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-basic-capture-intro.md ""). * Authorization reversal service to reverse a pre-authorization. See [Authorization Reversal](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-basic-auth-reversal-intro.md ""). * Refund service to reverse a pre-authorization completion or sale. See [Follow-On Refund](/docs/cybs/en-us/payments/developer/cup/rest/payments/payments-processing-basic-intro/payments-processing-basic-refund-intro.md ""). Endpoint {#payments-processing-pre-auth-intro_d8e16} ---------------------------------------------------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments`{#payments-processing-pre-auth-intro_d8e25} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments`{#payments-processing-pre-auth-intro_d8e35} Required Fields for a Pre-Authorization {#payments-processing-pre-auth-required} ================================================================================ Use these required fields for processing a pre-authorization. [consumerAuthenticationInformation.cavv](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : Required for 3-D Secure transactions. [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.administrativeArea](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-admin-area.md "") : [orderInformation.billTo.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-company-country.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-locality.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions.authIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-auth-ind.md "") : Set the value to `0`. [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : Set the value to `internet`. REST Example: Processing a Pre-Authorization {#payments-processing-pre-auth-ex-rest-cup} ======================================================================================== Request ```keyword { "orderInformation": { "billTo": { "country": "US", "lastName": "Kim", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Kyong-Jin", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2025", "number": "62509470XXXXXXXX", "expirationMonth": "12", "type": "062" } }, "processingInformation": { "commerceIndicator": "internet" } ``` Response to a Successful Request ``` { "_links" : { "authReversal" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/reversals" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6461731521426399003473" }, "capture" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/captures" } }, "clientReferenceInformation" : { "code" : "1646173152047" }, "id" : "6461731521426399003473", "orderInformation" : { "amountDetails" : { "authorizedAmount" : "100.00", "currency" : "CNY" } }, "paymentAccountInformation" : { "card" : { "type" : "062" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "062" }, "card" : { "type" : "062" } }, "paymentInsightsInformation" : { "responseInsights" : { "categoryCode" : "01" } }, "processorInformation" : { "systemTraceAuditNumber" : "862481", "approvalCode" : "831000", "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } }, "reconciliationId" : "6461731521426399003473", "status" : "AUTHORIZED", "submitTimeUtc" : "2022-03-01T22:19:12Z" } ``` Response to a Declined Request ``` { "clientReferenceInformation": { "code": "TC50171_3" }, "errorInformation": { "reason": "PROCESSOR_ERROR", "message": "Invalid account" }, "id": "6583553837826789303954", "paymentInsightsInformation": { "responseInsights": { "categoryCode": "01", "category": "ISSUER_WILL_NEVER_APPROVE" } }, "pointOfSaleInformation": { "amexCapnData": "1009S0600100" }, "processorInformation": { "systemTraceAuditNumber": "004544", "merchantNumber": "1231231222", "networkTransactionId": "431736869536459", "transactionId": "431736869536459", "responseCode": "111", "avs": { "code": "Y", "codeRaw": "Y" } }, "status": "DECLINED" } ``` Authorization Reversal {#payments-processing-basic-auth-reversal-intro} ======================================================================= This section provides the information about how 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. For a debit card or prepaid card in which only a partial amount was approved, the amount of the reversal must be the amount that was authorized, not the amount that was requested. For `China UnionPay`, use the authorization reversal service to reverse pre-authorizations. All supported card types can process authorization reversals. Endpoint {#payments-processing-basic-auth-reversal-intro_d8e85} --------------------------------------------------------------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments/`*{id}*`/reversals`{#payments-processing-basic-auth-reversal-intro_d8e94} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments/`*{id}*`/reversals`{#payments-processing-basic-auth-reversal-intro_d8e107} The *{id}* is the transaction ID returned in the authorization response. Required Fields for Processing an Authorization Reversal {#payments-processing-basic-auth-reversal-required-fields} =================================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [reversalInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/reversal-info-aa/reversal-info-amount-details-currency.md "") : [reversalInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/reversal-info-aa/reversal-info-amount-details-total-amount.md "") : The amount of the reversal must be the same as the authorization amount that was included in the authorization response message. Do not use the amount that was requested in the authorization request message. REST Example: Processing an Authorization Reversal {#payments-processing-basic-auth-reversal-ex-rest} ===================================================================================================== Request ``` { "clientReferenceInformation": { "code": "test123" } "reversalInformation" : { "amountDetails" : { "totalAmount" : "100.00", "currency" : "USD" } } } ``` Response to a Successful Request ``` { "_links" : { "self" : { "method" : "GET", "href" : "/pts/v2/reversals/6869460219566537303955" } }, "clientReferenceInformation" : { "code" : "RTS-Auth-Reversal" }, "id" : "6869460219566537303955", "orderInformation" : { "amountDetails" : { "currency" : "USD" } }, "processorInformation" : { "responseCode" : "200" }, "reconciliationId" : "82kBK3qDNtls", "reversalAmountDetails" : { "reversedAmount" : "100.00", "currency" : "USD" }, "status" : "REVERSED", "submitTimeUtc" : "2023-06-16T20:07:02Z" } ``` Sale {#payments-processing-basic-sale-intro} ============================================ 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. For `China UnionPay`, use the refund service to reverse a sale. Endpoint {#payments-processing-basic-sale-intro_d8e240} ------------------------------------------------------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments`{#payments-processing-basic-sale-intro_d8e248} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments`{#payments-processing-basic-sale-intro_d8e258} Required Fields for a Sale {#payments-processing-basic-sale-reqfields} ====================================================================== [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.administrativeArea](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-admin-area.md "") : [orderInformation.billTo.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-country.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-locality.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") [paymentInformation.card.useAs](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-use-as.md "") [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : Set the value to `true`. [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : Set the value to `internet`. {#payments-processing-basic-sale-reqfields_dl_cw5_zzq_nfc} REST Example: Sale {#payments-processing-basic-sale-ex-rest-cup} ================================================================ Request ```keyword { "processingInformation": { "capture": true, "commerceIndicator": "internet" }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "VDP", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "RTS", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "CNY" } }, "paymentInformation" : { "card" : { "expirationYear" : "2025", "number" : "62509470XXXXXXXX", "expirationMonth" : "12", "type" : "062" } } } ``` Response to a Successful Request ``` { "_links" : { "void" : { "method" : "POST", "href" : "/pts/v2/payments/6485004068966546103093/voids" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6485004068966546103093" } }, "clientReferenceInformation" : { "code" : "RTS-Auth" }, "id" : "6485004068966546103093", "orderInformation" : { "amountDetails" : { "totalAmount" : "100.00", "authorizedAmount" : "100.00", "currency" : "CNY" } }, "paymentAccountInformation" : { "card" : { "type" : "062" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "062" }, "card" : { "type" : "062" } }, "processorInformation" : { "systemTraceAuditNumber" : "841109", "approvalCode" : "831000", "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "retrievalReferenceNumber" : "208720841109", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } }, "reconciliationId" : "6485004068966546103093", "status" : "AUTHORIZED", "submitTimeUtc" : "2022-03-28T20:46:47Z" } ``` Capture {#payments-processing-basic-capture-intro} ================================================== This section describes how to capture an authorized transaction. For `China UnionPay`, use the capture service to process pre-authorization completions. Endpoint {#payments-processing-basic-capture-intro_d8e127} ---------------------------------------------------------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments/`*{id}*`/captures`{#payments-processing-basic-capture-intro_d8e136} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments/`*{id}*`/captures`{#payments-processing-basic-capture-intro_d8e149} The *{id}* is the transaction ID returned in the authorization response. Required Fields for Capturing an Authorization {#payments-processing-basic-capture-required-fields} =================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : This field value maps from the original authorization, sale, or credit transaction. [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : REST Example: Capturing an Authorization {#payments-processing-basic-capture-ex-rest} ===================================================================================== Request ``` { "clientReferenceInformation": { "code": "ABC123" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6662994431376681303954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6662994431376681303954" } }, "clientReferenceInformation": { "code": "1666299443215" }, "id": "6662994431376681303954", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }, "reconciliationId": "66535942B9CGT52U", "status": "PENDING", "submitTimeUtc": "2022-10-20T20:57:23Z" } ``` Follow-On Refund {#payments-processing-basic-refund-intro} ========================================================== This section provides the information you need in order to process a follow-on refund, which is linked to a capture or sale. You must request a follow-on refund within 180 days of the authorization or sale. For `China UnionPay`, use the follow-on refund service to reverse pre-authorization completions, also known as captures, and sales. When your account is enabled for credit authorizations, also known as purchase return authorizations, `Cybersource` authenticates the card and customer during a follow-on refund or stand-alone credit request. Every credit request is automatically authorized. Credit authorization results are returned in these response fields: * processorInformation.approvalCode * processorInformation.networkTransactionId * processorInformation.responseCode {#payments-processing-basic-refund-intro_d21e25} When you request a void for a refund or credit before settlement, the refund or credit is voided. If your account is enabled for credit authorizations, the credit authorization is also reversed. Endpoint {#payments-processing-basic-refund-intro_d8e199} --------------------------------------------------------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments/`*{id}*`/refunds`{#payments-processing-basic-refund-intro_d8e207} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments/`*{id}*`/refunds`{#payments-processing-basic-refund-intro_d8e220} The *{id}* is the transaction ID returned in the capture or sale response. Required Fields for Processing a Refund {#payments-processing-basic-refund-required-fields} =========================================================================================== [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : REST Example: Processing a Refund {#payments-processing-basic-refund-ex-rest} ============================================================================= Request ``` { "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/6699964581696622603955/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/6699964581696622603955" } }, "clientReferenceInformation": { "code": "1669996458298" }, "creditAmountDetails": { "currency": "eur", "creditAmount": "100.00" }, "id": "6699964581696622603955", "orderInformation": { "amountDetails": { "currency": "EUR" } }, "paymentAccountInformation": { "card": { "type": "062" } }, "paymentInformation": { "tokenizedCard": { "type": "062" }, "card": { "type": "062" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "016153570198200", "responseCode": "100" }, "reconciliationId": "61873329OAILG3Q6", "status": "PENDING", "submitTimeUtc": "2022-12-02T15:54:18Z" } ``` Void a Payment {#payments-processing-sale-void-intro} ===================================================== This section describes how to void a payment that was submitted but not yet processed by the processor. A payment is also known as a sale, which is an authorization and capture in one API request. Include the payment ID in the void request endpoint to cancel the payment. Endpoint {#payments-processing-sale-void-intro_d8e429} ------------------------------------------------------ **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments/`*{id}*`/voids`{#payments-processing-sale-void-intro_d8e438} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments/`*{id}*`/voids`{#payments-processing-sale-void-intro_d8e451} The *{id}* is the transaction ID returned in the sale response. Required Fields for Voiding a Payment {#payments-processing-sale-void-required-fields} ====================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : REST Example: Voiding a Payment {#payments-processing-sale-void-ex-rest} ======================================================================== Request ``` { "clientReferenceInformation": { "code": "123456789012" } } ``` Response to a Successful Request ``` { "submitTimeUtc": "2025-03-11T16:39:30Z", "processorInformation": { "approvalCode": "OK1272", "responseCode": "000" }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500036" }, "orderInformation": { "amountDetails": { "authorizedAmount": "110.00" } }, "message": "Successful transaction.", "clientReferenceInformation": { "code": "123456789012" }, "reconciliationId": "000000050000771", "id": "7417111702443232235535", "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/7417111702443232235535" } }, "status": "VOIDED" } ``` Void for a Capture or Credit {#payments-processing-basic-void-intro} ==================================================================== This section describes how to void a capture or credit that was submitted but not yet processed by the processor. Endpoints {#payments-processing-basic-void-intro_d8e268} -------------------------------------------------------- **Void a Capture** **Production:** `POST ``https://api.cybersource.com``/pts/v2/captures/`*{id}*`/voids`{#payments-processing-basic-void-intro_d8e281} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/captures/`*{id}*`/voids`{#payments-processing-basic-void-intro_d8e294} **Void a Credit** **Production:** `POST ``https://api.cybersource.com``/pts/v2/credits/`*{id}*`/voids`{#payments-processing-basic-void-intro_d8e311} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/credits/`*{id}*`/voids`{#payments-processing-basic-void-intro_d8e325} The *{id}* is the transaction ID returned during the credit response. Required Fields for Voiding a Capture or Credit {#payments-processing-basic-void-required-fields} ================================================================================================= [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : Including this field is recommended, but not required. REST Example: Voiding a Capture or Credit {#payments-processing-basic-void-ex-rest} =================================================================================== Request ``` { "clientReferenceInformation": { "code": "test123" } } ``` Response to a Successful Request ``` { "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/6541933390746728203005" } }, "clientReferenceInformation": { "code": "1654193339056" }, "id": "6541933390746728203005", "orderInformation": { "amountDetails": { "currency": "USD" } }, "status": "VOIDED", "submitTimeUtc": "2022-06-02T18:08:59Z", "voidAmountDetails": { "currency": "usd", "voidAmount": "100.00" } } ``` Pre-Authorizations {#payments-final-auth-indicator-preauth} =========================================================== A pre-authorization enables you to authorize a payment when the final amount is unknown. The system places the funds on hold until you request a follow-up transaction. Pre-authorizations are typically used for lodging, auto rental, e-commerce, and restaurant transactions. IMPORTANT Payment Services Directive 2 (PSD2) rules in the European Union (EU) and European Economic Area (EEA) require the initial pre-authorization to use strong customer authentication for merchants or customers in PSD2-applicable countries. When you have a specific merchant category code (MCC) assigned to your account, you are allowed to capture up to 20% more than the cumulatively authorized amount on Visa, Diners Club, Discover, and JCB cards. Contact your account manager to have your account enabled for this option. For a pre-authorization: * The authorization amount is greater than zero. * Submit the authorization for capture within 30 calendar days of its request. * After 30 calendar days, the customer bank (issuer) releases the hold on the authorized amount. * Send a new authorization request to claim the amount.