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 `Visa Acceptance Solutions` 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. Pilot Release {#payments-pilot-release} ======================================= This document provides information about the pilot release of the Payments REST API for `Fiserv RapidConnect`. Recent Revisions to This Document {#payments-doc-revisions} =========================================================== 25.09.01 -------- Added support for Mastercard. See [Card Types](/docs/vas/en-us/payments/developer/fiservrc/rest/payments/payments-intro/payments-intro-cards-types.md ""). 25.04.01 -------- `Fiserv RapidConnect` pilot release. Introduction to Payments {#payments-intro} ========================================== This introduction provides the basic information that you will need to successfully process payment transactions. It also provides an overview of the payments industry and provides workflows for each process. 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. Merchant Financial Institutions (Acquirers) {#payments-intro-banks-acquiring} ============================================================================= A merchant financial institution, also known as an *acquirer*, offers accounts to businesses that accept payment cards. 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, card-present, or mail-order/telephone-order (MOTO) transactions. If excessive chargebacks or fraudulant 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. Your payment processor assigns one or more merchant IDs (MIDs) to your business. These unique codes identify your business during payment transactions. This table lists the processors and corresponding card types that are supported for payment services. IMPORTANT Only the card types explicitly listed here are supported. | Payment Processor | Supported Card Types | Notes | |-----------------------|----------------------|-------| | `Fiserv RapidConnect` | Mastercard, Visa | | [Payment Processor and Supported Card Types] {#payments-intro-processors_supported-cards} Card Types {#payments-intro-cards-types} ======================================== You can process payments with these kinds of cards: * Credit cards * Debit cards You can process payments on the `Fiserv RapidConnect` processor with these card types: * Mastercard * Visa Transaction Types {#payments-intro-transactions-overview} ========================================================= This topic provides information about transaction types that are supported by your processor, such as card-present, card-not-present, and international transactions. 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 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. 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. Dual-Message Processing {#payments-intro-processing-sales-dual} =============================================================== Dual-message processing is a two-step process. The authorization is processed first. If the authorization is successful, the capture is processed immediately afterward. The response includes the authorization and the capture information. If the authorization is declined, the capture is not processed, and the response message includes only the authorization information. Partial Authorizations {#payments-intro-processing-sales-dual-partialauth} ========================================================================== All debit and prepaid card processors as well as a limited number of credit card processors support partial authorizations when dual-message processing is in place. When partial authorization is enabled, the issuing financial institution can approve a partial amount when the balance on the card is less than the requested amount. When a partial amount is authorized, the capture is not processed. The merchant can then use a second card to cover the balance, adjust the total cost, or void the transaction. Single-Message Processing {#payments-intro-processing-sales-single} =================================================================== Single-message processing treats the authorization and capture as a single transaction. There are important differences between dual-message processing and single-message processing: * Single-message processing treats the request as a full-financial transaction, and with a successful transaction, funds are immediately transferred from the customer account to the merchant account. * Authorization and capture amounts must be the same. * Some features cannot be used with single-message processing. Credits {#payments-intro-processing-credit} =========================================== Credits 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 credit 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. WARNING You should carefully control access to the credit service. 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. There are two basic types of credits: refunds and stand-alone credits. Refunds ------- Refunds, also known as *follow-on credits*, use the capture request ID to link the refund to a specific transaction. The request ID links the transaction to the customer's billing and account information, so you are not required to include those fields in the credit request. Unless otherwise specified, refunds must be requested within 180 days of a settlement. You can request multiple refunds against a single capture or sale transaction as long as the total amount does not exceed the original purchase amount. To perform multiple refunds, use the same request ID in each request. Stand-Alone Credits ------------------- Stand-alone credits are not connected to an original transaction. Stand-alone credits do not have a time restriction, and they can be used to issue refunds more than 180 days after a transaction settlement. Credit Workflow {#payments-intro-processing-credit-workflow} ============================================================ The credit workflow begins when you send a request for a credit. 1. The merchant sends a request for a credit to `Visa Acceptance Solutions`. 2. For online credits, `Visa Acceptance Solutions` validates the order information then sends an online credit 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. Voids {#payments-intro-processing-void} ======================================= A void cancels a capture or credit request that was submitted but not yet processed by the processor. Capture and credit requests are usually submitted once a day. 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, 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 ` Visa Acceptance Solutions ` 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, ` Visa Acceptance Solutions ` 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 ` Visa Acceptance Solutions ` 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.visaacceptance.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 the card numbers, 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} * UATP---1354 1234 5678 911 * Visa---4111 1111 1111 1111 Standard Payment Processing {#payments-processing-basic-intro} ============================================================== This section shows you how to process various authorization, capture, credit, and sales transactions. Zero Amount Authorizations {#payments-processing-basic-zero-auth-intro} ======================================================================= This section provides the information that you need in order to process a zero amount authorization. Authorizing a payment for a zero amount shows whether a payment card account is valid and whether the card is lost or stolen. You cannot capture a zero amount authorization. Endpoint {#payments-processing-basic-zero-auth-intro_d7e16} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-zero-auth-intro_d7e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-zero-auth-intro_d7e35} Required Fields for Processing a Zero Amount Authorization {#payments-processing-basic-zero-auth-required} ========================================================================================================== Use these required fields for processing a zero amount authorization. clientReferenceInformation.code : clientReferenceInformation.reconciliationId : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : Set this value to `0`. orderInformation.billTo.address1 : orderInformation.billTo.address2 : orderInformation.billTo.administrativeArea : orderInformation.billTo.country : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : orderInformation.billTo.locality : orderInformation.billTo.phoneNumber : orderInformation.billTo.postalCode : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : paymentInformation.card.securityCode : processingInformation.actionList : Set the value to `TOKEN_CREATE`. processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `paymnentInstrument` * `shippingAddress` REST Example: Processing a Zero Amount Authorization {#payments-processing-basic-zero-auth-ex-rest-fiservrc} ============================================================================================================ Request ```keyword { "clientReferenceInformation": { "code": "1234567890", "reconcilationId": "000000050000752" }, "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer", "paymentInstrument", "shippingAddress" ] }, "orderInformation": { "billTo": { "country": "US", "firstName": "John", "lastName": "Smith", "phoneNumber": "650-965-6111", "address2": "Room 2-2123", "address1": "600 Morgan Falls Road", "postalCode": "94566", "locality": "Atlanta", "administrativeArea": "MI", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "0", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2030", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } } } ``` Response to a Successful Request ``` { "embeddedActions": { "TOKEN_CREATE": { "status": "SUCCESS" } }, "paymentInformation": { "bin": "411111", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "Visa Classic", "cardBrand": "VISA", "cardType": "001" }, "submitTimeUtc": "2025-03-10T18:38:09Z", "processorInformation": { "approvalCode": "OK1272", "responseCodeSource": "4", "networkTransactionId": "0014239537635196CN", "responseCode": "000" }, "_links": { "capture": { "href": "/pts/v2/payments/7416318895663232235535/captures", "method": "POST" }, "reversal": { "href": "/pts/v2/payments/7416318895663232235535/reversals", "method": "POST" }, "self": { "method": "GET", "href": "/pts/v2/payments/7416318895663232235535" } }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500016", "merchantNumber": "RCTST1000107085" }, "orderInformation": { "amountDetails": { "authorizedAmount": "0000000000.00" } }, "message": "Successful transaction.", "clientReferenceInformation": { "code": "001234567890" }, "reconciliationId": "000000050000752", "pointOfSaleInformation": { "terminalId": "00000001" }, "id": "7416318895663232235535", "status": "AUTHORIZED", "tokenInformation": { "instrumentIdentifierNew": false, "customer": { "id": "300220A7824EF32AE0634136CF0A7425" }, "instrumentIdentifier": { "id": "7018759999957811111", "state": "ACTIVE" }, "paymentInstrument": { "id": "300220A78257F32AE0634136CF0A7425" }, "shippingAddress": { "id": "300220A7825AF32AE0634136CF0A7425" } } } ``` 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. Endpoint {#payments-processing-basic-sale-intro_d7e240} ------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-sale-intro_d7e248} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-sale-intro_d7e258} Required Fields for Processing a Sale {#payments-processing-basic-sale-reqfields} ================================================================================= clientReferenceInformation.code : clientReferenceInformation.reconciliationId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : orderInformation.billTo.address1 : orderInformation.billTo.administrativeArea : orderInformation.billTo.country : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : orderInformation.billTo.locality : orderInformation.billTo.phoneNumber : orderInformation.billTo.postalCode : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : processingInformation.capture : Set the value to `true`. {#payments-processing-basic-sale-reqfields_dl_cw5_zzq_nfc} REST Example: Sale with an Instrument Identifier Token {#payments-processing-basic-sale-ex-rest-fiservrc} ========================================================================================================= Request ```keyword { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000773" }, "processingInformation": { "commerceIndicator": "internet", "capture": true }, "orderInformation": { "billTo": { "country": "US", "firstName": "John", "lastName": "Smith", "phoneNumber": "650-965-6111", "address1": "600 Morgan Falls Road", "postalCode": "94566-1234", "locality": "Atlanta", "administrativeArea": "MI", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "110", "currency": "USD" } }, "merchantInformation": { "merchantDescriptor": { "name": "Best Bakery" } }, "paymentInformation": { "tokenizedCard": { "expirationYear": "2030", "expirationMonth": "02" }, "instrumentIdentifier": { "id": "7018759999957811111" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "411111", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "Visa Classic", "cardBrand": "VISA", "cardType": "001", "instrumentIdentifier": { "id": "7018759999957811111", "state": "ACTIVE" } }, "submitTimeUtc": "2025-03-12T16:27:31Z", "_links": { "refund": { "href": "/pts/v2/payments/7417968511323232235535/refunds", "method": "POST" }, "void": { "href": "/pts/v2/payments/7417968511323232235535/voids", "method": "POST" }, "self": { "method": "GET", "href": "/pts/v2/payments/7417968511323232235535" } }, "processorInformation": { "approvalCode": "OK1272", "consumerAuthenticationResponse": { "code": "1", "codeRaw": "1" }, "responseCodeSource": "4", "networkTransactionId": "0014239537635196CN", "responseCode": "000" }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500040", "merchantNumber": "RCTST1000107085" }, "clientReferenceInformation": { "code": "123456789012" }, "pointOfSaleInformation": { "terminalId": "00000001" }, "id": "7417968511323232235535", "orderInformation": { "amountDetails": { "authorizedAmount": "110.00" } }, "message": "Successful transaction.", "reconciliationId": "000000050000773", "status": "COMPLETED", "tokenInformation": { "instrumentIdentifierNew": false, "instrumentIdentifier": { "id": "7018759999957811111", "state": "ACTIVE" } }, "embeddedActions": { "TOKEN_RETRIEVE": { "status": "SUCCESS" } } } ``` Refunds {#payments-processing-basic-refund-intro} ================================================= This section provides the information you need in order to process a refund, which is linked to a sale. Endpoint {#payments-processing-basic-refund-intro_d7e199} --------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/refunds`{#payments-processing-basic-refund-intro_d7e207} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/refunds`{#payments-processing-basic-refund-intro_d7e220} 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} =========================================================================================== Use these required fields for processing a refund. clientReferenceInformation.code : clientReferenceInformation.reconciliationId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Processing a Refund {#payments-processing-basic-refund-ex-rest-fiservrc} ====================================================================================== Request ``` { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000769" }, "orderInformation": { "amountDetails": { "totalAmount": "110", "currency": "USD" } } } ``` Response to a Successful Request ``` { "submitTimeUtc": "2025-03-11T16:38:53Z", "processorInformation": { "approvalCode": "OK9473", "responseCodeSource": "4", "networkTransactionId": "0014239537635196CN", "responseCode": "000" }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500033", "merchantNumber": "RCTST1000107085" }, "orderInformation": { "amountDetails": { "authorizedAmount": "110.00" } }, "message": "Successful transaction.", "_links": { "void": { "href": "/pts/v2/refunds/7417111335293232235535/voids", "method": "POST" }, "self": { "method": "GET", "href": "/pts/v2/refunds/7417111335293232235535" } }, "clientReferenceInformation": { "code": "123456789012" }, "issuerInformation": { "responseCode": "123" }, "reconciliationId": "000000050000769", "pointOfSaleInformation": { "terminalId": "00000001" }, "id": "7417111335293232235535", "status": "COMPLETED" } ``` Credits {#payments-processing-basic-credit-intro} ================================================= This section shows you how to process a credit, which is not linked to a capture or sale. There is no time limit for requesting a credit. Endpoint {#payments-processing-basic-credit-intro_d7e169} --------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits/`{#payments-processing-basic-credit-intro_d7e178} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits/`{#payments-processing-basic-credit-intro_d7e188} Required Fields for Processing a Credit {#payments-processing-basic-credit-required-fields} =========================================================================================== Use these required fields for processing a credit. clientReferenceInformation.code : clientReferenceInformation.reconciliationId : merchantInformation.merchantDescriptor.name : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : orderInformation.billTo.address1 : orderInformation.billTo.administrativeArea : orderInformation.billTo.country : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : orderInformation.billTo.locality : orderInformation.billTo.postalCode : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : paymentInformation.instrumentIdentifier.id : processingInformation.commerceIndicator : Set the value to `internet`. {#payments-processing-basic-credit-required-fields_dl_dbd_ty2_r2c} REST Example: Processing a Credit {#payments-processing-basic-credit-ex-rest} ============================================================================= 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@vas.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "eur" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/6663069906146706403954/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/6663069906146706403954" } }, "clientReferenceInformation": { "code": "1666306990717" }, "creditAmountDetails": { "currency": "eur", "creditAmount": "100.00" }, "id": "6663069906146706403954", "orderInformation": { "amountDetails": { "currency": "eur" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "016153570198200", "responseCode": "100" }, "reconciliationId": "66490108K9CLFJPN", "status": "PENDING", "submitTimeUtc": "2022-10-20T23:03:10Z" } ``` REST Example: Processing a Credit {#payments-processing-basic-credit-ex-rest-fiservrc} ====================================================================================== Request ```keyword { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000765" }, "processingInformation": { "commerceIndicator": "internet" }, "orderInformation": { "billTo": { "country": "US", "firstName": "John", "lastName": "Smith", "phoneNumber": "650-965-6111", "address1": "600 Morgan Falls Road", "postalCode": "94566-1234", "locality": "Atlanta", "administrativeArea": "MI", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "110", "currency": "USD" } }, "merchantInformation": { "merchantDescriptor": { "name": "Best Bakery" } }, "paymentInformation": { "card": { "expirationYear": "2030", "expirationMonth": "02" }, "instrumentIdentifier": { "id": "7018759999957811111" } } } ``` Response to a Successful Request ``` { "submitTimeUtc": "2025-03-10T22:18:45Z", "_links": { "refund": { "href": "/pts/v2/payments/7416451254443232235535/refunds", "method": "POST" }, "void": { "href": "/pts/v2/payments/7416451254443232235535/voids", "method": "POST" }, "self": { "method": "GET", "href": "/pts/v2/payments/7416451254443232235535" } }, "processorInformation": { "approvalCode": "OK9473", "responseCodeSource": "4", "networkTransactionId": "0014239537635196CN", "responseCode": "000" }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500028", "merchantNumber": "RCTST1000107085" }, "orderInformation": { "amountDetails": { "authorizedAmount": "110.00" } }, "message": "Successful transaction.", "clientReferenceInformation": { "code": "123456789012" }, "issuerInformation": { "responseCode": "123" }, "reconciliationId": "000000050000765", "pointOfSaleInformation": { "terminalId": "00000001" }, "id": "7416451254443232235535", "status": "COMPLETED", "embeddedActions": { "TOKEN_RETRIEVE": { "status": "SUCCESS" } } } ``` Voids 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_d7e268} -------------------------------------------------------- **Void a Capture** **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/captures/`*{id}*`/voids`{#payments-processing-basic-void-intro_d7e281} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/captures/`*{id}*`/voids`{#payments-processing-basic-void-intro_d7e294} **Void a Credit** **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits/`*{id}*`/voids`{#payments-processing-basic-void-intro_d7e311} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits/`*{id}*`/voids`{#payments-processing-basic-void-intro_d7e325} The *{id}* is the transaction ID returned during the capture or credit response. Required Fields for Voiding a Capture or Credit {#payments-processing-basic-void-required-fields} ================================================================================================= clientReferenceInformation.code clientReferenceInformation.reconciliationId : REST Example: Voiding a Capture or Credit {#payments-processing-basic-void-ex-rest-fiservrc} ============================================================================================ Request ``` { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000771" }, "orderInformation": { "amountDetails": { "totalAmount": "110", "currency": "USD" } } } ``` 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 Sale {#payments-processing-sale-void-intro} ====================================================== This section describes how to void a sale that was submitted but not yet processed by the processor. Endpoint {#payments-processing-sale-void-intro_d7e429} ------------------------------------------------------ **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/voids`{#payments-processing-sale-void-intro_d7e438} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/voids`{#payments-processing-sale-void-intro_d7e451} The *{id}* is the transaction ID returned in the sale response. Required Fields for Voiding a Sale {#payments-processing-sale-void-required-fields} =================================================================================== clientReferenceInformation.code : clientReferenceInformation.reconciliationId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Voiding a Sale {#payments-processing-sale-void-ex-rest} ===================================================================== Request ``` { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000771" }, "orderInformation": { "amountDetails": { "totalAmount": "110", "currency": "USD" } } } ``` 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" } ``` Voids for a Refund {#payments-processing-refund-void-intro} =========================================================== This section describes how to void a sale that was submitted but not yet processed by the processor. Endpoint {#payments-processing-refund-void-intro_d7e472} -------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/refund/`*{id}*`/voids`{#payments-processing-refund-void-intro_d7e481} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/refund/`*{id}*`/voids`{#payments-processing-refund-void-intro_d7e494} The *{id}* is the transaction ID returned in the refund response. Required Fields for Voiding a Refund {#payments-processing-refund-void-required-fields} ======================================================================================= clientReferenceInformation.code : clientReferenceInformation.reconciliationId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Voiding a Refund {#payments-processing-refund-void-ex-rest} ========================================================================= Request ``` { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000772" }, "orderInformation": { "amountDetails": { "totalAmount": "100", "currency": "USD" } } } ``` Response to a Successful Request ``` { "submitTimeUtc": "2025-03-11T16:57:19Z", "processorInformation": { "approvalCode": "OK1272", "responseCode": "000" }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500039" }, "orderInformation": { "amountDetails": { "authorizedAmount": "110.00" } }, "message": "Successful transaction.", "clientReferenceInformation": { "code": "123456789012" }, "reconciliationId": "000000050000772", "id": "7417122396283232235535", "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/7417122396283232235535" } }, "status": "VOIDED" } ``` Time-Out Voids for a Capture, Sale, Refund, or Credit {#payments-timeout-void-intro} ==================================================================================== When you do not receive a response message after requesting a capture, sale, refund, or credit, this feature enables you to void the transaction that you requested. Include the clientReferenceInformation.transactionId field in the original request for a capture, sale, refund, or credit. The value of the merchant transaction ID must be unique for 180 days. When the original transaction fails, the response message for the reversal request includes these fields: * voidAmountDetails.originalTransactionAmount * processorInformation.responseCode Endpoint {#payments-timeout-void-intro_d7e585} ---------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/voids/`{#payments-timeout-void-intro_d7e594} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/voids/`{#payments-timeout-void-intro_d7e604} Required Fields for a Time-Out Void for a Capture, Sale, Refund, or Credit {#payments-timeout-void-required-fields} =================================================================================================================== clientReferenceInformation.code : clientReferenceInformation.reconciliationId : clientReferenceInformation.transactionId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Time-Out Void for a Capture, Sale, Refund, or Credit {#payments-timeout-void-ex-rest-fiservrc} ============================================================================================================ Request ``` { "clientReferenceInformation": { "code": "123456789012", "reconciliationId": "000000050000772" "transactionId": "987654321" }, "orderInformation": { "amountDetails": { "totalAmount": "100", "currency": "USD" } } } ``` Response to a Successful Request ``` { "submitTimeUtc": "2025-03-11T16:57:19Z", "processorInformation": { "approvalCode": "OK1272", "responseCode": "000" }, "consumerAuthenticationResponse": { "systemTraceAuditNumber": "500039" }, "orderInformation": { "amountDetails": { "authorizedAmount": "110.00" } }, "message": "Successful transaction.", "clientReferenceInformation": { "code": "123456789012" }, "reconciliationId": "000000050000772", "id": "7417122396283232235535", "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/7417122396283232235535" } }, "status": "VOIDED" } ``` Payer Authentication Processing {#payments-processing-pa-process-intro} ======================================================================= This section shows you how to process authorizations that use these payer authentication methods: {#payments-processing-pa-process-intro_ul_dqz_xll_5xb} Visa Secure {#payments-processing-pa-visa-intro} ================================================ Visa Secure is the authentication service in the Visa card network that uses the 3-D Secure protocol to authenticate customers at checkout. This authentication is a two-step process. First, the cardholder is authenticated by 3-D Secure. Then, the transaction is authorized based on the 3-D Secure evaluation. This section explains how to authorize a card payment based on the 3-D Secure evaluation. Before implementing Visa Secure, contact customer support to have your account configured for this feature. Fields Specific to the Visa Secure Use Case ------------------------------------------- These API fields are required specifically for this use case. processingInformation.commerceIndicator : Set the value to `vbv` for a successful authentication (3-D Secure value of `05`), `vbv_attempted` if authentication was attempted but did not succeed (3-D Secure value of `06`), or `vbv_failure` if authentication failed (3-D Secure value of `07`). consumerAuthenticationInformation.cavv : Required when payer authentication is successful. Endpoint {#payments-processing-pa-visa-intro_d7e16} --------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-processing-pa-visa-intro_d7e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-processing-pa-visa-intro_d7e35} Required Fields for Processing an Authorization Using Visa Secure {#payments-processing-pa-visa-reqfields} ========================================================================================================== Use these required fields to process an authorization using Visa Secure. > IMPORTANT When relaxed requirements for address data and the expiration date are being used, not all fields in this list are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. Refer to the Payments guide for more information about relaxed requirements in payment transactions. Required Fields --------------- [clientReferenceInformation.code](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.cavv](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : This field is required when payer authentication is successful. Otherwise, this field is optional. [consumerAuthenticationInformation.xid](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-xid.md "") : [orderInformation.amountDetails.currency](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : `Vero` supports Brazilian real (BRL) currency only. [orderInformation.amountDetails.totalAmount](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.administrativeArea](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-admin-area.md "") : [orderInformation.billTo.country](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-country.md "") : [orderInformation.billTo.email](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.locality](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-locality.md "") : [orderInformation.billTo.postalCode](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.commerceIndicator](https://developer.visaacceptance.com/docs/vas/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : Set this field to one of these values: * `vbv`: Successful authentication (EMV `3-D Secure` value of `05`). * `vbv_attempted`: Authentication was attempted (EMV `3-D Secure`value of `06`). * `vbv_failure`: or `internet`: Authentication failed or was not attempted (EMV `3-D Secure` value of `07`). {#payments-processing-pa-visa-reqfields_ul_ztw_km1_jxb} REST Example: Validating and Authorizing a Transaction {#payments-processing-pa-visa-ex-rest} ============================================================================================= Request ``` { "clientReferenceInformation": { "code": "test" }, "processingInformation": { "capture": "true", "authorizationOptions": { "ignoreAvsResult": "true" }, "actionList": [ "VALIDATE_CONSUMER_AUTHENTICATION" ] }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4XXXXXXXXXXX25X3", "securityCode": "123", "expirationMonth": "12", "type": "001" } }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "GBP" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "201 S. Division St._1", "address2": "Suite 500", "locality": "Foster City", "administrativeArea": "CA", "postalCode": "94404", "country": "US", "email": "accept@cybersource.com", "phoneNumber": "6504327113" } }, "consumerAuthenticationInformation": { "authenticationTransactionId": "2b4eAa4K3H778X34Ciy0" } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/payments/7478305945626990404807/voids" }, "self": { "method": "GET", "href": "/pts/v2/payments/7478305945626990404807" } }, "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "indicator": "vbv", "eciRaw": "05", "authenticationResult": "0", "strongAuthentication": { "OutageExemptionIndicator": "0" }, "authenticationStatusMsg": "Success", "eci": "05", "token": "Axj//wSTlWZX08jkcOTHAAIU3YMmzhgzcN2ie/LXsgSgKe/LXsgS50OnEFBWGTSTL0Yua1eAwHScqzK+nkcjhyY4wDi0", "cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=", "paresStatus": "Y", "xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=", "directoryServerTransactionId": "fa628ed8-ad77-4723-b28f-91952eaca8fe", "threeDSServerTransactionId": "71399671-8456-4c97-b056-e127622a5e26", "specificationVersion": "2.2.0", "acsTransactionId": "5f9fb589-08cc-4952-866d-30939868f411" }, "id": "7478305945626990404807", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "authorizedAmount": "100.00", "currency": "GBP" } }, "paymentAccountInformation": { "card": { "brandName": "VISA", "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "bin": "400000", "type": "VISA" } }, "pointOfSaleInformation": { "terminalId": "12345678" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013018036776997406844475", "merchantNumber": "12345678", "approvalCode": "100", "cardVerification": { "resultCodeRaw": "3", "resultCode": "2" }, "merchantAdvice": { "code": "00", "codeRaw": "0" }, "networkTransactionId": "123456789012345", "transactionId": "123456789012345", "responseCode": "0", "avs": { "code": "U", "codeRaw": "00" } }, "reconciliationId": "7026803874", "status": "AUTHORIZED", "submitTimeUtc": "2025-05-21T12:29:54Z" } ```