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 credit 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. Recent Revisions to This Document {#payment-doc-revisions} ========================================================== 25.01 ----- Added a testing section. See [Testing the Payment Services](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-intro/payments-testing-services.md ""). Credentialed Transactions : Removed Mastercard required field for retrieving customer credentials during a CIT request. See [Card-Specific Required Field for Retrieving Customer Credentials During a CIT](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-cit-intro/credentials-cit-using-intro/credentials-cit-using-required/credentials-install-mit-card-type.md ""). 24.14 ----- This revision contains only editorial changes and no technical updates. 24.13 ----- This revision contains only editorial changes and no technical updates. 24.12 ----- This revision contains only editorial changes and no technical updates. 24.11 ----- This revision contains only editorial changes and no technical updates. 24.10 ----- This revision contains only editorial changes and no technical updates. 24.09 ----- This revision contains only editorial changes and no technical updates. 24.08 ----- This revision contains only editorial changes and no technical updates. 24.07 ----- Pre-Authorizations : Added pre-authorization processing. See [Pre-Authorizations](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-processing-basic-intro/payments-processing-pre-auth-intro.md ""). 24.06 ----- Credit Authorizations on Refunds : Added credit authorization information to [Refunds](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-processing-basic-intro/payments-processing-basic-refund-intro.md ""). Credit Authorizations on Credits : Added credit authorization information to [Credits](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-processing-basic-intro/payments-processing-basic-credit-intro.md ""). Multiple Partial Captures : Updated how to set the processingInformation.captureOptions.totalCaptureCount field. See [Multiple Partial Captures](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-processing-basic-intro/payments-processing-capture-multi-intro.md ""). 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. With `Visa Acceptance Solutions` 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. `Visa Acceptance Solutions` supports a large number of payment cards and offers a wide choice of gateways and financial institutions, all through one connection. Financial Institutions and Payment Networks {#cc-banks-overview} ================================================================ Financial institutions and payment networks enable payment services. These entities work together to complete the full payment cycle. Merchant Financial Institutions (Acquirers) {#cc-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) {#cc-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 {#cc-cards-card-companies} =========================================== Payment networks manage communications between acquiring financial institutions and issuing financial institutions. They also develop industry standards, support their brands, and establish fees for acquiring institutions. Some payment networks, such as Visa, Mastercard, and UnionPay International, are trade associations that do not issue cards. Issuers are members of these associations, and they issue cards under license from the association. Other networks, such as Discover and American Express, issue their own cards. Before you process cards from these companies, you must sign agreements with them. 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 | |---------------------------|----------------------|-------| | `American Express Direct` | American Express | | [Payment Processors and Supported Card Types] Card Types {#cc-cards-types-and-payment-methods} ================================================ You can process payments with these kinds of cards: * Credit cards * Debit cards 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 checking account. A merchant who accepts the debit card can deduct funds directly from the account. Transaction Types {#cc-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 {#cc-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. Authorizations with Card Verification Numbers {#payment-auth-cvn-intro} ======================================================================= Card verification numbers (CVNs) are a required feature for the authorization service. The CVN is printed on a payment card, and only the cardholder can access it. The CVN is used in card-not-present transactions as a verification feature. Using the CVN helps reduce the risk of fraud. CVNs are not included in payment card track data and cannot be obtained from a card swipe, tap, or dip. CVNs must not be stored after authorization. > IMPORTANT In Europe, Visa mandates that you not include a CVN for mail-order transactions and not record a CVN on any physical format such as a mail-order form. Endpoint {#payment-auth-cvn-intro_d19e16} ----------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payment-auth-cvn-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payment-auth-cvn-intro_d19e35} CVN Locations and Terminology {#payment-auth-cvn-locations} =========================================================== For most cards, the CVN is a three-digit number printed on the back of the card, to the right of the signature field. For American Express, the CVN is a four-digit number printed on the front of the card above the card number. #### Figure: CVN Locations ![Image depicting the location of the CVN on the back of most cards and the front of an American Express card.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/card-processing/payments/images/CVV_Location.svg/jcr:content/renditions/original) Each payment card company has its own name for the CVN value: * American Express and Discover call it the *Card Identification Number* (CID). * JCB calls it the *Card Authentication Value* (CAV2). * Mastercard calls it the *Card Validation Code* (CVC2). * Visa calls it the *Card Verification Value* (CVV2). `Token Management Service` {#payments-intro-tms-overview} ========================================================= The `Token Management Service` (`TMS`) tokenizes, securely stores, and manages customer and payment data. `TMS` enables you to: * Securely store a customer's payment details and their billing and shipping addresses. * Create a network token of a customer's payment card. {#payments-intro-tms-overview_ul_4} `TMS` simplifies your PCI DSS compliance. `TMS` passes back to you tokens that represent this data. You then store these tokens in your environment and databases instead of customer payment details. **`TMS` Token Types** * Customer --- Stores the buyer's email address and the merchant's account ID for that buyer plus any other custom fields. * Shipping Address --- Stores a shipping address for a specific customer. * Instrument Identifier --- Stores either a payment card number or a bank account number and routing number This resource creates either: * An Instrument Identifier token using details of a payment card or an ACH bank account. * A payment network token using the details of a payment card; also uses the card expiration date and billing address, which are pass-through only fields. {#payments-intro-tms-overview_ul_5} * Payment Instrument --- Stores a Payment Instrument using an Instrument Identifier token. It does not store the card number and cannot exist without an associated Instrument Identifier. It stores: * Card expiration date * Billing address {#payments-intro-tms-overview_ul_2} You can also choose to store this information yourself instead and store only the card number or bank account and routing number in an Instrument Identifier object. * Customer Payment Instrument --- Creates and stores a payment instrument for a specific customer ID and an Instrument Identifier token. **`TMS` Features** * Create, retrieve, update, and delete tokens. * Set a default payment instrument and shipping address for a customer. * Process follow-on payment transactions with token IDs. * Create and update tokens through bundled payment transactions. > IMPORTANT > Due to mandates from the Reserve Bank of India, Indian merchants cannot store personal account numbers (PAN). Use network tokens instead. For more information on network tokens, see the Network Tokenization section of the [` Token Management Service ` Guide.](https://developer.visaacceptance.com/docs/vas/en-us/tms/developer/ctv/rest/tms/tms-overview.md "") Payment Services {#payment-services-intro} ========================================== This section describes various services for 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. Authorizations {#payment-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. Micropayment Authorizations {#payments-intro-processing-auth-micropayment} ========================================================================== Micropayments are payments for less than one unit in the transaction's currency. For `American Express Direct`, `Visa Acceptance Solutions` supports micropayment authorizations for American Express payment cards in the US. Online Authorizations {#payments-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. An 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 to 7 days. The issuing bank does not inform `Visa Acceptance Solutions` when an authorization confirmation expires. By default, the authorization information for each transaction remains in the `Visa Acceptance Solutions` database for 180 days after the authorization date. To capture an authorization that expired with the issuing bank, you can resubmit the authorization request. Offline Authorizations {#payment-processing-auth-offline} ========================================================= Online transactions require an internet connection. In situations where the internet is not available, for example, due to an outage, merchants can continue to take credit card payments using offline transactions. An offline authorization is an authorization request for which you do not receive an immediate confirmation about the availability of funds. Offline authorizations have a higher level of risk than online transactions because they do not confirm funds availability or set aside the funds for later capture. Further, it can take up to 5 days to receive payment confirmations for offline transactions. To mitigate this risk, merchants may choose to fulfill orders only after receiving payment confirmation. Incremental Authorizations {#payment-processing-auth-incremental} ================================================================= Incremental authorizations are useful when a customer adds products and services to a purchase. After a successful initial authorization, you can request subsequent authorizations and request one capture for the initial authorization and the incremental authorizations. The incremental authorization service is not the same as the incremental authorization scenario for a merchant-initiated transaction. Scenario for the Incremental Authorization Service {#payments-processing-basic-auth-inc-scenario} ================================================================================================= This sequence is an example of how incremental authorizations work: 1. The customer reserves a hotel room for two nights at a cost of 200.00 per night. You request an authorization for 400.00. The authorization request is approved. 2. The customer orders dinner through room service the first night. You request an incremental authorization of 50.00 for the dinner. 3. The customer decides to stay an extra night. You request an incremental authorization of 200.00 for the additional night. 4. The customer uses items from the mini-bar. The cost of the mini-bar items is 50.00. You request an incremental authorization of 50.00. 5. When the customer checks out, they sign a receipt for 700.00, which is the total of all costs incurred. 6. You request a capture for 700.00. Pre-Authorizations {#payments-intro-pre-auths} ============================================== A pre-authorization enables you to authorize a payment when the final amount is unknown. It is typically used for lodging, auto rental, e-commerce, and restaurant transactions. For a pre-authorization: * The authorization amount must be greater than zero. * The authorization must be submitted for capture within 30 calendar days of its request. * When you do not capture the authorization, you must reverse it. In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed. In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations. * Chargeback protection is in effect for 30 days after the authorization. Payment Network Token Authorizations {#payments-intro-processing-auth-pnt} ========================================================================== You can integrate authorizations with payment network tokens into your existing order management system. For an incremental authorization, you do not need to include any payment network tokenization fields in the authorization request because `Visa Acceptance Solutions` obtains the payment network tokenization information from the original authorization request. Authorization Workflow {#payments-intro-processing-auth-workflow} ================================================================= This image and description show the authorization workflow: ![](/content/dam/new-documentation/documentation/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 `Visa Acceptance Solutions`. 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. `Visa Acceptance Solutions` 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 and American Express, 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 `Visa Acceptance Solutions`. * If the issuing bank denies the request, it returns an authorization denial to `Visa Acceptance Solutions`. {#payments-intro-processing-auth-workflow_ul_smg_gg5_rbc} 6. `Visa Acceptance Solutions` runs its own tests then tells you whether the authorization succeeded. Sales {#payment-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 {#payment-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. Authorization Reversals {#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. If your processor supports authorization reversal after void (ARAV), you can reverse an authorization after you void the associated capture. If your processor does not support ARAV, you can use the authorization reversal service only for an authorization that has not been captured and settled. 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 `Visa Acceptance Solutions` 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 `Business Center`. > 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 ` Business Center `. Captures {#payment-processing-captures} ======================================= 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. Captures are typically not performed in real time. They are placed in a batch file and sent to the processor, and the processor settles all of the captures at one time. In most cases, these batch files are sent and processed outside of the merchant's business hours. It usually takes 2 to 4 days for the acquiring financial institution to deposit the funds into the merchant account. 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 ` Business Center `. Capture Workflow {#payment-processing-captures-workflow} ======================================================== The capture workflow begins when you send a request for a capture. 1. The merchant sends a request for a capture to `Visa Acceptance Solutions`. 2. For online captures, `Visa Acceptance Solutions` validates the order information then sends an online capture to the payment processor. For offline captures, `Visa Acceptance Solutions` stores the capture request in a batch file and sends the batch file to the payment processor after midnight. 3. The processor validates the request and forwards it to the issuing bank. 4. The issuing bank transfers funds to the acquiring bank. 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. This request ID is returned during the capture request (also known as a *settlement*) and is used in all subsequent refunds associated with the original capture. 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. However, when you combine a request for a refund with a request for another service, such as the tax calculation service, you must provide the customer's billing and account information. Unless otherwise specified, refunds must be requested within 180 days of a settlement. You can request multiple refunds against a single capture. To perform multiple refunds, use the same request ID in each request. Stand-Alone Credits ------------------- Stand-alone credits are not tied 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. A credit does not happen in real time. All of the credit requests for a day are typically placed in a file and sent to the processor as a single *batch* transaction. In most cases, the batch transaction is settled overnight. 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. For offline credits, `Visa Acceptance Solutions` stores the credit request in a batch file and sends the batch file to the payment processor after midnight. 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. Payment Features {#payments-features-intro} =========================================== You can apply features to different payment services to enhance the customer payment processing experience. This section includes an overview of these features: * [Debit and Prepaid Card Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-intro/payments-features-intro/payments-debit-prepaid-intro.md "") * [Payer Authentication](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-intro/payments-features-intro/payments-processing-pa-intro.md "") * [Processing Payments Using Credentials](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro.md "") * [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-intro/payments-features-intro/payments-relax-reqs-intro.md "") * [Token Management Service](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-intro/payments-features-intro/payment-tms-intro.md "") Debit and Prepaid Card Payments {#payments-debit-prepaid-intro} =============================================================== Debit cards are linked to a cardholder's checking account. A merchant who accepts the debit card can deduct funds directly from the linked cardholder's account. You can process debit cards using these services: * Credit card services * PIN debit services * Partial authorizations, which are a special feature available for debit cards * Balance inquiries, which are a special feature available for debit cards Related Information ------------------- * See [Standard Payment Processing](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-processing-basic-intro.md "") for information that shows you how to use credit card services. * See [Debit and Prepaid Card Processing](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-debit-prepaid-process-intro.md "") for information that shows you how to process authorizations that use a debit or prepaid card. Payer Authentication {#payment-processing-pa-intro} =================================================== Payer authentication is run before a transaction is submitted for authorization. Most of the time payer authentication is bundled with authorization so that after payer authentication happens, the transaction is automatically submitted for authorization. Payer authentication and authorization can be configured to occur as separate operations. This section shows you how to run payer authentication as a separate process and pass the payer authentication data when seeking authorization for a transaction. Payer authentication consists of a two-step verification process that adds an extra layer of fraud protection during the payment process. During transactions, the transaction device, location, past purchasing habits, and other factors are analyzed for indications of fraud. This process collects customer data during the transaction from at least two of these three categories: * **Something you have**: A payment card or a payment card number * **Something you know**: A password or pin * **Something you are**: Facial recognition or fingerprint Each of these payment card companies has its own payer authentication product: * **Discover**: ProtectBuy * **JCB**: J/Secure * **Mastercard**: Identity Check * **Visa**: Visa Secure Payer authentication can be used to satisfy the Strong Customer Authentication (SCA) requirement of the Payment Services Directive (PSD2). SCA applies to the European Economic Area (EEA) and the United Kingdom. SCA requires banks to perform additional checks when customers make payments to confirm their identity. Related Information {#payment-processing-pa-intro_section_rb2_vbs_5xb} ---------------------------------------------------------------------- * See [Payer Authentication Processing](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-processing-pa-process-intro.md "") for information about how to process payments with payer authentication. {#payment-processing-pa-intro_ul_r3s_vbs_5xb} Relaxed Requirements for Address Data and Expiration Date in Payment Transactions {#payments-relax-reqs-intro} ============================================================================================================== With relaxed requirements for address data and the expiration date, not all standard payment request fields are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. Related Information ------------------- * See [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md "") for information about how to process payments with relaxed requirements for address data and expiration date. Introduction to Credentialed Transactions {#credentials-intro} ============================================================== Credentialed transactions are transactions that involve either storing a customer's payment credentials for future transactions or using a customer's already stored payment credentials. When processing a credentialed transaction, you must indicate the type of credentialed transaction and the reason for the transaction. Credentialed transactions are also known as *credential-on-file* (COF) transactions. There are several types of credentialed transactions: * **Customer-Initiated Transactions (CITs):** Any transaction a customer is actively participating in such as making a card-present payment, completing an online checkout, or by using a stored credential. CIT transactions can store the customer's credentials in your system for future CITs or merchant-initiated transactions. * **Merchant-Initiated Transactions (MITs):** Any transaction a merchant initiates without the customer's participation such as an industry practice transaction or a standing instruction transaction. * **Industry Practice Transactions:** MITs that are performed as subsequent transactions to a CIT because the initial transaction could not be completed in one transaction. Not every industry practice transaction involves a stored credential. If a stored credential is used only for one transaction, that transaction is not considered a credentialed transaction. * **Standing Instruction Transactions:** MITs that are performed to follow agreed-upon instructions from the customer for the provision of goods and services. Supported Services ------------------ These are the supported merchant-initiated services: * Installment Transactions * Mastercard Standing Order Transactions * Mastercard Subscription Transactions * Recurring Transactions * Unscheduled Credentials-on-File Transactions The service determines the reason for the credentialed transaction. Token Management Service {#payment-tms-intro} ============================================= The `Token Management Service` (`TMS`) enables you to replace personally identifiable information (PII), such as the primary account numbers (PANs), with unique tokens. These tokens do not include the PII data, but act as a placeholder for the personal information that would otherwise need to be shared. By using tokens, businesses can provide a secure payment experience, reduce the risk of fraud, and comply with industry consumer security regulations such as PCI-DSS. `TMS` links tokens across service providers, payment types, and channels for sellers, acquirers, and technology partners. `TMS` tokenizes, securely stores, and manages the primary account number (PAN), the payment card expiration date, electronic check details, and customer data. `TMS` also enables you to create a network token of a customer's payment card. IMPORTANT Due to mandates from the Reserve Bank of India, Indian merchants cannot store PANs. Use network tokenization instead. You can manage sensitive data securely by creating, retrieving, updating, and deleting tokens through the [TMS API](https://developer.visaacceptance.com/api-reference-assets/index.md#token-management ""). `TMS` simplifies your PCI DSS compliance. `TMS` passes tokens back to you that represent this data. You then store these tokens in your environment and databases instead of storing customer payment details. `TMS` protects sensitive payment information through tokenization and secures and manages customer data using these token types: * Customer tokens * Instrument identifier tokens * Payment instrument tokens * Shipping address tokens These `TMS` tokens can be used individually, or they can be associated with one customer token: #### Figure: `TMS` Token Types ![Diagram of the unified token identifier.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/tms/images/token-types-intro.svg/jcr:content/renditions/original) Related Information {#payment-tms-intro_section_wvx_nhs_5xb} ------------------------------------------------------------ * See [Token Management Service Processing](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payment-tms-process-intro.md "") for information that shows you how to process payments using the `TMS`. {#payment-tms-intro_ul_lph_4hs_5xb} 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} ========================================================= > IMPORTANT Before you can test, you must 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 ""). If 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 will 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. * American Express---3782 8224 6310 005 * Discover---6011 1111 1111 1117 * JCB---3566 1111 1111 1113 * Maestro (International) * 5033 9619 8909 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 0000 0008 * 6759 5600 4500 5727 054 * 5641 8211 1116 6669 {#payments-testing-cards_ul_2} * Mastercard * 2222 4200 0000 1113 * 2222 6300 0000 1125 * 5555 5555 5555 4444 {#payments-testing-cards_ul_3} * UATP---1354 1234 5678 911 * 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 "") . Test American Express Card Verification {#payments-test-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 {#payment-processing-basic-intro} ============================================================= This section shows you how to process various authorization, capture, credit, and sales transactions. Additional Resources for Processing Payments {#cnp-basic-related} ================================================================= For more information, see these guides: * [API field reference guide for the REST API](https://developer.visaacceptance.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "") Basic Authorizations {#payments-processing-basic-auth-intro} ============================================================ This section provides the information you need in order to process a basic authorization. Endpoint {#payments-processing-basic-auth-intro_d19e16} ------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-auth-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-auth-intro_d19e35} Declined Authorizations {#payments-intro-processing-auth-decline} ================================================================= If an authorization is declined, you can use response categories to help you decide whether to retry or block a declined transaction. These response fields provide additional information: * paymentInsightsInformation.responseInsights.category * paymentInsightsInformation.responseInsights.categoryCode Category codes have possible values (such as `01`) each of which corresponds to a category that contains a description. You cannot retry this category code and category: * `01 ISSUER_WILL_NEVER_APPROVE` {#payments-intro-processing-auth-decline_ul_wxl_1yx_f5b}For these values, you can retry the transaction a maximum of 15 times over a period of 30 days: * `02 ISSUER_CANNOT_APPROVE_AT_THIS_TIME` * `03 ISSUER_CANNOT_APPROVE_WITH_THESE_DETAILS`: Data quality issue. Revalidate data prior to retrying the transaction. * `04 GENERIC_ERROR` * `97 PAYMENT_INSIGHTS_INTERNAL_ERROR` * `98 OTHERS` * `99 PAYMENT_INSIGHTS_RESPONSE_CATEGORY_MATCH_NOT_FOUND` {#payments-intro-processing-auth-decline_ul_zf4_4yx_f5b} Required Fields for Processing a Basic Authorization {#payments-processing-basic-auth-required} =============================================================================================== Use these required fields for processing a basic authorization. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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 : REST Interactive Example: Processing a Basic Authorization {#payments-processing-basic-auth-ex-live} ==================================================================================================== ``` Simple Authorization(Internet) ``` Live Console URL: [index.html#payments_payments_process-a-payment](https://developer.visaacceptance.com/api-reference-assets/index.md#payments_payments_process-a-payment "") REST Example: Processing a Basic Authorization {#payments-processing-basic-auth-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": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } } } ``` 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" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "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" } ``` Authorizations with Line Items {#payment-processing-basic-auth-lineitem-intro} ============================================================================== This section shows you how to process an authorization with line items. The main difference between a basic authorization and an authorization that includes line items is that the orderInformation.amountDetails.totalAmount field, which is included in a basic authorization, is substituted with one or more line items that are included in a lineItem\[\] array. Fields Specific to this Use Case -------------------------------- These fields are required for each line item that you use: orderInformation.lineItems\[\].unitPrice : orderInformation.lineItems\[\].quantity : orderInformation.lineItems\[\].productCode : orderInformation.lineItems\[\].productSku : Optional when item_#_productCode is set to `default`, `shipping_only`, `handling_only`, or `shipping_and_handling` orderInformation.lineItems\[\].productName : Optional when item_#_productCode is set to `default`, `shipping_only`, `handling_only`, or `shipping_and_handling` {#payment-processing-basic-auth-lineitem-intro_dl_ht4_hlx_rxb} At a minimum, you must include the orderInformation.lineItems\[\].unitPrice field in order to include a line item in an authorization. When this field is the only field included in the authorization, the system sets: * orderInformation.lineItems\[\].productCode: `default` * orderInformation.lineItems\[\].quantity: `1` For example, these three line items are valid. ``` "orderInformation": { "lineItems": [ { "unitPrice": "10.00" }, { "unitPrice": "5.99", "quantity": "3", "productCode": "shipping_only" }, { "unitPrice": "29.99", "quantity": "3", "productCode": "electronic_good", "productSku": "12384569", "productName": "receiver" } ] } ``` Endpoint {#payment-processing-basic-auth-lineitem-intro_d19e16} --------------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payment-processing-basic-auth-lineitem-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payment-processing-basic-auth-lineitem-intro_d19e35} Required Fields for Processing an Authorization with Line Items {#payments-processing-basic-auth-lineitem-required} =================================================================================================================== Use these required fields for processing an authorization that includes line items. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). orderInformation.amountDetails.currency 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 : REST Example: Processing an Authorization with Line Items {#payements-processing-basic-auth-lineitem-ex-rest} ============================================================================================================= Request ```keyword { "currencyConversion": { "indicator": "Y" }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "currency": "USD", "exchangeRate": ".91", "originalAmount": "107.33", "originalCurrency": "eur" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com" }, "lineItems": [ { "unitPrice": "10.00" }, { "unitPrice": "5.99", "quantity": "3", "productCode": "shipping_only" }, { "unitPrice": "29.99", "quantity": "3", "productCode": "electronic_good", "productSku": "12384569", "productName": "receiver" } ] } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6482385519226028804003/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6482385519226028804003" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6482385519226028804003/captures" } }, "clientReferenceInformation": { "code": "1648238551902" }, "id": "6482385519226028804003", "orderInformation": { "amountDetails": { "authorizedAmount": "117.94", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "systemTraceAuditNumber": "191521", "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": "6482385519226028804003", "status": "AUTHORIZED", "submitTimeUtc": "2022-03-25T20:02:32Z" } ``` Authorizations with Payment Network Tokens {#pnt-std-auth-intro} ================================================================ This section shows you how to successfully process an authorization with payment network tokens. > IMPORTANT > Due to mandates from the Reserve Bank of India, Indian merchants cannot store personal account numbers (PAN). Use network tokens instead. For more information on network tokens, see [Network Tokenization](https://developer.visaacceptance.com/docs/vas/en-us/tms/developer/ctv/rest/tms/tms-net-tkn-onboard.md "") in the *` Token Management Service ` Developer Guide*. Endpoint {#pnt-std-auth-intro_d60e16} ------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#pnt-std-auth-intro_d60e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#pnt-std-auth-intro_d60e35} Required Fields for Authorizations with Payment Network Tokens {#pnt-std-req-fields} ==================================================================================== Use these required fields for processing an authorization with payment network tokens. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : orderInformation.billTo.address1 : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : paymentinformation.tokenizedCard.cryptogram : paymentinformation.tokenizedCard.expirationMonth : paymentinformation.tokenizedCard.expirationYear : Optional Fields for Authorizations with Payment Network Tokens {#pnt-std-optional-fields} ========================================================================================= You can use these optional fields to include additional information when processing an authorization with a payment network token. clientReferenceInformation.code : consumerAuthenticationInformation.cavv : For 3-D Secure in-app transactions for Visa and JCB, set this field to the 3-D Secure cryptogram. Otherwise, set to the network token cryptogram. consumerAuthenticationInformation.ucafAuthenticationData : For Mastercard requests using 3-D Secure, set this field to the Identity Check cryptogram. consumerAuthenticationInformation.ucafCollectionIndicator : For Mastercard requests using 3-D Secure, set the value to `2`. orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : orderInformation.billTo.address1 : orderInformation.billTo.country : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : orderInformation.billTo.locality : orderInformation.billTo.postalCode : Required only for transactions in the US and Canada. orderInformation.billTo.administrativeArea : Required only for transactions in the US and Canada. processingInformation.commerceIndicator : paymentInformation.tokenizedCard.cardType : It is strongly recommended that you send the card type even if it is optional for your processor. Omitting the card type can cause the transaction to be processed with the wrong card type. paymentInformation.tokenizedCard.cryptogram : paymentInformation.tokenizedCard.expirationMonth : Set to the token expiration month that you received from the token service provider. paymentInformation.tokenizedCard.expirationYear : Set to the token expiration year that you received from the token service provider. paymentInformation.tokenizedCard.number : Set to the token value that you received from the token service provider. paymentInformation.tokenizedCard.requestorId paymentInformation.tokenizedCard.transactionType : REST Example: Authorizations with Payment Network Tokens {#pnt-ex-rest} ======================================================================= Request ``` { "orderInformation" : { "amountDetails" : { "totalAmount" : "100", "currency" : "USD" } }, "paymentInformation" : { "tokenizedCard" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12", "transactionType" : "1", "cryptogram" : "qE5juRwDzAUFBAkEHuWW9PiBkWv=" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6838294805206235603954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6838294805206235603954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6838294805206235603954/captures" } }, "clientReferenceInformation": { "code": "1683829480593" }, "id": "6838294805206235603954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "1" } }, "reconciliationId": "60332034UHI9PRJ0", "status": "AUTHORIZED", "submitTimeUtc": "2023-05-11T18:24:40Z" } ``` Authorizations with a Card Verification Number {#payments-auth-cvn-procedure} ============================================================================= This section shows you how to process an authorization with a Card Verification Number (CVN). CVN Results ----------- The response includes a raw response code and a mapped response code: * The raw response code is the value returned by the processor. This value is returned in the processorInformation.cardVerification.resultCodeRaw field. Use this value only for debugging purposes; do not use it to determine the card verification response. * The mapped response code is the pre-defined value that corresponds to the raw response code. This value is returned in the processorInformation.cardVerification.resultCode field. Even when the CVN does not match the expected value, the issuing bank might still authorize the transaction. You will receive a CVN decline, but you can still capture the transaction because it has been authorized by the bank. However, you must review the order to ensure that it is legitimate. Settling authorizations that fail the CVN check might have an impact on the fees charged by your bank. Contact your bank for details about how card verification management might affect your discount rate. When a CVN decline is received for the authorization in a sale request, the capture request is not processed unless you set the processingInformation.authorizationOptions.ignoreCvResult field to `true`. CVN Results for American Express : A value of `1` in the processorInformation.cardVerification.resultCode field indicates that your account is not configured to use card verification. Contact customer support to have your account enabled for this feature. CVN Results for Discover : CVN Results for Visa and Mastercard : A CVN code of `D` or `N` causes the request to be declined with a reason code value of `230`. You can still capture the transaction, but you must review the order to ensure that it is legitimate. `Visa Acceptance Solutions`, not the issuer, assigns the CVN decline to the authorization. You can capture any authorization that has a valid authorization code from the issuer, even when the request receives a CVN decline. When the issuer does not authorize the transaction and the CVN does not match, the request is declined because the card is refused. You cannot capture the transaction. Fields Specific to this Use Case {#payments-auth-cvn-procedure_section_ylk_2qx_rxb} ----------------------------------------------------------------------------------- Include this field with a standard authorization request when processing an authorization with a CVN: * paymentInformation.card.securityCode {#payments-auth-cvn-procedure_ul_zlk_2qx_rxb} Endpoint {#payments-auth-cvn-procedure_d19e16} ---------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-auth-cvn-procedure_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-auth-cvn-procedure_d19e35} Required Fields for Processing an Authorization with a Card Verification Number {#payments-auth-cvn-required} ============================================================================================================= Use these required fields for processing an authorization that includes a Card Verification Number (CVN). > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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.card.securityCode : paymentInformation.card.type : paymentInformation.card.securityCode : Optional Fields for Processing an Authorization with a Card Verification Number {#payments-auth-cvn-optional} ============================================================================================================= You can use these optional fields to include additional information when processing an authorization with a card verification number. paymentInformation.card.securityCodeIndicator : processingInformation.authorizationOptions.ignoreCvResult : REST Example: Processing an Authorization with a Card Verification Number {#payments-auth-cvn-ex-rest} ====================================================================================================== Request ``` { "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031", "type": "001", "securityCode": "999" } }, "orderInformation": { "amountDetails": { "totalAmount": "49.95", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1295 Charleston Rd.", "locality": "Mountain View", "administrativeArea": "CA", "postalCode": "94043", "country": "US", "email": "jdoe@example.com", "phoneNumber": "650-965-6000" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6554147587216874903954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6554147587216874903954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6554147587216874903954/captures" } }, "clientReferenceInformation": { "code": "1655414758839" }, "id": "6554147587216874903954", "orderInformation": { "amountDetails": { "authorizedAmount": "49.95", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67546603C43Z6JWN", "status": "AUTHORIZED", "submitTimeUtc": "2022-06-16T21:25:58Z" } ``` Zero Amount Authorizations {#payment-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. Processor-Specific Information ------------------------------ `American Express Direct` : AVS is supported. : Card type: American Express : All currencies that are supported for standard authorizations for `American Express Direct` are also supported for zero amount authorizations. Endpoint {#payment-processing-basic-zero-auth-intro_d19e16} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payment-processing-basic-zero-auth-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payment-processing-basic-zero-auth-intro_d19e35} Required Fields for Processing a Zero Amount Authorization {#payments-processing-basic-zero-auth-required} ========================================================================================================== Use these required fields for processing a zero amount authorization. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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 : REST Example: Processing a Zero Amount Authorizations {#payements-processing-basic-zero-auth-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" : "0.00", "currency" : "usd" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12" } } } ``` 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" : "0", "currency" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "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" } ``` Pre-Authorizations {#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. It is typically used for lodging, auto rental, e-commerce, and restaurant transactions. For a pre-authorization: * The authorization amount must be greater than zero. * The authorization must be submitted for capture within 30 calendar days of its request. * When you do not capture the authorization, you must reverse it. In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed. In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations. * Chargeback protection is in effect for 30 days after the authorization. Endpoint {#payments-processing-pre-auth-intro_d19e16} ----------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-processing-pre-auth-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-processing-pre-auth-intro_d19e35} Required Fields for a Pre-Authorization {#payments-processing-pre-auth-required} ================================================================================ Use these required fields for processing a pre-authorization. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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 : REST Example: Processing a Pre-Authorization {#payments-processing-pre-auth-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": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } } } ``` 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" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "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 Reversals {#payments-processing-basic-auth-reversal-intro} ======================================================================== This section provides the information you need in order to process an authorization reversal. Reversing an authorization releases the hold on the customer's payment card funds that the issuing bank placed when processing the authorization. Endpoint {#payments-processing-basic-auth-reversal-intro_d19e85} ---------------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/reversals`{#payments-processing-basic-auth-reversal-intro_d19e94} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/reversals`{#payments-processing-basic-auth-reversal-intro_d19e107} 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 : id : Set the `id` URL parameter to the transaction ID that was included in the authorization response message. orderInformation.amountDetails.currency : reversalInformation.amountDetails.totalAmount : 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" } "orderInformation" : { "amountDetails" : { "currency" : "USD" } }, "reversalInformation" : { "amountDetails" : { "totalAmount" : "100.00" } } } ``` 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" } ``` Sales {#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_d19e239} -------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-sale-intro_d19e247} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-processing-basic-sale-intro_d19e257} Required Fields for Processing a Sale {#payments-processing-basic-sale-reqfields} ================================================================================= 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 : processingInformation.capture : Set the value to `true`. REST Example: Processing a Sale {#payments-processing-basic-sale-ex-rest} ========================================================================= Request ```keyword { "processingInformation": { "capture": true }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "VDP", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "RTS", "email" : "test@vas.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "usd" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12", "type" : "001 } } } ``` 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" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "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" } ``` Captures {#payments-processing-basic-capture-intro} =================================================== This section provides the information you need in order to capture an authorized transaction. Endpoint {#payments-processing-basic-capture-intro_d19e127} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/captures`{#payments-processing-basic-capture-intro_d19e136} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/captures`{#payments-processing-basic-capture-intro_d19e149} The `{id}` is the transaction ID returned in the authorization response. Required Fields for Capturing an Authorization {#payments-processing-basic-capture-required-fields} =================================================================================================== Use these required fields for capturing an authorization. clientReferenceInformation.code : This field value maps from the original authorization, sale, or credit transaction. orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : 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" } ``` Multiple Partial Captures {#payments-processing-capture-multi-intro} ==================================================================== This section shows you how to process multiple partial captures for an authorization. This feature enables you to request multiple partial captures for one authorization. A multiple partial capture allows you to incrementally settle authorizations over time. Ensure that the total amount of all the captures does not exceed the authorized amount. Endpoint {#payments-processing-capture-multi-intro_d19e127} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/captures`{#payments-processing-capture-multi-intro_d19e136} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/captures`{#payments-processing-capture-multi-intro_d19e149} The `{id}` is the transaction ID returned in the authorization response. Required Fields for Processing Multiple Partial Captures {#payment-processing-capture-multiple-reqfields} ========================================================================================================= clientReferenceInformation.code : Set to clientReferenceInformation.code value used in corresponding authorization request. clientReferenceInformation.partner. thirdPartyCertificationNumber : `Visa Acceptance Solutions` provides the value for this field. orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Processing Multiple Partial Captures {#payments-processing-multi-capture-ex-rest} =============================================================================================== Request ``` { { "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "captureOptions": { "captureSequenceNumber": "2", "totalCaptureCount": "3" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6742496815656503003954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6742496815656503003954" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6742496815656503003954", "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } }, "reconciliationId": "67332020GD2G1OO1", "status": "PENDING", "submitTimeUtc": "2023-01-20T21:21:21Z" } ``` Forced Captures {#payments-forced-captures} =========================================== This feature allows merchants to process authorizations obtained through an organization other than `Visa Acceptance Solutions`. For example, a merchant might call their processor to request a manual authorization, at which point they can request a forced capture of the authorization. A manual authorization cannot be captured for more than the original authorization amount, and the authorization expires after seven days. Supported Services ------------------ * Authorization Required Fields for Forced Captures {#payments-forced-capture-required} ======================================================================= Use these required fields for processing forced captures. 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.type : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : processingInformation.authorizationOptions.authType : Set the value to `verbal`. processingInformation.authorizationOptions.verbalAuthCode : Set this field to the manually obtained authorization code. REST Example: Forced Captures {#payments-forced-captur4e-ex-rest} ================================================================= Request ```keyword { "orderInformation": { "billTo" : { "firstName" : "RTS", "lastName" : "VDP", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "country" : "US", "email" : "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } }, "processingInformation": { "authorizationOptions": { "authType": "verbal", "verbalAuthCode": "ABC123" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6915126171696653403954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6915126171696653403954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6915126171696653403954/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6915126171696653403954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "ABC123" }, "status": "AUTHORIZED", "submitTimeUtc": "2023-08-08T16:36:57Z" } ``` Refunds {#payments-processing-basic-refund-intro} ================================================= This section provides the information you need in order to process a refund, which is linked to a capture or sale. You must request a refund within 180 days of the authorization. When your account is enabled for credit authorizations, also known as purchase return authorizations, `Visa Acceptance Solutions` authenticates the card and customer during a refund or credit request. Every credit request is automatically authorized. Credit authorization results are returned in these response fields: * processorInformation.approvalCode * processorInformation.networkTransactionId * processorInformation.responseCode When you request a void for the credit and the credit is voided. If your account is enabled for credit authorizations, the credit authorization is also reversed. Endpoint {#payments-processing-basic-refund-intro_d19e198} ---------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/refunds`{#payments-processing-basic-refund-intro_d19e206} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/refunds`{#payments-processing-basic-refund-intro_d19e219} 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. orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Interactive Example: Processing a Refund {#payments-processing-basic-refund-ex-live} ========================================================================================= ``` Refund a Payment ``` Live Console URL: [index.html#payments_refund_refund-a-payment](https://developer.visaacceptance.com/api-reference-assets/index.md#payments_refund_refund-a-payment "") 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": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "016153570198200", "responseCode": "100" }, "reconciliationId": "61873329OAILG3Q6", "status": "PENDING", "submitTimeUtc": "2022-12-02T15:54:18Z" } ``` 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. When your account is enabled for credit authorizations, also known as purchase return authorizations, `Visa Acceptance Solutions` authenticates the card and customer during a refund or credit request. Every credit request is automatically authorized. Credit authorization results are returned in these response fields: * processorInformation.approvalCode * processorInformation.networkTransactionId * processorInformation.responseCode When you request a void for the credit and the credit is voided. If your account is enabled for credit authorizations, the credit authorization is also reversed. Endpoint {#payments-processing-basic-credit-intro_d19e168} ---------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits/`{#payments-processing-basic-credit-intro_d19e177} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits/`{#payments-processing-basic-credit-intro_d19e187} Required Fields for Processing a Credit {#payments-processing-basic-credit-required-fields} =========================================================================================== Use these required fields for processing a credit. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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 : {#payments-processing-basic-credit-required-fields_dl_vbd_yfw_1yb} REST Interactive Example: Processing a Credit {#payments-processing-basic-credit-ex-live} ========================================================================================= ``` Credit ``` Live Console URL: [index.html#payments_credit_process-a-credit](https://developer.visaacceptance.com/api-reference-assets/index.md#payments_credit_process-a-credit "") 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" } ``` Voids {#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. Endpoint {#payments-processing-basic-void-intro_d19e267} -------------------------------------------------------- **Void a Capture** **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/captures/`*{id}*`/voids`{#payments-processing-basic-void-intro_d19e280} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/captures/`*{id}*`/voids`{#payments-processing-basic-void-intro_d19e293} **Void a Credit** **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits/`*{id}*`/voids`{#payments-processing-basic-void-intro_d19e310} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits/`*{id}*`/voids`{#payments-processing-basic-void-intro_d19e324} The *{id}* is the transaction ID returned during the capture or credit response. Required Fields for Processing a Void {#payments-processing-basic-void-required-fields} ======================================================================================= clientReferenceInformation.code : While not required, this field is recommended. id : Set the `id` URL parameter to the request ID that was included in the authorization response message. REST Example: Processing a Void {#payments-processing-basic-void-ex-rest} ========================================================================= ``` { "clientReferenceInformation": { "code": "test123" } } } ``` ``` { "_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" } } ``` Debit and Prepaid Card Processing {#payments-debit-prepaid-process-intro} ========================================================================= This section shows you how to process authorizations that use a debit or prepaid card. Related Information ------------------- * See [Debit and Prepaid Card Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-intro/payments-features-intro/payments-debit-prepaid-intro.md "") for a description of the debit or prepaid card transactions you can process. Processing Debit and Prepaid Authorizations {#payments-debit-prepaid-auth-intro} ================================================================================ This section shows you how to process an authorization using debit and prepaid cards. Endpoint {#payments-debit-prepaid-auth-intro_d19e16} ---------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-debit-prepaid-auth-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-debit-prepaid-auth-intro_d19e35} Required Fields for Processing Debit and Prepaid Authorizations {#payments-processing-debit-prepaid-auth-required} ================================================================================================================== Use these required fields for processing debit and prepaid authorizations. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). clientReferenceInformation.code : 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.type : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : Optional Field for Processing Debit and Prepaid Authorizations {#concept_i1y_bnd_g5b} ===================================================================================== You can use this optional field to include additional information when processing debit and prepaid authorizations. processingInformation.linkId : Set this field to the request ID that was returned in the response message from the original authorization request. REST Example: Processing Debit and Prepaid Authorizations {#payments-debit-prepaid-auth-ex-rest} ================================================================================================ Request ```keyword { "orderInformation" : { "billTo" : { "country" : "US", "firstName" : "John", "lastName" : "Deo", "address1" : "901 Metro Center Blvd", "postalCode" : "40500", "locality" : "Foster City", "administrativeArea" : "CA", "email" : "test@vas.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "securityCode" : "123", "expirationMonth" : "12", "type" : "001" } } } ``` Response to a Successful Request ``` { "_links" : { "authReversal" : { "method" : "POST", "href" : "/pts/v2/payments/6595482584316313203494/reversals" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6595482584316313203494" }, "capture" : { "method" : "POST", "href" : "/pts/v2/payments/6595482584316313203494/captures" } }, "clientReferenceInformation" : { "code" : "RTS-Auth" }, "consumerAuthenticationInformation" : { "token" : "Axj/7wSTZYq1MhJBMfMmAEQs2auWrRwyauGjNi2ZsWbJgzaOWiaVA+JbK AU0qB8S2VpA6cQIp4ZNvG2YbC9eM4E5NlirUyEkEx8yYAAA4A1c" }, "id" : "6595482584316313203494", "orderInformation" : { "amountDetails" : { "authorizedAmount" : "100.00", "currency" : "USD" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "processorInformation" : { "systemTraceAuditNumber" : "853428", "approvalCode" : "831000", "cardVerification" : { "resultCodeRaw" : "M", "resultCode" : "M" }, "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "retrievalReferenceNumber" : "221517853428", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } } } ``` Enabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-part-auth-intro} =========================================================================================== Partial authorizations and balance responses are special features that are available for debit cards and prepaid cards. This section shows you how to enable partial authorizations for a specific transaction. Field Specific to this Use Case ------------------------------- Include this field in addition to the fields required for a standard authorization request: * Indicate that this request is a partial authorization. Set the processingInformation.authorizationOptions.partialAuthIndicator to `true`. Endpoint {#payments-debit-prepaid-part-auth-intro_d19e16} --------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-debit-prepaid-part-auth-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-debit-prepaid-part-auth-intro_d19e35} Required Fields for Enabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-part-auth-required} ================================================================================================================== Use these required fields for enabling debit and prepaid partial authorizations. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). clientReferenceInformation.code : 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.type : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : processingInformation.authorizationOptions.partialAuthIndicator : Set the value to `true`. Optional Field for Enabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-part-auth-optional} ================================================================================================================= You can use these optional fields to include additional information when enabling debit and prepaid partial authorizations. processingInformation.linkId : Set this field to the request ID that was returned in the response message from the original authorization request. REST Example: Enabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-part-auth-ex-rest} =========================================================================================================== Request ```keyword { "clientReferenceInformation" : { "code" : "TC50171_3" }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Deo", "address2" : "Address 2", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "John", "phoneNumber" : "999999999", "district" : "MI", "buildingNumber" : "123", "company" : "Visa", "email" : "test@vas.com" }, "amountDetails" : { "totalAmount" : "1000.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "5555555555xxxxxx", "securityCode" : "123", "expirationMonth" : "12", "type" : "002" } }, "processingInformation" : { "authorizationOptions" : { "partialAuthIndicator" : "true" } } } ``` Response to a Successful Request ``` { "_links" : { "self" : { "method" : "GET", "href" : "/pts/v2/payments/6595549144566655003494" } }, "clientReferenceInformation" : { "code" : "TC50171_3" }, "id" : "6595549144566655003494", "orderInformation" : { "amountDetails" : { "totalAmount" : "1000.00", "authorizedAmount" : "499.01", "currency" : "USD" } }, "paymentInformation" : { "accountFeatures" : { "currency" : "usd", "balanceAmount" : "0.00" } }, "pointOfSaleInformation" : { "terminalId" : "261996" }, "processorInformation" : { "merchantNumber" : "000000092345678", "approvalCode" : "888888", "cardVerification" : { "resultCode" : "" }, "networkTransactionId" : "123456789619999", "transactionId" : "123456789619999", "responseCode" : "100", "avs" : { "code" : "X", "codeRaw" : "I1" } }, "reconciliationId" : "56059417N6C86KTJ", "status" : "PARTIAL_AUTHORIZED", "submitTimeUtc" : "2022-08-03T19:28:34Z" } ``` Disabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-disable-part-auth-intro} ==================================================================================================== This topic shows you how to successfully disable partial authorizations for specific transactions. Field Specific to this Use Case {#payments-debit-prepaid-disable-part-auth-intro_section_brd_jvn_sxb} ----------------------------------------------------------------------------------------------------- Include this field in addition to the fields required for a standard authorization request: * Indicate that this request is not a partial authorization. Set the `processingInformation.authorizationOptions.partialAuthIndicator` to `false`. {#payments-debit-prepaid-disable-part-auth-intro_ul_crd_jvn_sxb} Endpoint {#payments-debit-prepaid-disable-part-auth-intro_d19e16} ----------------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#payments-debit-prepaid-disable-part-auth-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#payments-debit-prepaid-disable-part-auth-intro_d19e35} Required Field for Disabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-disable-part-auth-required} ========================================================================================================================== Use these required fields for disabling debit and prepaid partial authorizations. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). clientReferenceInformation.code : 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.type : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.number : processingInformation.authorizationOptions.partialAuthIndicator : Set the value to `false` in an authorization or sale request. When you do so, only that specific transaction is disabled for partial authorization. Optional Field for Disabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-disable-part-auth-optional} ========================================================================================================================== You can use this optional field to include additional information when disabling debit and prepaid partial authorizations. processingInformation.linkId : Set this field to the request ID that was returned in the response message from the original authorization request. REST Example: Disabling Debit and Prepaid Partial Authorizations {#payments-debit-prepaid-disable-part-auth-ex-rest} ==================================================================================================================== Request ```keyword { "processingInformation":{ "authorizationOptions":{ "partialAuthIndicator": "false" } }, "clientReferenceInformation" : { "code" : "TC50171_3" }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Deo", "address2" : "Address 2", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "John", "phoneNumber" : "999999999", "district" : "MI", "buildingNumber" : "123", "company" : "Visa", "email" : "test@vas.com" }, "amountDetails" : { "totalAmount" : "501.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "5555555555xxxxxx", "securityCode" : "123", "expirationMonth" : "12", "type" : "002" } } } ``` Response to a Successful Request ``` { "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/6595545423896900104953" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "errorInformation": { "reason": "PROCESSOR_DECLINED", "message": "Decline - General decline of the card. No other information provided by the issuing bank." }, "id": "6595545423896900104953", "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "status": "DECLINED" } ``` Payer Authentication Processing {#payment-processing-pa-process-intro} ====================================================================== This section shows you how to process authorizations that use these payer authentication methods: * **American Express**: SafeKey {#payment-processing-pa-process-intro_ul_dqz_xll_5xb} Providing Payer Authentication Information for Authorization {#concept_hr5_jnj_hxb} =================================================================================== The values that are returned from payer authentication must be provided when seeking authorization for the transaction. Authentication information that is not included when considering authorization may cause the transaction to be refused or downgraded and prevent the normal liability shift from occurring. The level of security in payer authentication is denoted by the two digit Electronic Commerce Indicator (ECI) that is assigned to the transaction. These digital values have text equivalents which are assigned to the processingInformation.commerceIndicator field. The American Express, Diners, Discover, UPI, and Visa card brands use 05, 06, and 07 digit values to express the authentication level for a 3-D Secure transaction. | ECI Value | Meaning | Visa | Diners | Discover | UPI | Amex | |:----------|--------------------------------------------|:---------------------|:-------------|:---------------|:-----------------------|:---------------| | `05` | Authenticated | vbv | pb | dipb | up3ds | aesk | | `06` | Attempted authentication with a cryptogram | vbv_attempted | pb_attempted | dipb_attempted | up3ds_attempted | aesk_attempted | | `07` | Internet, not authenticated | vbv_failure/internet | internet | internet | up3ds_failure/internet | internet | [Text Values for ECI Values] American Express SafeKey {#cc-pa-amex-intro} ============================================ American Express SafeKey is the authentication service in the American Express card network that uses the 3-D Secure protocol to validate customers at checkout. When you request an authorization using a supported card type and a supported processor, you can include payer authentication data in the request. Before implementing payer authentication for American Express SafeKey, contact customer support to have your account configured for this feature. > IMPORTANT > On ` American Express Direct `, American Express SafeKey is mandatory for transactions that originate in Singapore. Fields Specific to the American Express SafeKey Use Case -------------------------------------------------------- These API fields are required specifically for this use case. consumerAuthenticationInformation.cavv : Required when payer authentication is successful. processingInformation.commerceIndicator : Set this field to one of these values: * `aesk`: Successful authentication (3-D Secure value of `05`). * `aesk_attempted`: Authentication was attempted (3-D Secure value of `06`). * `internet`: Authentication failed or was not attempted (3-D Secure value of `07`). {#cc-pa-amex-intro_ul_onm_fn1_jxb} Endpoint {#cc-pa-amex-intro_d19e16} ----------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#cc-pa-amex-intro_d19e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#cc-pa-amex-intro_d19e35} Required Fields for Processing an Authorization Using American Express SafeKey {#payments-processing-pa-amex-reqfields} ======================================================================================================================= These fields must be included in a request for an authorization with American SafeKey. The values for these fields are in the response from the payer authentication validate service. When you request the payer authentication validate and authorization services together, the data is automatically passed from one service to the other. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). clientReferenceInformation.code : consumerAuthenticationInformation.cavv : consumerAuthenticationInformation.eciRaw : Required when the payer authentication validation service returns a raw unmapped ECI value. 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.card.type : processingInformation.commerceIndicator : Set this field to one of these values: * `aesk`: Successful authentication (3-D Secure value of `05`). * `aesk_attempted`: Authentication was attempted (3-D Secure value of `06`). * `internet`: Authentication failed or was not attempted (3-D Secure value of `07`). {#payments-processing-pa-amex-reqfields_ul_onm_fn1_jxb} Optional Field for Processing an Authorization Using American Express SafeKey {#payments-processing-pa-amex-optfields} ====================================================================================================================== This field is optional in a request for an authorization with American Express SafeKey. The value for this field is in the response from the payer authentication validate service. When you request the payer authentication validate and authorization services together, the data is automatically passed from one service to the other. consumerAuthenticationInformation.xid : REST Example: Processing an Authorization Using American Express SafeKey {#payments-processing-pa-amex-ex-rest} =============================================================================================================== Request ``` { "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "aesk" }, "paymentInformation": { "card": { "number": "3400000XXXXXXX8", "expirationMonth": "01", "expirationYear": "2025" } }, "orderInformation": { "amountDetails": { "totalAmount": "100", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "201 S. Division St._1", "locality": "Foster City", "administrativeArea": "CA", "postalCode": "94404", "country": "US", "email": "accept@who.com", "phoneNumber": "6504327113" } }, "consumerAuthenticationInformation": { "cavv": "1234567890987654321ABCDEFabcdefABCDEF123", "xid": "1234567890987654321ABCDEFabcdefABCDEF123" } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6783071542936193303955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6783071542936193303955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6783071542936193303955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6783071542936193303955", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "003" } }, "paymentInformation": { "accountFeatures": { "currency": "usd", "balanceAmount": "70.00" }, "tokenizedCard": { "type": "003" }, "card": { "type": "003" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62427259FEYR18Q2", "status": "AUTHORIZED", "submitTimeUtc": "2023-03-08T20:25:54Z" } ``` Relaxed Requirements for Address Data and Expiration Date in Payment Transactions {#payments-relax-reqs} ======================================================================================================== With relaxed requirements for address data and the expiration date, not all standard payment request fields are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. Requirements {#payments-relax-reqs-reqs} ======================================== You must contact customer support in order to enable relaxed requirements for address data and expiration date. Services {#payments-relax-reqs-services} ======================================== Relaxed requirements for address data and expiration date are supported for these services: * Authorization * Capture * Stand-alone credit * Subscription create * Subscription update Relaxed Fields {#payments-relax-reqs-fields} ============================================ > IMPORTANT > When relaxed requirements for address data and expiration date are enabled for your ` Visa Acceptance Solutions ` account, and your service request does not include one or more of the fields in the following list, you increase the risk of declined transactions and fraud depending on your location, your processor, and the cardholder's issuing bank. > It is your responsibility to determine whether a field is required for the transaction you are requesting. For example, an issuing bank can decline an authorization request for a recurring transaction with a Visa Europe card if the expiration date is incorrect, invalid, or missing. If you do not provide the correct expiration date for a recurring transaction the authorization request may be declined. orderInformation.billTo.address1 : orderInformation.billTo.administrativeArea : orderInformation.billTo.country : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : orderInformation.billTo.locality : orderInformation.billTo.postalCode : When you include this field in your request, you must also include orderInformation.billTo.country paymentInformation.card.expirationMonth : When you include this field in your request, you must also include paymentInformation.card.expirationYear. : This field is required for payment network token transactions and subscription creation requests. paymentInformation.card.expirationYear : When you include this field in your request, you must also include paymentInformation.card.expirationMonth. : This field is required for payment network token transactions and subscription creation requests. Processing Payments Using Credentials {#credentials-processing-intro} ===================================================================== This section provides the information you need in order to process payments using credentials. Customer-Initiated Transactions with Credentials on File {#credentials-cit-intro} ================================================================================= A customer-initiated transaction (CIT) is a transaction initiated by the customer. There are two types of CITs: * Customer transactions during which the credentials are stored for future **customer**-initiated transactions. * Customer transactions during which the credentials are stored for future **merchant**-initiated transactions. Customers can initiate a CIT at a merchant payment terminal, through an online purchase transaction, or by making a purchase using a previously stored credential. When storing cardholder data for a CIT, you must also include 3-D Secure authentication credentials to ensure that the CIT can successfully process. Authentication credentials can be stored for future use with the card credentials by doing a non-payment authentication (NPA). `Business Center` ----------------- You can create a new customer-initiated transaction in the `Business Center` by going to the One-Time Payments section and requesting a new authorization. When you have entered the customer's information, you can store the customer's credentials with the customer's permission in the Payment Information section. By doing so, you can perform merchant-initiated transactions for payments that the customer has pre-approved. Storing Customer Credentials with a CIT and PAN {#credentials-cit-storing-intro} ================================================================================ Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated transaction (CIT) with credentials-on-file (COF), you must store the customer's credentials for later use. Further, before you can store the user's credentials, you must get the customer's consent to store their private information. This is also known as establishing a relationship with the customer. Endpoint {#credentials-cit-storing-intro_d8e16} ----------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-cit-storing-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-cit-storing-intro_d8e35} Required Fields for Storing Customer Credentials During a CIT {#credentials-cit-storing-required} ================================================================================================= Use these required fields for storing customer credentials during a customer-initiated transaction. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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.authorizationOptions. initiator. credentialStoredOnFile : Set the value to `true`. REST Example: Storing Customer Credentials During a CIT {#credentials-cit-storing-ex-rest} ========================================================================================== Request ```keyword { "processingInformation": { "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "email": "test@vas.com", "phoneNumber": "5554327113" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" } ``` Storing Customer Credentials with a CIT and `TMS` {#credentials-cit-initial-tms-intro} ====================================================================================== Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated transaction (CIT) with credentials-on-file (COF), you must get the customer's consent to store their payment credentials. This is also known as establishing a relationship with the customer. After you have their consent, you can store their payment credentials for later use. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Endpoint {#credentials-cit-initial-tms-intro_d8e16} --------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-cit-initial-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-cit-initial-tms-intro_d8e35} Required Fields for Storing Customer Credentials with a CIT and `TMS` {#credentials-cit-initial-tms-req-fields} =============================================================================================================== > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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.actionList : Set the value to`TOKEN_CREATE` processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `instrumentIdentifier` * `paymnentInstrument` {#credentials-cit-initial-tms-req-fields_ul_lpg_4mc_1dc} {#credentials-cit-initial-tms-req-fields_dl_ar1_mwl_bwb} REST Example: Storing Customer Credentials with a CIT and `TMS` {#credentials-cit-initial-tms-ex-rest} ====================================================================================================== Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ] }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031", "securityCode": "123" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "4158880000" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6972267090226779103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6972267090226779103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62506622XNMR6Q1Y", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-13T19:51:49Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } } ``` Retrieving Stored Customer Credentials During a CIT {#credentials-cit-using-intro} ================================================================================== After customers store their credentials on file, you can retrieve these credentials to use with subsequent transactions. Endpoint {#credentials-cit-using-intro_d8e16} --------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-cit-using-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-cit-using-intro_d8e35} Required Fields for Retrieving Customer Credentials During a Customer-Initiated Transaction {#credentials-cit-using-required} ============================================================================================================================= Use these required fields to retrieve customer credentials during a customer-initiated transaction. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). 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.authorizationOptions. initiator. storedCredentialUsed : Set field to `true`. {#credentials-cit-using-required_dl_kjy_kwl_bwb} Card-Specific Required Field for Retrieving Customer Credentials During a CIT {#credentials-install-mit-card-type} ================================================================================================================== Discover -------- Discover requires the authorization amount from the original transaction in addition to the above required fields. processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction. originalAuthorizedAmount : REST Example: Retrieving Customer Credentials During a CIT {#credentials-cit-using-ex-rest} =========================================================================================== Request ```keyword { "processingInformation": { "authorizationOptions": { "initiator": { "storedCredentialUsed": "true" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "email": "test@vas.com", "phoneNumber": "5554327113" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD", "originalAmount": "100" // Discover card Only } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } }, "processorInformation": { "transactionId": "12345678961000" } } ``` Response to a Successful Request ``` }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63740353A3AJ2NSH", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T19:13:06Z" } ``` Installment Payments {#credentials-install-intro} ================================================= An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer. The agreement enables you to charge a specific amount at specified intervals. Installments Service for Installment Payments {#credentials-install-intro_install-service} ------------------------------------------------------------------------------------------ > IMPORTANT > Do not use this document if you are using the Installments service. When using the Installments service, ` Visa Acceptance Solutions ` saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices. Customer-Initiated Installment Payments with PAN {#credentials-mit-cit-install-initial-intro} ============================================================================================= An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer, and sometimes, the issuing bank. The agreement enables you to charge a specific amount at specified intervals. For customers, installment payments provide greater purchasing power and lower impact on their monthly budget. For you, offering installment payments at checkout can help increase the number of successfully completed purchases. Before you can accept installment payments, you and your acquirer must agree on the maximum number of installments you can accept, which can be different for each card type. > IMPORTANT > Do not use this document if you are using the Installments service. When using the Installments service, ` Visa Acceptance Solutions ` saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices. > IMPORTANT > When you submit an installment transaction that does not meet the ` American Express Direct ` requirements for installment payments, ` American Express Direct ` processes the transaction as a regular, non-installment transaction. Installment Payment Types ------------------------- `American Express Direct` enables you to process these types of installment payments: Issuer Installments : American Express refers to this arrangement as a *deferred payment plan*. The customer pays for goods or services using an installment plan agreed upon by the customer and their issuing bank. The issuer controls how the customer's account is debited. Your account is credited for the entire amount in a single transaction. The issuer assumes the risk and establishes credit rates and fees that are charged to the customer. Merchant Installments : American Express refers to this arrangement as a *Plan N*. The customer pays for goods or services using an installment plan agreed upon by you and the customer. The issuer controls how the customer's account is debited. Your account is credited periodically for partial amounts as the customer's account is debited. You assume the risk and establish the credit rate and fees that are charged to the customer. Supported Countries and Regions ------------------------------- This table describes the countries and regions `American Express Direct` supports for processing installment payments, and the installment payment types that are supported there. | Country and Region | Installment Payment Types | Currency | |--------------------|-----------------------------------------------|-----------------------------------------| | Argentina | * Issuer Installments * Merchant Installments | `ARS` | | Asia Pacific | * Issuer Installments | No restrictions. | | Australia | * Issuer Installments | No restrictions. | | Mexico | * Issuer Installments * Merchant Installments | `MXN` Payments must be 250 MXN or more. | [Supported Countries and Regions] Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Endpoint {#credentials-mit-cit-install-initial-intro_d8e16} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mit-cit-install-initial-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mit-cit-install-initial-intro_d8e35} Successful Response ------------------- You must store the *network transaction ID* from the successful response message to include in subsequent MIT authorization requests in order to associate the CIT to the MIT. The network transaction ID is the processorInformation.networkTransactionId field value. Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for Initial Customer-Initiated Installment Payments with a PAN {#credentials-mit-install-initial-reqfields} =========================================================================================================================== Include these required fields to authorize an initial customer-initiated installment payment using a PAN. installmentInformation.planType : Include if the corresponding value is not set in your account or if you want to override the value in your account. installmentInformation.totalCount : 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. authorizationOptions. initiator. credentialStoredOnFile : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `customer`. processingInformation. commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. Card-Specific Fields for Authorizing Initial Installment Payments {#credentials-mit-install-initial-reqfields_initial-cit-card} ------------------------------------------------------------------------------------------------------------------------------- Use this required field if you are authorizing an initial installment payment using the card type referenced below. Mastercard : processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. reason : Set the value to `9`. REST Example: Authorizing Initial Customer-Initiated Installment Payments with a PAN {#credentials-mit-install-initial-ex-rest} =============================================================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "type": "customer", "credentialStoredOnFile": "true", "merchantInitiatedTransaction": { "reason": "9" //Mastercard only } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" } ``` Customer-Initiated Installment Payment with `TMS` {#credentials-install-cit-tms-iid-intro} ========================================================================================== An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer, and sometimes, the issuing bank. The agreement enables you to charge a specific amount at specified intervals. For customers, installment payments provide greater purchasing power and lower impact on their monthly budget. For you, offering installment payments at checkout can help increase the number of successfully completed purchases. Before you can accept installment payments, you and your acquirer must agree on the maximum number of installments you can accept, which can be different for each card type. > IMPORTANT > Do not use this document if you are using the Installments service. When using the Installments service, ` Visa Acceptance Solutions ` saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices. > IMPORTANT > When you submit an installment transaction that does not meet the ` American Express Direct ` requirements for installment payments, ` American Express Direct ` processes the transaction as a regular, non-installment transaction. Installment Payment Types ------------------------- `American Express Direct` enables you to process these types of installment payments: Issuer Installments : American Express refers to this arrangement as a *deferred payment plan*. The customer pays for goods or services using an installment plan agreed upon by the customer and their issuing bank. The issuer controls how the customer's account is debited. Your account is credited for the entire amount in a single transaction. The issuer assumes the risk and establishes credit rates and fees that are charged to the customer. Merchant Installments : American Express refers to this arrangement as a *Plan N*. The customer pays for goods or services using an installment plan agreed upon by you and the customer. The issuer controls how the customer's account is debited. Your account is credited periodically for partial amounts as the customer's account is debited. You assume the risk and establish the credit rate and fees that are charged to the customer. Supported Countries and Regions ------------------------------- This table describes the countries and regions `American Express Direct` supports for processing installment payments, and the installment payment types that are supported there. | Country and Region | Installment Payment Types | Currency | |--------------------|-----------------------------------------------|-----------------------------------------| | Argentina | * Issuer Installments * Merchant Installments | `ARS` | | Asia Pacific | * Issuer Installments | No restrictions. | | Australia | * Issuer Installments | No restrictions. | | Mexico | * Issuer Installments * Merchant Installments | `MXN` Payments must be 250 MXN or more. | [Supported Countries and Regions] Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Endpoint {#credentials-install-cit-tms-iid-intro_d8e16} ------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-install-cit-tms-iid-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-install-cit-tms-iid-intro_d8e35} Required Fields for CIT Installment Payments with TMS {#credentials-install-cit-tms-iid-reqfields} ================================================================================================== installmentInformation.planType : Include if the corresponding value is not set in your account or if you want to override the value in your account. installmentInformation.totalCount : 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.actionList : Set the value to `TOKEN_CREATE`. processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `instrumentIdentifier` * `paymnentInstrument` processingInformation.commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. {#credentials-install-cit-tms-iid-reqfields_dl_cbq_dwl_bwb} Card-Specific Fields for Authorizing Initial Installment Payments {#credentials-install-cit-tms-iid-reqfields_section_sqm_shj_mxb} ---------------------------------------------------------------------------------------------------------------------------------- Use this required field if you are authorizing an initial installment payment using the card type referenced below. Mastercard : processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. reason : Set the value to `9`. REST Example: CIT Installment Payment with TMS {#credentials-install-cit-tms-iid-ex-rest} ========================================================================================= Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet" }, "paymentInformation": { "card": { "number": "411111111111XXXX", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "4158880000" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6972267090226779103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6972267090226779103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62506622XNMR6Q1Y", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-13T19:51:49Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } } ``` Customer-Initiated Installment Payment with Enrollable Network Tokens {#credentials-install-cit-dw-intro} ========================================================================================================= An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer, and sometimes, the issuing bank. The agreement enables you to charge a specific amount at specified intervals. For customers, installment payments provide greater purchasing power and lower impact on their monthly budget. For you, offering installment payments at checkout can help increase the number of successfully completed purchases. > IMPORTANT > Do not use this document if you are using the Installments service. When using the Installments service, ` Visa Acceptance Solutions ` saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices. Using Enrollable Network Tokens ------------------------------- The `Token Management Service` can enroll certain *network tokens* , known as device tokens, into an instrument identifier token for future payments. *Device tokens* store and encrypt card-on-file information which enables customers to make quick and easy purchases using their mobile device. When authorizing a credentialed payment with a device token, you must create and store the device token in a `TMS` instrument identifier token. To do this, include the device token information in the paymentInformation.tokenizedCard fields and set the token creation fields to create an instrument identifier token. Follow-on merchant-initiated transactions are performed using the created instrument identifier as the payment information. For more information about how to request a merchant-initiated transaction, see [Merchant-Initiated Installment Payment with TMS](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-install-intro/credentials-install-mit-tms-intro.md ""). Device tokens are also known as *digital payments* , *digital wallets* , and *tokenized cards*. Network Token Types ------------------- In your request, include the processingInformation.paymentSolution field to identify the device token type you are using, and set it to one of these possible values: * `001`: Apple Pay * `004`: `Visa Acceptance Solutions` In-App Solution * `005`: Masterpass * `006`: Android Pay * `007`: Chase Pay * `008`: Samsung Pay * `012`: Google Pay * `014`: Mastercard credential-on-file (COF) payment network token{#credentials-install-cit-dw-intro_d10e71} {#credentials-install-cit-dw-intro_d10e71} * `015`: Visa credential-on-file (COF) payment network token{#credentials-install-cit-dw-intro_d10e76} {#credentials-install-cit-dw-intro_d10e76} * `027`: Click to Pay * `visacheckout`: `Visa Click to Pay`. {#credentials-install-cit-dw-intro_d10e67} Installment Payment Types ------------------------- `American Express Direct` enables you to process these types of installment payments: Issuer Installments : American Express refers to this arrangement as a *deferred payment plan*. The customer pays for goods or services using an installment plan agreed upon by the customer and their issuing bank. The issuer controls how the customer's account is debited. Your account is credited for the entire amount in a single transaction. The issuer assumes the risk and establishes credit rates and fees that are charged to the customer. Merchant Installments : American Express refers to this arrangement as a *Plan N*. The customer pays for goods or services using an installment plan agreed upon by you and the customer. The issuer controls how the customer's account is debited. Your account is credited periodically for partial amounts as the customer's account is debited. You assume the risk and establish the credit rate and fees that are charged to the customer. Supported Countries and Regions ------------------------------- This table describes the countries and regions `American Express Direct` supports for processing installment payments, and the installment payment types that are supported there. | Country and Region | Installment Payment Types | Currency | |--------------------|-----------------------------------------------|-----------------------------------------| | Argentina | * Issuer Installments * Merchant Installments | `ARS` | | Asia Pacific | * Issuer Installments | No restrictions. | | Australia | * Issuer Installments | No restrictions. | | Mexico | * Issuer Installments * Merchant Installments | `MXN` Payments must be 250 MXN or more. | [Supported Countries and Regions] Endpoint {#credentials-install-cit-dw-intro_d8e16} -------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-install-cit-dw-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-install-cit-dw-intro_d8e35} Required Fields for a CIT Installment Payment with Enrollable Network Tokens {#credentials-install-cit-dw-reqfields} ==================================================================================================================== 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.tokenizedCard.expirationMonth : paymentInformation.tokenizedCard.expirationYear : paymentInformation.tokenizedCard.number : paymentInformation.tokenizedCard.transactionType : Set the value to `1`. processingInformation.actionList : Set the value to `TOKEN_CREATE`. processingInformation.actionTokenTypes : Set the value to `instrumentIdentifier`. processingInformation.commerceIndicator : Set the value to `internet`. processingInformation.paymentSolution : Set to one of these possible values: * `001`: Apple Pay * `004`: `Visa Acceptance Solutions` In-App Solution * `005`: Masterpass * `006`: Android Pay * `007`: Chase Pay * `008`: Samsung Pay * `012`: Google Pay * `014`: Mastercard credential-on-file (COF) payment network token{#credentials-install-cit-dw-reqfields_d10e71} {#credentials-install-cit-dw-reqfields_d10e71} * `015`: Visa credential-on-file (COF) payment network token{#credentials-install-cit-dw-reqfields_d10e76} {#credentials-install-cit-dw-reqfields_d10e76} * `027`: Click to Pay * `visacheckout`: `Visa Click to Pay`. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). Example: CIT Installment Payments with Enrollable Network Tokens {#credentials-install-cit-dw-ex-rest} ====================================================================================================== Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet", "paymentSolution": "001" }, "paymentInformation": { "tokenizedCard": { "number": "4111111111111111", "expirationMonth": "02", "expirationYear": "2025", "transactionType": "1" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78757", "country": "US", "email": "test@vas.com", "phoneNumber": "444-4444-4444" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7094060020036241803954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/captures" } }, "clientReferenceInformation": { "code": "1709406002076" }, "id": "7094060020036241803954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60616704ST7Q27K2", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-02T19:00:02Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } } ``` Merchant-Initiated Installment Payments with PAN {#credentials-mit-install-subsequent-intro} ============================================================================================ After the initial CIT installment payment, subsequent installment payments are merchant-initiated transactions (MITs). > IMPORTANT > When you submit an installment transaction that does not meet the ` American Express Direct ` requirements for installment payments, ` American Express Direct ` processes the transaction as a regular, non-installment transaction. Prerequisites ------------- The first transaction in an installment payment is a *customer-initiated transaction* (CIT). Before you can perform a subsequent *merchant-initiated transaction* (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Installment Payment Types ------------------------- `American Express Direct` enables you to process these types of installment payments: Issuer Installments : American Express refers to this arrangement as a *deferred payment plan*. The customer pays for goods or services using an installment plan agreed upon by the customer and their issuing bank. The issuer controls how the customer's account is debited. Your account is credited for the entire amount in a single transaction. The issuer assumes the risk and establishes credit rates and fees that are charged to the customer. Merchant Installments : American Express refers to this arrangement as a *Plan N*. The customer pays for goods or services using an installment plan agreed upon by you and the customer. The issuer controls how the customer's account is debited. Your account is credited periodically for partial amounts as the customer's account is debited. You assume the risk and establish the credit rate and fees that are charged to the customer. Supported Countries and Regions ------------------------------- This table describes the countries and regions `American Express Direct` supports for processing installment payments, and the installment payment types that are supported there. | Country and Region | Installment Payment Types | Currency | |--------------------|-----------------------------------------------|-----------------------------------------| | Argentina | * Issuer Installments * Merchant Installments | `ARS` | | Asia Pacific | * Issuer Installments | No restrictions. | | Australia | * Issuer Installments | No restrictions. | | Mexico | * Issuer Installments * Merchant Installments | `MXN` Payments must be 250 MXN or more. | [Supported Countries and Regions] Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Endpoint {#credentials-mit-install-subsequent-intro_d8e16} ---------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mit-install-subsequent-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mit-install-subsequent-intro_d8e35} Required Fields for Authorizing Merchant-Initiated Subsequent Installment Payments {#credentials-mit-install-reqfields} ======================================================================================================================= Use these required fields to authorize merchant-initiated subsequent installment payments. 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.authorizationOptions. initiator. merchantInitiatedTransaction. previousTransactionID : * American Express: set to the transaction ID from the original transaction. * Discover: set to the transaction ID from the original transaction. * Visa: set to the last successful transaction ID. processingInformation. authorizationOptions. initiator. storedCredentialUsed : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `merchant`. processingInformation. commerceIndicator : Set the value to `install`. REST Example: Authorizing Merchant-Initiated Subsequent Installment Payments {#credentials-mit-install-ex-rest} =============================================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "install", "authorizationOptions": { "initiator": { "storedCredentialUsed": "true", "type": "merchant", "merchantInitiatedTransaction": { "reason": "9", "previousTransactionId": "123456789619999", "originalAuthorizedAmount": "100" //Discover Only } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` Merchant-Initiated Installment Payment with `TMS` {#credentials-install-mit-tms-intro} ====================================================================================== This section describes how to process a merchant-initiated installment payment using these `TMS` token types: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } } ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. : Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } } ``` **Instrument Identifier** : Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID. : ``` "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } } ``` > IMPORTANT > When you submit an installment transaction that does not meet the ` American Express Direct ` requirements for installment payments, ` American Express Direct ` processes the transaction as a regular, non-installment transaction. Prerequisites ------------- The first transaction in an installment payment is a *customer-initiated transaction* (CIT). Before you can perform a subsequent *merchant-initiated transaction* (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Installment Payment Types ------------------------- `American Express Direct` enables you to process these types of installment payments: Issuer Installments : American Express refers to this arrangement as a *deferred payment plan*. The customer pays for goods or services using an installment plan agreed upon by the customer and their issuing bank. The issuer controls how the customer's account is debited. Your account is credited for the entire amount in a single transaction. The issuer assumes the risk and establishes credit rates and fees that are charged to the customer. Merchant Installments : American Express refers to this arrangement as a *Plan N*. The customer pays for goods or services using an installment plan agreed upon by you and the customer. The issuer controls how the customer's account is debited. Your account is credited periodically for partial amounts as the customer's account is debited. You assume the risk and establish the credit rate and fees that are charged to the customer. Supported Countries and Regions ------------------------------- This table describes the countries and regions `American Express Direct` supports for processing installment payments, and the installment payment types that are supported there. | Country and Region | Installment Payment Types | Currency | |--------------------|-----------------------------------------------|-----------------------------------------| | Argentina | * Issuer Installments * Merchant Installments | `ARS` | | Asia Pacific | * Issuer Installments | No restrictions. | | Australia | * Issuer Installments | No restrictions. | | Mexico | * Issuer Installments * Merchant Installments | `MXN` Payments must be 250 MXN or more. | [Supported Countries and Regions] Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Endpoint {#credentials-install-mit-tms-intro_d8e16} --------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-install-mit-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-install-mit-tms-intro_d8e35} Required Fields for MIT Installment Payments with `TMS` {#credentials-install-mit-tms-reqfields} ================================================================================================ Include these Required Fields ----------------------------- orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.\[tokentype\].id : Where \[tokentype\] is the `TMS` token type you are using: : * customer * instrumentIdentifier * paymentInstrument processingInformation.commerceIndicator : Set the value to `install`. Instrument Identifier Required Fields ------------------------------------- If you are using the paymentInformation.instrumentIdentifier.id token, include these required fields in addition to the required fields listed above. 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 : Example: MIT with `TMS` Instrument Identifier Token {#credentials-install-mit-tms-iid-ex-rest} ============================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "install" }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2031" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "4158880000" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` Recurring Payments {#credentials-recur-intro} ============================================= A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer for a fixed amount at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Recurring payments are also known as *subscriptions*. Mastercard uses standing order and subscription payments instead of recurring payments. See [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md "") and [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md ""). Recurring Billing Service for Recurring Payments ------------------------------------------------ IMPORTANT Do not use this document for the Recurring Billing service. Customer-Initiated Recurring Payment with PAN {#credentials-recur-cit-pan-intro} ================================================================================ A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer at a fixed amount, at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Support Card Type ----------------- The American Express card type is supported for processing credentialed transactions. Mastercard uses standing order and subscription payments instead of recurring payments. See [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md "") and [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md ""). Recurring Billing Service for Recurring Payments ------------------------------------------------ > IMPORTANT Do not use this document for the Recurring Billing service. Address Verification Service for Recurring Payments --------------------------------------------------- If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request. `Visa Acceptance Solutions` recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud. You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment. Endpoint {#credentials-recur-cit-pan-intro_d8e16} ------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-recur-cit-pan-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-recur-cit-pan-intro_d8e35} Successful Response ------------------- You must store the *network transaction ID* from the successful response message to include in subsequent MIT authorization requests in order to associate the CIT to the MIT. The network transaction ID is the processorInformation.networkTransactionId field value. Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for Authorizing a Customer-Initiated Recurring Payment with PAN {#credentials-recur-cit-pan-reqfields} ====================================================================================================================== Use these required fields to request an initial customer-initiated recurring payment. 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 : processingInformation. authorizationOptions. initiator. credentialStoredOnFile : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `customer`. processingInformation. commerceIndicator : Set the value to `internet`, a payer authentication value, or `MOTO`. processingInformation. recurringOptions. firstRecurringPayment : Set the value to `true`. REST Example: Authorizing a Customer-Initiated Recurring Payment with a PAN {#credentials-recur-cit-pan-ex-rest} ================================================================================================================ Request ```keyword { "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true", "type": "customer" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" } ``` Customer-Initiated Recurring Payment with `TMS` {#credentials-recur-cit-tms-intro} ================================================================================== A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer at a fixed amount, at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Support Card Type ----------------- The American Express card type is supported for processing credentialed transactions. Mastercard uses standing order and subscription payments instead of recurring payments. See [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md "") and [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md ""). Recurring Billing Service for Recurring Payments ------------------------------------------------ > IMPORTANT Do not use this document for the Recurring Billing service. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Address Verification Service for Recurring Payments --------------------------------------------------- If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request. `Visa Acceptance Solutions` recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud. You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment. Endpoint {#credentials-recur-cit-tms-intro_d8e16} ------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-recur-cit-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-recur-cit-tms-intro_d8e35} Required Fields for Authorizing a Customer-Initiated Recurring Payment with `TMS` {#credentials-recur-cit-tms-reqfields} ======================================================================================================================== Use these required fields to request a customer-initiated recurring payment with `TMS`. 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 : processingInformation.actionList : Set the value to `TOKEN_CREATE`. processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `instrumentIdentifier` * `paymentInstrument` processingInformation.commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. processingInformation.recurringOptions.firstRecurringPayment : Set the value to `true`. {#credentials-recur-cit-tms-reqfields_dl_dqw_kdt_5wb} REST Example: Authorizing a Customer-Initiated Recurring Payment with `TMS` {#credentials-recur-cit-tms-ex-rest} ================================================================================================================ Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer" ], "commerceIndicator": "internet", "recurringOptions": { "firstRecurringPayment": true } }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976858134106105703954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976858134106105703954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976858134106105703954/captures" } }, "clientReferenceInformation": { "code": "1697685813462" }, "id": "6976858134106105703954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62698397FNN143CC", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T03:23:33Z", "tokenInformation": { "customer": { "id": "080A3A742BF87171E063A2598D0AEABE" } } } ``` Customer-Initiated Recurring Payment with Enrollable Network Tokens {#credentials-recur-cit-dw-intro} ===================================================================================================== A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer at a fixed amount, at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Mastercard uses standing order and subscription payments instead of recurring payments. See [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md "") and [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md ""). Recurring Billing Service for Recurring Payments ------------------------------------------------ > IMPORTANT Do not use this document for the Recurring Billing service. Using Enrollable Network Tokens ------------------------------- The `Token Management Service` can enroll certain *network tokens* , known as device tokens, into an instrument identifier token for future payments. *Device tokens* store and encrypt card-on-file information which enables customers to make quick and easy purchases using their mobile device. When authorizing a credentialed payment with a device token, you must create and store the device token in a `TMS` instrument identifier token. To do this, include the device token information in the paymentInformation.tokenizedCard fields and set the token creation fields to create an instrument identifier token. Follow-on merchant-initiated transactions are performed using the created instrument identifier as the payment information. For more information about how to request a merchant-initiated transaction, see [Merchant-Initiated Recurring Payments with TMS](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-recur-intro/credentials-recur-mit-tms-intro.md ""). Device tokens are also known as *digital payments* , *digital wallets* , and *tokenized cards*. Network Token Types ------------------- In your request, include the processingInformation.paymentSolution field to identify the device token type you are using, and set it to one of these possible values: * `001`: Apple Pay * `004`: `Visa Acceptance Solutions` In-App Solution * `005`: Masterpass * `006`: Android Pay * `007`: Chase Pay * `008`: Samsung Pay * `012`: Google Pay * `014`: Mastercard credential-on-file (COF) payment network token{#credentials-recur-cit-dw-intro_d10e71} {#credentials-recur-cit-dw-intro_d10e71} * `015`: Visa credential-on-file (COF) payment network token{#credentials-recur-cit-dw-intro_d10e76} {#credentials-recur-cit-dw-intro_d10e76} * `027`: Click to Pay * `visacheckout`: `Visa Click to Pay`. {#credentials-recur-cit-dw-intro_d10e67} Endpoint {#credentials-recur-cit-dw-intro_d8e16} ------------------------------------------------ **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-recur-cit-dw-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-recur-cit-dw-intro_d8e35} Required Fields for Authorizing a Customer-Initiated Recurring Payments with Enrollable Network Tokens {#credentials-recur-cit-dw-reqfields} ============================================================================================================================================ 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.tokenizedCard.expirationMonth : paymentInformation.tokenizedCard.expirationYear : paymentInformation.tokenizedCard.number : paymentInformation.tokenizedCard.transactionType : Set the value to `1`. processingInformation.actionList : Set the value to `TOKEN_CREATE`. processingInformation.actionTokenTypes : Set the value to `instrumentIdentifier`. processingInformation.commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. processingInformation.paymentSolution : Set to one of these possible values: * `001`: Apple Pay * `004`: `Visa Acceptance Solutions` In-App Solution * `005`: Masterpass * `006`: Android Pay * `007`: Chase Pay * `008`: Samsung Pay * `012`: Google Pay * `014`: Mastercard credential-on-file (COF) payment network token{#credentials-recur-cit-dw-reqfields_d10e71} {#credentials-recur-cit-dw-reqfields_d10e71} * `015`: Visa credential-on-file (COF) payment network token{#credentials-recur-cit-dw-reqfields_d10e76} {#credentials-recur-cit-dw-reqfields_d10e76} * `027`: Click to Pay * `visacheckout`: `Visa Click to Pay`. > 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. For details about relaxed requirements, see [Relaxed Requirements for Address Data and Expiration Date in Payment Transactions](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/payments-relax-reqs.md ""). REST Example: Authorizing a Customer-Initiated Recurring Payment with Enrollable Network Tokens {#credentials-recur-cit-dw-ex-rest} =================================================================================================================================== Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet", "paymentSolution": "001" }, "paymentInformation": { "tokenizedCard": { "number": "4111111111111111", "expirationMonth": "02", "expirationYear": "2025", "transactionType": "1" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78757", "country": "US", "email": "test@vas.com", "phoneNumber": "444-4444-4444" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7094060020036241803954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/captures" } }, "clientReferenceInformation": { "code": "1709406002076" }, "id": "7094060020036241803954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60616704ST7Q27K2", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-02T19:00:02Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } } ``` Merchant-Initiated Recurring Payments with PAN {#credentials-recur-mit-pan-intro} ================================================================================= After the initial recurring payment (CIT), subsequent recurring payments are merchant-initiated transactions (MITs). Prerequisites ------------- The first transaction in a recurring payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the customer's credentials, you must get their consent to store their private information. This is also known as establishing a relationship with the customer. Support Card Type ----------------- The American Express card type is supported for processing credentialed transactions. Mastercard uses standing order and subscription payments instead of recurring payments. See [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md "") and [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md ""). Address Verification Service for Recurring Payments --------------------------------------------------- If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request. `Visa Acceptance Solutions` recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud. You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment. Replacing Expiration Dates -------------------------- If the customer's card-on-file is going to expire before a scheduled subsequent recurring payment, your processor may allow you to replace the expiration date with the date 12/2099. IMPORTANT Do not replace a card's expiration date if the card is not expired. Using this replacement expiration date does not guarantee a successful authorization request. It is your responsibility to know if your processor supports this feature. Not all issuing banks support the 12/2099 expiration date and may decline the authorization request. To include this date in the authorization request, use these fields and values. paymentInformation.card.expirationMonth : Set to `12`. paymentInformation.card.expirationYear : Set to `99`. Endpoint {#credentials-recur-mit-pan-intro_d8e16} ------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-recur-mit-pan-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-recur-mit-pan-intro_d8e35} Required Fields for Authorizing a Merchant-Initiated Recurring Payment {#credentials-recur-mit-pan-reqfields} ============================================================================================================= Use these required fields to authorize subsequent recurring payments. 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. authorizationOptions. initiator. merchantInitiatedTransaction. previousTransactionID : For Discover and American Express cards, use the transaction ID from the original transaction. For Visa, use the last successful transaction ID. processingInformation. authorizationOptions. initiator. storedCredentialUsed : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `merchant`. processingInformation. commerceIndicator : Set the value to `recurring`. {#credentials-recur-mit-pan-reqfields_dl_w5j_cyb_1dc} Card-Specific Required Fields for Authorizing Subsequent Recurring Payments {#credentials-recur-mit-card-type} ============================================================================================================== Some card companies require additional information when making authorizations with stored credentials. Discover -------- Include the authorization amount from the original transaction in this field: processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction. originalAuthorizedAmount : Mastercard ---------- Mastercard supports subscription and standing order payments instead of recurring payments. See [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md "") and [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md ""). REST Example: Authorizing a Merchant-Initiated Recurring Payment {#credentials-recur-mit-pan-ex-rest} ===================================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "recurring", "authorizationOptions": { "initiator": { "storedCredentialUsed": "true", "type": "merchant", "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999", "originalAuthorizedAmount": "100" //Discover Only } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` Merchant-Initiated Recurring Payments with `TMS` {#credentials-recur-mit-tms-intro} =================================================================================== After the customer-initiated recurring payment, you can send merchant-initiated recurring payments using one or more `TMS` token types: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } } ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. : Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } } ``` **Instrument Identifier** : Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID. : ``` "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } } ``` Prerequisites ------------- The first transaction in a recurring payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the customer's credentials, you must get their consent to store their private information. This is also known as establishing a relationship with the customer. Support Card Type ----------------- The American Express card type is supported for processing credentialed transactions. Mastercard uses standing order and subscription payments instead of recurring payments. See [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md "") and [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md ""). Address Verification Service for Recurring Payments --------------------------------------------------- If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request. `Visa Acceptance Solutions` recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud. You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment. Replacing Expiration Dates -------------------------- If the customer's card-on-file is going to expire before a scheduled subsequent recurring payment, your processor may allow you to replace the expiration date with the date 12/2099. IMPORTANT Do not replace a card's expiration date if the card is not expired. Using this replacement expiration date does not guarantee a successful authorization request. It is your responsibility to know if your processor supports this feature. Not all issuing banks support the 12/2099 expiration date and may decline the authorization request. To include this date in the authorization request, use these fields and values. paymentInformation.card.expirationMonth : Set to `12`. paymentInformation.card.expirationYear : Set to `99`. Endpoint {#credentials-recur-mit-tms-intro_d8e16} ------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-recur-mit-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-recur-mit-tms-intro_d8e35} Required Fields for Authorizing a Merchant-Initiated Recurring Payments with `TMS` {#credentials-recur-mit-tms-reqfields} ========================================================================================================================= Use these required fields to authorize subsequent recurring payments. orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.\[tokentype\].id : Where \[tokentype\] is the `TMS` token type you are using: : * customer * instrumentIdentifier * paymentInstrument processingInformation.commerceIndicator : Set the value to `recurring`. Instrument Identifier Required Fields ------------------------------------- If you are using the paymentInformation.instrumentIdentifier.id token, include these required fields in addition to the required fields listed above. 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 : Card-Specific Field ------------------- Some card companies require additional fields when making authorizations with stored credentials. Include this field if you are using these card types: Discover : processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.originalAuthorizedAmount Mastercard : Mastercard supports subscription and standing order payments instead of recurring payments. See [Mastercard Subscription Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mc-subscription-intro.md "") and [Mastercard Standing Order Payments](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-mit-stand-order-intro.md ""). REST Example: Authorizing a Merchant-Initiated Recurring Payment with a `TMS` Instrument Identifier {#credentials-recur-mit-tms-iid-ex-rest} ============================================================================================================================================ Request ```keyword { "processingInformation": { "commerceIndicator": "recurring" }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2025" }, "instrumentIdentifier": { "id": "4111xxxxxxxxxxxx" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "4158880000" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` REST Example: Authorizing a Merchant-Initiated Recurring Payment with `TMS` Payment Instrument {#credentials-recur-mit-tms-pid-ex-rest} ======================================================================================================================================= Request ``` { "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "recurring" }, "paymentInformation": { "paymentInstrument": { "id": "07DB0915C20F2DDBE063A2598D0A6F26" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6974839908106304103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6974839908106304103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6974839908106304103955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6974839908106304103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "07DB0915C20F2DDBE063A2598D0A6F26" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62599243NNMR6324", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-16T19:19:51Z" } ``` REST Example: Authorizing a Merchant-Initiated Recurring Payment with a `TMS` Customer Token {#credentials-recur-mit-tms-cid-ex-rest} ===================================================================================================================================== Request ``` { "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "recurring" }, "paymentInformation": { "customer": { "id": "07DB50E35AE11DA2E063A2598D0A9995" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6974846967476340503955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6974846967476340503955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6974846967476340503955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6974846967476340503955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62599950BNN133LK", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-16T19:31:36Z" } ``` Mastercard Standing Order Payments {#credentials-mit-stand-order-intro} ======================================================================= A standing order payment is a recurring COF transaction that is a variable amount at a regular interval, such as a utility bill, not to exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Mastercard Initial CIT Standing Order Payment {#credentials-mit-cit-stand-order-initial-intro} ============================================================================================== The first transaction in a standing order payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Endpoint {#credentials-mit-cit-stand-order-initial-intro_d8e16} --------------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mit-cit-stand-order-initial-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mit-cit-stand-order-initial-intro_d8e35} Successful Response ------------------- You must store the *network transaction ID* from the successful response message to include in subsequent MIT authorization requests in order to associate the CIT to the MIT. The network transaction ID is the processorInformation.networkTransactionId field value. Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for Authorizing Initial CIT Standing Order Payments {#credentials-mit-stand-order-initial-reqfields} ==================================================================================================================== Use these required fields to authorize initial customer-initated standing order payments. 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. authorizationOptions. initiator. credentialStoredOnFile : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `customer`. processingInformation. commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. reason : Set the value to `8`. {#credentials-mit-stand-order-initial-reqfields_dl_kmx_yvl_bwb} REST Example: Authorizing Initial CIT Standing Order Payments {#credentials-mit-stand-order-initial-ex-rest} ============================================================================================================ Request ```keyword { "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true", "type": "customer", "merchantInitiatedTransaction": { "reason": "8" } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "5555xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` Mastercard Initial CIT Standing Order Payment with `TMS` {#credentials-mit-cit-stand-order-initial-tms-intro} ============================================================================================================= The first transaction in a standing order payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Endpoint {#credentials-mit-cit-stand-order-initial-tms-intro_d8e16} ------------------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mit-cit-stand-order-initial-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mit-cit-stand-order-initial-tms-intro_d8e35} Required Fields for Authorizing Initial CIT Standing Order Payments with `TMS` {#credentials-mit-stand-order-initial-tms-reqfields} =================================================================================================================================== 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.actionList : Set the value to `TOKEN_CREATE` processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `instrumentIdentifier` * `paymentInstrument` processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.reason : Set the value to `8`. processingInformation.commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. {#credentials-mit-stand-order-initial-tms-reqfields_dl_kmx_yvl_bwb} REST Example: Authorizing Initial CIT Standing Order Payments with `TMS` {#credentials-mit-stand-order-initial-tms-ex-rest} =========================================================================================================================== Request ```keyword { "processingInformation": { "actionList": ["TOKEN_CREATE"], "actionTokenTypes": ["customer"], "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "8" } } } }, "paymentInformation": { "card": { "number": "555555555555xxxx", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Sunnyville", "administrativeArea": "CA", "postalCode": "55555", "country": "US", "email": "test@vas.com", "phoneNumber": "444-4444-4444" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7064959411486706503954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7064959411486706503954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7064959411486706503954/captures" } }, "clientReferenceInformation": { "code": "1706495941197" }, "id": "7064959411486706503954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "680915409RRMGL34", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-29T02:39:01Z", "tokenInformation": { "customer": { "id": "100D6CDA178DD64DE063A2598D0AD3D5" } } } ``` Mastercard Subscription Payments {#credentials-mc-subscription-intro} ===================================================================== A subscription payment is a recurring COF transaction that is processed at a fixed amount at regular intervals not to exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Mastercard CIT Initial Subscription Payment {#credentials-mc-subscription-cit-pan-intro} ======================================================================================== The first transaction in a subscription payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Endpoint {#credentials-mc-subscription-cit-pan-intro_d8e16} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mc-subscription-cit-pan-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mc-subscription-cit-pan-intro_d8e35} Successful Response ------------------- You must store the *network transaction ID* from the successful response message to include in subsequent MIT authorization requests in order to associate the CIT to the MIT. The network transaction ID is the processorInformation.networkTransactionId field value. Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for Authorizing CIT Initial Subscription Payments {#credentials-mc-subscription-cit-pan-req-fields} =================================================================================================================== 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.authorizationOptions.initiator.credentialStoredOnFile : Set the value to `true`. processingInformation.authorizationOptions.initiator.type : Set the value to `customer`. processingInformation.commerceIndicator : Set the value to `recurring`. processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.reason : Set the value to `7`. {#credentials-mc-subscription-cit-pan-req-fields_dl_s1l_wvl_bwb} REST Example: Authorizing Initial CIT Subscription Payments {#credentials-mc-subscription-cit-pan-ex-rest} ========================================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "type": "customer", "credentialStoredOnFile": "true", "merchantInitiatedTransaction": { "reason": "7" } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` Mastercard CIT Initial Subscription Payment with `TMS` {#credentials-mc-subscription-cit-tms-intro} =================================================================================================== The first transaction in a subscription payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Endpoint {#credentials-mc-subscription-cit-tms-intro_d8e16} ----------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mc-subscription-cit-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mc-subscription-cit-tms-intro_d8e35} Required Fields for Authorizing CIT Initial Subscription Payments with `TMS` {#credentials-mc-subscription-cit-tms-req-fields} ============================================================================================================================== 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.actionList : Set the value to `TOKEN_CREATE` processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `instrumentIdentifier` * `paymentInstrument` processingInformation.commerceIndicator : Set the value to `recurring`. processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.reason : Set the value to `7`. {#credentials-mc-subscription-cit-tms-req-fields_dl_s1l_wvl_bwb} REST Example: Authorizing Initial CIT Subscription Payments {#credentials-mc-subscription-cit-tms-ex-rest} ========================================================================================================== Request ```keyword { "processingInformation": { "actionList": ["TOKEN_CREATE"], "actionTokenTypes": ["customer"], "commerceIndicator": "recurring", "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "7" } } } }, "paymentInformation": { "card": { "number": "555555555555xxxx", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Sunnyville", "administrativeArea": "CA", "postalCode": "55555", "country": "US", "email": "test@vas.com", "phoneNumber": "444-4444-4444" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7064946846256410103954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7064946846256410103954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7064946846256410103954/captures" } }, "clientReferenceInformation": { "code": "1706494684667" }, "id": "7064946846256410103954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "68091233JRRDUQ34", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-29T02:18:04Z", "tokenInformation": { "customer": { "id": "100D1DC40CC7C803E063A2598D0A29BD" } } } ``` Unscheduled COF Payments {#credentials-ucof-intro} ================================================== An unscheduled credentials-on-file (COF) transaction uses stored payment information for a fixed or variable amount that does not occur regularly. An account top-up is one kind of unscheduled COF. Customer-Initiated Unscheduled COF Payment with PAN {#credentials-cit-ucof-initial-intro} ========================================================================================= An unscheduled credentials-on-file (COF) transaction uses stored payment information for a fixed or variable amount that does not occur regularly. An account top-up is one kind of unscheduled COF. Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Endpoint {#credentials-cit-ucof-initial-intro_d8e16} ---------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-cit-ucof-initial-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-cit-ucof-initial-intro_d8e35} Successful Response ------------------- You must store the *network transaction ID* from the successful response message to include in subsequent MIT authorization requests in order to associate the CIT to the MIT. The network transaction ID is the processorInformation.networkTransactionId field value. Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for a Customer-Initiated Unscheduled COF Payment with PAN {#credentials-cit-ucof-initial-reqfields} =================================================================================================================== These fields are required in a subsequent authorization request for an initial unscheduled COF payment: 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. authorizationOptions. initiator. credentialStoredOnFile : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `customer`. processingInformation. commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. REST Example: Customer-Initiated Unscheduled COF Payment with PAN {#credentials-cit-ucof-initial-ex-rest} ========================================================================================================= Request ```keyword { "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true", "type": "customer" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" } ``` Customer-Initiated Unscheduled COF Payments with `TMS` {#credentials-ucof-cit-tms-intro} ======================================================================================== An unscheduled credentials-on-file (COF) transaction uses stored payment information for a fixed or variable amount that does not occur regularly. An account top-up is one kind of unscheduled COF. Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Endpoint {#credentials-ucof-cit-tms-intro_d8e16} ------------------------------------------------ **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-ucof-cit-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-ucof-cit-tms-intro_d8e35} Required Fields for CIT Unscheduled COF Payments with `TMS` {#credentials-ucof-cit-tms-reqfields} ================================================================================================= 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.actionList : Set the value to `TOKEN_CREATE` processingInformation.actionTokenTypes : Set to one or more of these values: * `customer` * `instrumentIdentifier` * `paymnentInstrument` processingInformation.commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. REST Example: Initial CIT Unscheduled COF Payment in TMS {#credentials-ucof-cit-tms-ex-rest} ============================================================================================ Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer" ], "commerceIndicator": "internet" }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "444-4444-4444" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976866073586557303955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976866073586557303955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976866073586557303955/captures" } }, "clientReferenceInformation": { "code": "1697686607441" }, "id": "6976866073586557303955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699023FNN143DG", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T03:36:47Z", "tokenInformation": { "customer": { "id": "080A6C3842C72DCBE063A2598D0AA98B" } } } ``` Customer-Initiated Unscheduled COF Payment with Enrollable Network Tokens {#credentials-ucof-cit-dw-intro} ========================================================================================================== An unscheduled credentials-on-file (COF) transaction uses stored payment information for a fixed or variable amount that does not occur regularly. An account top-up is one kind of unscheduled COF. Using Enrollable Network Tokens ------------------------------- The `Token Management Service` can enroll certain *network tokens* , known as device tokens, into an instrument identifier token for future payments. *Device tokens* store and encrypt card-on-file information which enables customers to make quick and easy purchases using their mobile device. When authorizing a credentialed payment with a device token, you must create and store the device token in a `TMS` instrument identifier token. To do this, include the device token information in the paymentInformation.tokenizedCard fields and set the token creation fields to create an instrument identifier token. Follow-on merchant-initiated transactions are performed using the created instrument identifier as the payment information. For more information about how to request a merchant-initiated transaction, see [Merchant-Initiated Unscheduled COF Payments with TMS](/docs/vas/en-us/payments/developer/amexdirect/rest/payments/credentials-processsing-intro/credentials-ucof-intro/credentials-ucof-mit-tms-intro.md ""). Device tokens are also known as *digital payments* , *digital wallets* , and *tokenized cards*. Network Token Types ------------------- In your request, include the processingInformation.paymentSolution field to identify the device token type you are using, and set it to one of these possible values: * `001`: Apple Pay * `004`: `Visa Acceptance Solutions` In-App Solution * `005`: Masterpass * `006`: Android Pay * `007`: Chase Pay * `008`: Samsung Pay * `012`: Google Pay * `014`: Mastercard credential-on-file (COF) payment network token{#credentials-ucof-cit-dw-intro_d10e71} {#credentials-ucof-cit-dw-intro_d10e71} * `015`: Visa credential-on-file (COF) payment network token{#credentials-ucof-cit-dw-intro_d10e76} {#credentials-ucof-cit-dw-intro_d10e76} * `027`: Click to Pay * `visacheckout`: `Visa Click to Pay`. {#credentials-ucof-cit-dw-intro_d10e67} Endpoint {#credentials-ucof-cit-dw-intro_d8e16} ----------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-ucof-cit-dw-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-ucof-cit-dw-intro_d8e35} Required Fields for CIT Unscheduled COF Payment with Enrollable Network Tokens {#credentials-ucof-cit-dw-reqfields} =================================================================================================================== 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.tokenizedCard.expirationMonth : paymentInformation.tokenizedCard.expirationYear : paymentInformation.tokenizedCard.number : paymentInformation.tokenizedCard.transactionType : Set the value to `1`. processingInformation.actionList : Set the value to `TOKEN_CREATE`. processingInformation.actionTokenTypes : Set the value to `instrumentIdentifier`. processingInformation.commerceIndicator : Set the value to `internet`, `MOTO`, or a payer authentication value. processingInformation.paymentSolution : Set to one of these possible values: * `001`: Apple Pay * `004`: `Visa Acceptance Solutions` In-App Solution * `005`: Masterpass * `006`: Android Pay * `007`: Chase Pay * `008`: Samsung Pay * `012`: Google Pay * `014`: Mastercard credential-on-file (COF) payment network token{#credentials-ucof-cit-dw-reqfields_d10e71} {#credentials-ucof-cit-dw-reqfields_d10e71} * `015`: Visa credential-on-file (COF) payment network token{#credentials-ucof-cit-dw-reqfields_d10e76} {#credentials-ucof-cit-dw-reqfields_d10e76} * `027`: Click to Pay * `visacheckout`: `Visa Click to Pay`. `REST API` Example: CIT Unscheduled COF Payment with Enrollable Network Tokens {#credentials-ucof-cit-dw-ex-rest} ================================================================================================================= Request ```keyword { "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet", "paymentSolution": "001" }, "paymentInformation": { "tokenizedCard": { "number": "4111111111111111", "expirationMonth": "02", "expirationYear": "2025", "transactionType": "1" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78757", "country": "US", "email": "test@vas.com", "phoneNumber": "444-4444-4444" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7094060020036241803954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/captures" } }, "clientReferenceInformation": { "code": "1709406002076" }, "id": "7094060020036241803954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60616704ST7Q27K2", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-02T19:00:02Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } } ``` Merchant-Initiated Unscheduled COF Payments with PAN {#credentials-mit-unsched-subsequent-intro} ================================================================================================ After the initial CIT unscheduled COF payment, subsequent unscheduled COF transactions are merchant-initiated transactions (MITs). Prerequisites ------------- The first transaction in an unscheduled COF payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Endpoint {#credentials-mit-unsched-subsequent-intro_d8e16} ---------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-mit-unsched-subsequent-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-mit-unsched-subsequent-intro_d8e35} Required Fields for Authorizing Subsequent MIT Unscheduled COF Payments {#credentials-mit-unsched-reqfields} ============================================================================================================ These fields are required in a subsequent authorization request for a subsequent unscheduled COF payment: 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. authorizationOptions. initiator. merchantInitiatedTransaction. previousTransactionID : * American Express: set to the transaction ID from the original transaction. * Discover: set to the transaction ID from the original transaction. * Visa: set to the last successful transaction ID. {#credentials-mit-unsched-reqfields_ul_eg2_12c_1dc} processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction.reason : Set the value to `10`. : Required only for American Express, Discover, and Mastercard. processingInformation. authorizationOptions. initiator. storedCredentialUsed : Set the value to `true`. processingInformation. authorizationOptions. initiator. type : Set the value to `merchant`. processingInformation. commerceIndicator : Set the value to `internet`. {#credentials-mit-unsched-reqfields_dl_zwx_rvl_bwb} REST Example: Authorizing Subsequent MIT Unscheduled COF Payments {#credentials-mit-unsched-ex-rest} ==================================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "storedCredentialUsed": "true", "type": "merchant", "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999", "originalAuthorizedAmount": "100" <--Discover Only--> } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@vas.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" } ``` Merchant-Initiated Unscheduled COF Payments with `TMS` {#credentials-ucof-mit-tms-intro} ======================================================================================== After the customer-initiated unscheduled COF payment, you can send merchant-initiated unscheduled COF payments using one or more `TMS` token types: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } } ``` **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. : Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } } ``` **Instrument Identifier** : Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID. : ``` "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } } ``` Prerequisites ------------- The first transaction in an unscheduled COF payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Supported Card Type ------------------- The American Express card type is supported for processing credentialed transactions. Endpoint {#credentials-ucof-mit-tms-intro_d8e16} ------------------------------------------------ **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#credentials-ucof-mit-tms-intro_d8e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#credentials-ucof-mit-tms-intro_d8e35} Required Fields for MIT Unscheduled COF Payments with `TMS` {#credentials-ucof-mit-tms-req-fields} ================================================================================================== Include these Required Fields ----------------------------- orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.\[tokentype\].id : Where \[tokentype\] is the `TMS` token type you are using: : * customer * instrumentIdentifier * paymentInstrument processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction.reason : Set the value to `10`. : Required only for American Express, Discover, and Mastercard. processingInformation.commerceIndicator : Set the value to `internet`. Instrument Identifier Required Fields ------------------------------------- If you are using the paymentInformation.instrumentIdentifier.id token, include these required fields in addition to the required fields listed above. 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 : Card-Specific Field ------------------- The listed card type requires an additional field. Discover : processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.originalAuthorizedAmount : Provide the original transaction amount. Example: MIT Unscheduled COF Payment with TMS Instrument Identifier {#credentials-ucof-mit-tms-iid-ex-rest} =========================================================================================================== Request ```keyword { "processingInformation": { "commerceIndicator": "internet" }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2031" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@vas.com", "phoneNumber": "4158880000" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976892714556134003954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976892714556134003954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976892714556134003954/captures" } }, "clientReferenceInformation": { "code": "1697689271513" }, "id": "6976892714556134003954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699554NNMR6X7R", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T04:21:11Z" } ``` Example: MIT Unscheduled COF Payment with TMS Payment Instrument {#credentials-ucof-mit-tms-pid-ex-rest} ======================================================================================================== Request ``` { "processingInformation": { "commerceIndicator": "internet" }, "paymentInformation": { "paymentInstrument": { "id": "080AE120369A7947E063A2598D0A718F" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976891300676431103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976891300676431103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976891300676431103955/captures" } }, "clientReferenceInformation": { "code": "1697689130124" }, "id": "6976891300676431103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "080AE120369A7947E063A2598D0A718F" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699372XNMR85HS", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T04:18:50Z" } ``` Example: MIT Unscheduled COF Payment with TMS Customer {#credentials-ucof-mit-tms-cid-ex-rest} ============================================================================================== Request ``` { "processingInformation": { "commerceIndicator": "internet" }, "paymentInformation": { "customer": { "id": "080AC9AB60C92AA2E063A2598D0A0C74" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } } ``` Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976889582016147703955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976889582016147703955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976889582016147703955/captures" } }, "clientReferenceInformation": { "code": "1697688958296" }, "id": "6976889582016147703955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "080AE6DB37B09557E063A2598D0AA4C9" }, "card": { "type": "001" }, "customer": { "id": "080AC9AB60C92AA2E063A2598D0A0C74" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699842BNN13VA0", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T04:15:58Z" } ``` `Token Management Service` Processing {#payment-tms-process-intro} ================================================================== This section provides the information you need in order to process `Token Management Service` authorization and credit transactions. > IMPORTANT > Due to mandates from the Reserve Bank of India, Indian merchants cannot store personal account numbers (PANs). Use network tokens instead. For more information on network tokens, see the Network Tokenization section of the [` Token Management Service ` Guide .](https://developer.visaacceptance.com/docs/vas/en-us/tms/developer/ctv/rest/tms/tms-overview.md "") Authorizing a Payment with a Customer Token {#tms-cust-tkn-pay-intro} ===================================================================== This section provides the information you need to authorize a payment with a customer token. Endpoint -------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments ` **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments `{#tms-cust-tkn-pay-intro_restcust-test} Required Fields for Authorizing a Payment with a Customer Token {#tms-cust-tkn-pay-reqfields} ============================================================================================= clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.customer.id : Set to the ID of the customer token you want to use. {#tms-cust-tkn-pay-reqfields_dl_u12_vqy_dwb} REST Example: Authorizing a Payment with a Customer Token {#tms-cust-tkn-pay-ex-rest} ===================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-cust-tkn-pay-ex-rest_codeblock_ndp_y3n_lwb} Response to a Successful Request The request response returns the payment instrument and shipping address IDs that are used as the customer's defaults. ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055928871556818104953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055928871556818104953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055928871556818104953/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055928871556818104953", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "shippingAddress": { "id": "0F35F0D99AD088B5E063A2598D0AE066" }, "paymentInstrument": { "id": "0F35E9CFEA463E34E063A2598D0A3FC2" }, "card": { "type": "001" }, "customer": { "id": "B21E6717A6F03479E05341588E0A303F" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67467352CRIISD1G", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T15:48:07Z" } ``` {#tms-cust-tkn-pay-ex-rest_codeblock_pdp_y3n_lwb} REST Example: Authorizing a Payment Using a Customer Token Linked to a Network Token {#tms-cust-tkn-pay-nt-ex-rest} =================================================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" },   "paymentInformation": {     "customer": {       "id": "F60328413BAB09A4E053AF598E0A33DB"     }   },   "orderInformation": {     "amountDetails": {       "totalAmount": "102.21",       "currency": "USD"     }   } } ``` {#tms-cust-tkn-pay-nt-ex-rest_codeblock_ndp_y3n_lwb} Response to a Successful Request The request response returns the payment instrument and shipping address IDs that are used as the customer's defaults. ``` {   "_links": {     "authReversal": {       "method": "POST",       "href": "/pts/v2/payments/6778647071126384904953/reversals"     },     "self": {       "method": "GET",       "href": "/pts/v2/payments/6778647071126384904953"     },     "capture": {       "method": "POST",       "href": "/pts/v2/payments/6778647071126384904953/captures"     }   },   "clientReferenceInformation": {     "code": "TC50171_3"   },   "id": "6778647071126384904953",   "issuerInformation": {     "responseRaw": "0110322000000E100002000....."   },   "orderInformation": {     "amountDetails": {       "authorizedAmount": "102.21",       "currency": "USD"     }   },   "paymentAccountInformation": {     "card": {       "type": "002"     }   },   "paymentInformation": {     "tokenizedCard": {       "type": "002"     },     "instrumentIdentifier": {       "id": "7020000000010603216",       "state": "ACTIVE"     },     "shippingAddress": {       "id": "F60328413BAE09A4E053AF598E0A33DB"     },     "paymentInstrument": {       "id": "F6032841BE33098EE053AF598E0AB0A5"     },     "card": {       "type": "002"     },     "customer": {       "id": "F60328413BAB09A4E053AF598E0A33DB"     }   },   "pointOfSaleInformation": {     "terminalId": "08244117"   },  "processingInformation": {    "paymentSolution": "014"  },   "processorInformation": {     "paymentAccountReferenceNumber": "50015OU4U5UYXLV127XTONYN49CL1",     "merchantNumber": "000844028303882",     "approvalCode": "831000",     "networkTransactionId": "0602MCC603474",     "transactionId": "0602MCC603474",     "responseCode": "00",     "avs": {       "code": "Y",       "codeRaw": "Y"     }   },   "reconciliationId": "EUHW1EMHIZ3O",   "status": "AUTHORIZED",   "submitTimeUtc": "2023-03-03T17:31:48Z" } ``` {#tms-cust-tkn-pay-nt-ex-rest_codeblock_pdp_y3n_lwb} Authorizing a Payment with a Non-Default Shipping Address {#tms-ship-addr-make-pay-nondefault-ship-addr-intro} ============================================================================================================== This section provides the information you need in order to make a payment with a non-default shipping address. Endpoint {#tms-ship-addr-make-pay-nondefault-ship-addr-intro_section_m1k_n4p_mwb} --------------------------------------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments ` **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments `{#tms-ship-addr-make-pay-nondefault-ship-addr-intro_restcust-test} Required Fields for Authorizing a Payment with a Non-Default Shipping Address {#tms-ship-addr-make-pay-nondefault-ship-addr-reqfields} ====================================================================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.customer.id : Set to the ID of the customer token you want to use. paymentInformation.shippingAddress.id : Set to the ID of the shipping address token you want to use. {#tms-ship-addr-make-pay-nondefault-ship-addr-reqfields_dl_u12_vqy_dwb} REST Example: Authorizing a Payment with a Non-Default Shipping Address {#tms-ship-addr-make-pay-nondefault-ship-addr-ex-rest} ============================================================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" }, "shippingAddress": { "id": "F45FD8DE51B99E9CE053A2598D0AFDFA" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-ship-addr-make-pay-nondefault-ship-addr-ex-rest_codeblock_bnm_wjn_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055949037316786904953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055949037316786904953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055949037316786904953/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055949037316786904953", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7030000000014831523", "state": "ACTIVE" }, "shippingAddress": { "id": "F45FD8DE51B99E9CE053A2598D0AFDFA" }, "paymentInstrument": { "id": "F45FE45E7993C7DBE053A2598D0AED19" }, "card": { "type": "001" }, "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "674679208RIKQ52K", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:21:44Z" } ``` {#tms-ship-addr-make-pay-nondefault-ship-addr-ex-rest_codeblock_dnm_wjn_lwb} Authorizing a Payment with a Non-Default Payment Instrument {#tms-cust-pi-tkn-pay-nondefault-pi-intro} ====================================================================================================== This section provides the information you need in order to authorize a payment with a non-default payment instrument. Endpoint -------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments ` **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#tms-cust-pi-tkn-pay-nondefault-pi-intro_restcust-test} Required Fields for Authorizing a Payment with a Non-Default Payment Instrument {#tms-cust-pi-tkn-pay-nondefault-pi-reqfields} ============================================================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.paymentInstrument.id : Set to the ID of the payment instrument token you want to use. {#tms-cust-pi-tkn-pay-nondefault-pi-reqfields_dl_bcz_qry_dwb} Optional Fields for Authorizing a Payment with a Non-Default Payment Instrument {#tms-cust-pi-tkn-pay-nondefault-pi-optfields} ============================================================================================================================== You can use these optional fields to include additional information when authorizing a payment with a non-default payment instrument. 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.card.type : {#tms-cust-pi-tkn-pay-nondefault-pi-optfields_dl_bcz_qry_dwb} REST Example: Authorizing a Payment with a Non-Default Payment Instrument {#tms-cust-pi-tkn-pay-nondefault-pi-ex-rest} ====================================================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-cust-pi-tkn-pay-nondefault-pi-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055952648586653304951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055952648586653304951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055952648586653304951/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055952648586653304951", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67468244CRIL0U0Y", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:27:45Z" } ``` {#tms-cust-pi-tkn-pay-nondefault-pi-ex-rest_codeblock_x4l_mlt_lwb} Authorizing a Payment with a Payment Instrument {#tms-pi-tkn-pay-intro} ======================================================================= This section provides the information you need in order to authorize a payment with a payment instrument. Endpoint {#tms-pi-tkn-pay-intro_section_dqc_gyd_pwb} ---------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments ` **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#tms-pi-tkn-pay-intro_restcust-test} Required Fields for Authorizing a Payment with a Payment Instrument {#tms-pi-tkn-pay-reqfields} =============================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.paymentInstrument.id : Set to the ID of the payment instrument token you want to use. Optional Fields for Authorizing a Payment with a Payment Instrument {#tms-pi-tkn-pay-optfields} =============================================================================================== You can use these optional fields to include additional information when authorizing a payment with a payment instrument. 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.card.type : {#tms-pi-tkn-pay-optfields_dl_gv1_vnj_rwb} REST Example: Authorizing a Payment with a Payment Instrument {#tms-pi-tkn-pay-ex-rest} ======================================================================================= Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-pi-tkn-pay-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6765713628736138103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6765713628736138103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6765713628736138103955/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "6765713628736138103955", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" }, "card": { "type": "001" }, "customer": { "id": "F4D5E715F75E9910E053A2598D0A7278" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60561224BE37KN5W", "status": "AUTHORIZED", "submitTimeUtc": "2023-02-16T18:16:03Z" } ``` {#tms-pi-tkn-pay-ex-rest_codeblock_x4l_mlt_lwb} Authorize a Payment with an Instrument Identifier {#tms-ii-tkn-pay-intro} ========================================================================= This section provides the information you need in order to authorize a payment with an instrument identifier token. Endpoint -------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments ` **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#tms-ii-tkn-pay-intro_restcust-test} Required Fields for Authorizing a Payment with an Instrument Identifier {#tms-ii-tkn-pay-reqfields} =================================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.instrumentIdentifier.id : Set to the ID of the instrument identifier token you want to use. {#tms-ii-tkn-pay-reqfields_dl_u12_vqy_dwb} REST Example: Authorizing a Payment with an Instrument Identifier {#tms-ii-tkn-pay-ex-rest} =========================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-ii-tkn-pay-ex-rest_codeblock_okq_f1t_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055955288186053404953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055955288186053404953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055955288186053404953/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055955288186053404953", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "1" } }, "reconciliationId": "67468271CRIL0U24", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:32:09Z" } ``` {#tms-ii-tkn-pay-ex-rest_codeblock_qkq_f1t_lwb} REST Example: Authorizing a Payment with an Instrument Identifier While Creating `TMS` Tokens {#tms-ii-tkn-pay-create-ex-rest} ============================================================================================================================== Request ``` { "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer", "paymentInstrument", "shippingAddress" ] }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" }, "shipTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US" } } } ``` {#tms-ii-tkn-pay-create-ex-rest_codeblock_okq_f1t_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7114679840376687203955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7114679840376687203955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7114679840376687203955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "7114679840376687203955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "623971212U7PN4IU", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-26T15:46:24Z", "tokenInformation": { "shippingAddress": { "id": "14930C904FC4D97BE063A2598D0AE0F1" }, "paymentInstrument": { "id": "149310A4A924E911E063A2598D0A47AD" }, "customer": { "id": "14930C904FC1D97BE063A2598D0AE0F1" } } } ``` {#tms-ii-tkn-pay-create-ex-rest_codeblock_qkq_f1t_lwb} Authorize a Payment While Ignoring Network Token {#tms-net-tkn-direct-merch-pay-intro} ====================================================================================== This section shows you how to authorize a payment ignoring a network token. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#tms-net-tkn-direct-merch-pay-intro_restcust-test} **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments ` Required Fields for Authorizing a Payment While Ignoring Network Token {#tms-net-tkn-direct-merch-pay-reqfields} ================================================================================================================ clientReferenceInformation.code : paymentInformation.customer.id : paymentInformation.paymentInformation.id : paymentInformation.shippingAddress.id : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : processingInformation.capture : processingInformation.commerceIndicator : tokenInformation.networkTokenOption : Set value to `ignore`. {#tms-net-tkn-direct-merch-pay-reqfields_dl_bcz_qry_dwb} REST Example: Authorizing a Payment While Ignoring Network Token {#tms-net-tkn-direct-merch-pay-ex-rest} ======================================================================================================== Request ``` { "clientReferenceInformation": { "code": "RTS-Auth" }, "paymentInformation": { "card": { "expirationYear": "2031", "expirationMonth": "12", "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "1.00" } }, "processingInformation": { "capture": "false", "commerceIndicator": "internet" }, "tokenInformation": { "networkTokenOption": "ignore" } } ``` {#tms-net-tkn-direct-merch-pay-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6769913443166412604951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6769913443166412604951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6769913443166412604951/captures" } }, "clientReferenceInformation": { "code": "RTS-Auth" }, "id": "6769913443166412604951", "orderInformation": { "amountDetails": { "authorizedAmount": "1.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7030000000014911515", "state": "ACTIVE" }, "shippingAddress": { "id": "F537CE8DBA2F032CE053AF598E0A64F2" }, "paymentInstrument": { "id": "F537E3D12322416EE053AF598E0AD771" }, "card": { "type": "001" }, "customer": { "id": "F537CE8DBA2C032CE053AF598E0A64F2" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013019326121174070050420", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "744295942E2LY3F8", "status": "AUTHORIZED", "submitTimeUtc": "2023-02-21T14:55:44Z" } ``` {#tms-net-tkn-direct-merch-pay-ex-rest_codeblock_x4l_mlt_lwb} Authorizing a Payment with a Legacy Token {#tms-legacy-tkn-pay-intro} ===================================================================== This section shows you how to authorize a payment with a legacy token. Endpoint {#tms-legacy-tkn-pay-intro_d25e16} ------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#tms-legacy-tkn-pay-intro_d25e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#tms-legacy-tkn-pay-intro_d25e35} Required Fields for Authorizing a Payment with a Legacy Token {#tms-legacy-tkn-pay-reqfields} ============================================================================================= clientReferenceInformation.code : paymentInformation.legacyToken.id : Include the ID of the legacy token you want to use to authorize a payment. orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : {#tms-legacy-tkn-pay-reqfields_dl_bcz_qry_dwb} REST Example: Authorizing a Payment with a Legacy Token {#tms-legacy-tkn-pay-ex-rest} ===================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "legacyToken": { "id": "B21E6717A6F03479E05341588E0A303F" } }, "orderInformation": { "amountDetails": { "totalAmount": "22.00", "currency": "USD" } } } ``` {#tms-legacy-tkn-pay-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055956342476789004951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055956342476789004951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055956342476789004951/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055956342476789004951", "orderInformation": { "amountDetails": { "authorizedAmount": "22.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67468431FRIIS246", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:33:54Z" } ``` {#tms-legacy-tkn-pay-ex-rest_codeblock_x4l_mlt_lwb} Making a Credit with a Customer Token {#tms-cust-tkn-credit-intro} ================================================================== This section shows you how to make a credit with a customer token. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits `{#tms-cust-tkn-credit-intro_restcust-test} **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits ` Required Fields for Making a Credit with a Customer Token {#tms-cust-tkn-credit-reqfields} ========================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.customer.id : Set to the ID of the customer token you want to use. REST Example: Making a Credit with a Customer Token {#tms-cust-tkn-credit-ex-rest} ================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-cust-tkn-credit-ex-rest_codeblock_ond_y3n_lwb} Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055967677826132904951/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055967677826132904951" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055967677826132904951", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7030000000014831523", "state": "ACTIVE" }, "shippingAddress": { "id": "F45FD8DE51B99E9CE053A2598D0AFDFA" }, "paymentInstrument": { "id": "F45FE45E7993C7DBE053A2598D0AED19" }, "card": { "type": "001" }, "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013019326121538313096266", "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67444961BRIL0BB8", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:52:48Z" } ``` {#tms-cust-tkn-credit-ex-rest_codeblock_qnd_y3n_lwb} Making a Credit with a Non-Default Payment Instrument {#tms-cust-pi-tkn-credit-nondefault-pi-intro} =================================================================================================== This section shows you how to make a credit with a non-default payment instrument. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits `{#tms-cust-pi-tkn-credit-nondefault-pi-intro_restcust-test} **Production:** `POST ``https://api.visaacceptance.com``pts/v2/credits ` Required Fields for Making a Credit with a Non-Default Payment Instrument {#tms-cust-pi-tkn-credit-nondefault-pi-reqfields} =========================================================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.paymentInstrument.id : Set to the ID of the payment instrument token that you want to use. {#tms-cust-pi-tkn-credit-nondefault-pi-reqfields_dl_u12_vqy_dwb} Optional Fields for Making a Credit with a Non-Default Payment Instrument {#tms-cust-pi-tkn-credit-nondefault-pi-optfields} =========================================================================================================================== You can use these optional fields to include additional information when making a credit with a non-default payment instrument. 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.card.type : {#tms-cust-pi-tkn-credit-nondefault-pi-optfields_dl_u12_vqy_dwb} REST Example: Making a Credit with a Non-Default Payment Instrument {#tms-cust-pi-tkn-credit-nondefault-pi-ex-rest} =================================================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-cust-pi-tkn-credit-nondefault-pi-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055968581386446104953/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055968581386446104953" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055968581386446104953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67445196PRILCQCN", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:54:18Z" } ``` {#tms-cust-pi-tkn-credit-nondefault-pi-ex-rest_codeblock_x4l_mlt_lwb} Making a Credit with a Payment Instrument {#tms-pi-tkn-credit-intro} ==================================================================== This section shows you how to make a credit with a payment instrument. Endpoint {#tms-pi-tkn-credit-intro_section_mks_hyd_pwb} ------------------------------------------------------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits `{#tms-pi-tkn-credit-intro_restcust-test} **Production:** `POST ``https://api.visaacceptance.com``pts/v2/credits ` Required Fields for Making a Credit with a Payment Instrument {#tms-pi-tkn-credit-reqfields} ============================================================================================ clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.paymentInstrument.id : Set to the ID of the payment instrument token you want to use. REST Example: Making a Credit with a Payment Instrument {#tms-pi-tkn-credit-ex-rest} ==================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` {#tms-pi-tkn-credit-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055969586686467104953/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055969586686467104953" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055969586686467104953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67446174JRIKXXHB", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:55:59Z" } ``` {#tms-pi-tkn-credit-ex-rest_codeblock_x4l_mlt_lwb} Making a Credit with an Instrument Identifier {#tms-ii-tkn-credit-intro} ======================================================================== This section shows you how to make a credit with an instrument identifier token. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits `{#tms-ii-tkn-credit-intro_restcust-test} **Production:** `POST ``https://api.visaacceptance.com``pts/v2/credits ` Required Fields for Making a Credit with an Instrument Identifier {#tms-ii-tkn-credit-reqfields} ================================================================================================ clientReferenceInformation.code : orderInformation.amountDetails.currency orderInformation.amountDetails.totalAmount : paymentInformation.paymentInstrument.id : Set to the ID of the payment instrument token you want to use. REST Example: Making a Credit with an Instrument Identifier {#tms-ii-tkn-credit-ex-rest} ======================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055970261066212404951/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055970261066212404951" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055970261066212404951", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67445198PRILCQCQ", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:57:06Z" } ``` Making a Credit with a Legacy Token {#tms-legacy-tkn-credit-intro} ================================================================== This section shows you how to make a credit with a legacy token. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits`{#tms-legacy-tkn-credit-intro_restcust-test} **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits ` Required Fields for Making a Credit with a Legacy Token {#tms-legacy-tkn-credit-reqfields} ========================================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.legacyToken.id : Include the ID of the legacy token that you want to use to authorize a payment. REST Example: Making a Credit with a Legacy Token {#tms-legacy-tkn-credit-ex-rest} ================================================================================== Request ``` { "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "legacyToken": { "id": "B21E6717A6F03479E05341588E0A303F" } }, "orderInformation": { "amountDetails": { "totalAmount": "22.00", "currency": "USD" } } } ``` {#tms-legacy-tkn-credit-ex-rest_codeblock_v4l_mlt_lwb} Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055970562096509704953/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055970562096509704953" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "22.00" }, "id": "7055970562096509704953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67444779FRILJT84", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:57:36Z" } ``` {#tms-legacy-tkn-credit-ex-rest_codeblock_x4l_mlt_lwb} Pre-Authorizations {#payments-final-auth-indicator-preauth} =========================================================== A pre-authorization enables you to authorize a payment when the final amount is unknown. It is typically used for lodging, auto rental, e-commerce, and restaurant transactions. For a pre-authorization: * The authorization amount must be greater than zero. * The authorization must be submitted for capture within 30 calendar days of its request. * When you do not capture the authorization, you must reverse it. In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed. In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations. * Chargeback protection is in effect for 30 days after the authorization.