Card Present Connect \| Mass Transit Developer Guide {#um-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 integrate payment processing for mass transit fare collection systems. These services are available using only the REST API. Implementing these services requires software development skills and knowledge and understanding of the card scheme mass transit rules. You must write code that uses the REST API request and response fields to integrate the payment services into your existing mass transit fare collection system. Conventions : This statement is used in this document: > IMPORTANT > An *Important* statement contains information essential to successfully completing a task or learning a concept. Recent Revisions to This Document {#um-doc-revisions} ===================================================== 26.06.01 -------- : Revised and combined Mass Transit Transactions section and Mass Transit Transaction Workflows section into a new section: [Mass Transit Models and Workflows](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-transit-models-flows-intro.md ""). 26.02.01 -------- : Updated debt recovery workflow descriptions in [Debt Recovery Workflows](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-transit-models-flows-intro/um-models-flows-cup-intro/um-models-flows-common-debt-recovery.md ""). : Added response field handling information for authorization requests that return the `AUTH_DECLINE_CAPTURE_POSSIBLE` value in the errorInformation.reason field in [Pre-Authorization with a Token](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-processing-tms/um-processing-cup-pre-auth-intro.md ""). : Combined two EMV data tables into one in [EMV Data Elements and Tags](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-intro-overview/um-processing-emv-cup.md ""). 25.12.01 -------- This revision contains only editorial changes and no technical updates. 25.04.1 ------- Added Sample Test Cards. See [Transit Test Cards](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-intro-overview/um-intro-test-cards-cup.md ""). Added transaction workflows with graphics. See [China UnionPay Mass Transit Workflows](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-transit-models-flows-intro/um-models-flows-cup-intro.md ""). Introduction to Card Present Connect \| Mass Transit {#um-intro-overview} ========================================================================= Card Present Connect \| Mass Transit is the `Visa Acceptance Solutions` solution for processing transactions using card scheme mass transit models. This solution follows global card scheme standards for contactless EMV transit transactions. Transit Rider Benefits {#um-intro-rider} ======================================== These are some transit rider benefits: * Retail-like contactless payment experience. * Fast, contactless tap to enter and exit. * Payment card data protection. * Single, combined payment for multiple trips during a set period. * Ability to request journey history and corresponding receipt. * Travel fare total on payment card statements. * Consistent fare collection experience across transit systems in various cities and countries. Transit System Benefits {#um-intro-merchant} ============================================ These are some mass transit systems benefits: * Lower ticketing overhead that can reduce the need for ticket booths or paper tickets. * Ability to track riders when they tap to enter and exit. * Flexible fare management, including: * Riders pay as they go. * Fares are aggregated for one payment transaction each travel period. * Merchant protection such as: * Encrypted payment data. * First Ride Risk support in some regions. * Debt recovery support. Mass Transit Terminology {#um-intro-terms} ========================================== Aggregated : Transaction in which you calculate the fare based on multiple contactless card taps for trips during a predetermined time period, usually 24 hours, processed as a single transaction. Back office : A component within your transit systems that processes the taps received from transit readers, and that performs any or all journey construction, fare calculation, risk management, and payment processing. Card hash : One-way hash token ID of the payment card data that is used to maintain the deny list. Combined data authentication (CDA) : Authentication technique that uses a combination of card and transaction data. Deferred authorization : Combined authorization and capture request, also known as a sale, for aggregated fare payments. Deny list : List of cards that failed ODA because of an unsuccessful AVR or transit payment. It is used for blocking cards that have not been accepted for travel within your transit system when you are processing aggregated payments, such as the Mastercard PAYG and Visa MTT models. Deny list manager : Manages the deny list and distributes it to the validators. First Ride Risk debt recovery : Under specific and limited conditions established by the card schemes, you can recover the cost of the first ride by capturing a declined authorization. For details, refer to each of the card scheme's rules for mass transit chargeback thresholds and protection. See [First Ride Risk](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-intro-overview/um-workflow-first-ride-risk.md ""). Instrument identifier token : `Token Management Service` token that stores the payment card number. Journey construction : The process of analyzing individual taps received from transit readers and forming logical journeys performed by cardholders. Mobility and Transport Transaction (MTT) : Visa model for contactless mass transit payments for single or multiple modes of transportation, which includes fixed, distance-based, and time-based fares. Offline data authentication (ODA) : EMV security feature in which payment cards are authenticated offline. ODA is necessary so that cardholders can quickly tap and enter the transit system. It is used for aggregated transactions, such as Mastercard PAYG and Visa MTT. Pay As You Go (PAYG) for Mastercard : Mastercard model in which the fare is not known when the cardholder taps their card for travel. All cardholder taps are recorded to calculate the fare and process an aggregated payment. Payment instrument token : `Token Management Service` token that stores the instrument identifier token, card expiration date, and billing address. Retail : Transaction in which you process the payment as a standard contactless retail payment. Tap : Refers to the act of presenting a contactless card at a validator. Ticket inspection : Process in which ticket inspectors verify compliance with fare policies by checking paper tickets or using a portable terminal to read the payment card. Ticket inspectors : Transit employees who travel on the transit system to verify passenger travel status. Transient token : Unique, time-limited token ID that is associated with the tokens created by TMS. The validator forwards this ID to your back office to use for payment transactions and to manage tokens. `Visa Acceptance Solutions` automatically deletes this token after seven days. Travel period : Period of time during which a traveler can make multiple taps in and out of the transit system, before you submit the final payment transaction for the aggregated amount. Validator : EMV contactless card-present terminal located at an automated turnstile device where cardholders tap their card to enter, and optionally exit from, the transit system. Before allowing the cardholder to enter the transit system, the validator checks the deny list to ensure that the card has not failed ODA. Mass Transit Prerequisites {#um-intro-reqs} =========================================== Before integrating `Visa Acceptance Solutions` services for mass transit, you must have these systems in place: * Merchant account with an acquirer that is enabled for mass transit transactions on `Visa Platform Connect`. * `Visa Acceptance Solutions` account for payment services. * Payment technology provider (PTP) that is integrated with `Visa Acceptance Solutions` and can perform message-level validation (MLV). * EMV Level 1 certified transit terminals and EMV Level 2 certified software in preparation for EMV Level 3 Certification. First Ride Risk {#um-workflow-first-ride-risk} ============================================== First Ride Risk (FRR) is a feature that addresses the liability for the first use of a payment credential that fails pre-authorization and might result in a refusal for travel. Use FRR to capture a transaction even when the pre-authorization fails. In this case, the merchant or acquirer assumes responsibility for the risk. First Ride Risk Eligibility Reason Codes {#um-workflow-first-ride-risk-codes} ============================================================================= When a failed pre-authorization returns one of these response codes in the processorInformation.responseCode field, the transaction is eligible for FRR and capture: * `01`: Refer to card issuers. * `04`: Pick-up. * `05`: ID certification fails. * `12`: Invalid related transaction. * `13`: Invalid amount. * `14`: Invalid card number (no such account). * `21`: Card not initialized. * `22`: Suspected malfunction, related transaction error. * `34`: Fraud. * `38`: PIN try limit exceeded. * `40`: Function requested not supported. * `41`: Lost card. * `43`: Stolen card. * `57`: Transaction not allowed to be processed by cardholder. * `58`: Transaction not allowed to be processed by terminal. * `59`: Suspected fraud. * `62`: Restricted card. * `68`: Issuer response timeout. * `75`: Allowable number of PIN tries exceeded. * `90`: Cutoff is in progress. * `91`: Issuer cannot process. * `97`: ATM/POS terminal number cannot be located. * `98`: Issuer response not received. * `99`: PIN block error. * `1A`: The transaction needs additional customer authentication. * `A0`: MAC failed. * `N1`: Items not on Bankbook beyond limit, declined. * `P1`: Contact phone number of cardholder cannot be found in the issuer's system. EMV Data Elements and Tags {#um-processing-emv-cup} =================================================== You can request these payment services for mass transit with EMV and card data: * Sale for single fares and debt recovery. * Authorization and capture for aggregate fares and debt recovery. * First ride risk. * Stand-alone credit. The EMV Data Elements and Tags table lists details about EMV tags that are mandatory (M), prohibited (P), optional (O), or conditional (C) for `China UnionPay`. Send a conditional tag when it is present in the card and terminal. | Data Element | EMV Tag | Length | Example Data | China UnionPay | |:----------------------------------------|:--------|:-------|:---------------------------------|:---------------| | Transaction Currency Code | 5F2A | 02 | 0446 | M | | Application Interchange Profile | 82 | 02 | 2000 | M | | Terminal Verification Result (TVR) | 95 | 05 | 0000000000 | M | | Transaction Date | 9A | 03 | 240109 | M | | Transaction Type | 9C | 01 | 03 | M | | Transaction Amount / Amount Authorized | 9F02 | 06 | 000000001000 | M | | Amount Other | 9F03 | 06 | 000000000000 | M | | Issuer Application Data (IAD) | 9F10 | 08 | 0700010300000001 | M | | Terminal Country Code | 9F1A | 02 | 0156 | M | | Application Cryptogram (AC) | 9F26 | 08 | 5E3890A05B8F8BAF | M | | Cryptogram Information Data (CID) | 9F27 | 01 | 80 | M | | Terminal Capabilities | 9F33 | 03 | 204040 | M | | Application Transaction Counter (ATC) | 9F36 | 02 | 0006 | M | | Unpredictable Number | 9F37 | 04 | 30373634 | M | | Card Product Identification Information | 9F63 | 10 | 36323130393433360020650000000000 | M | [EMV Data Elements and Tags] Transit Test Cards {#um-intro-test-cards-cup} ============================================= | Description | Card 01 | Card 02 | Card 03 | |--------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| | Test Card Scenario | PIN + Signature PIN preceding Non-matching Currency Transaction CVM limit = 9999 | PIN + Signature PIN preceding Non-matching Currency Transaction CVM not required CVM limit = 9999 | Apple Pay device wrong 9F46 Signature Non-matching Currency Transaction CVM limit = 9999 Card Sequence Number = 03 9F63 present | | Card Type | Credit | Qusi Credit | Credit | | PAN/Token | 621 094 388 801 5 | 621 094 366 600 002 5 | 817 199 997 700 004 0 | | PAR | / | / | 1D55503030323647324A524F53423858485 9553535364D5946595236564A | | Support ODA | YES | YES | YES | | PAN Len | 13 | 16 | 16 | | Curr | RMB | HKD | RMB | | Track 2 | 6210943888015= 30102010000000000000 | 6210943666000025= 30102010000000000000 | 8171999977000040= 30102010000000000000 | | CA Index | 08 | 9 | 0B | | 9F08 | 0030 | 0030 | 0030 | | 9F51 | 0156 | 0344 | 0156 | | DF71 | N/A | N/A | N/A | | 9F52 | C000 | C000 | C000 | | qUICS CVN | 01 | 01 | 01 | | 9F63 | N/A | N/A | 3831373139393939 00 80 30 40 00 00 00 00 | | 9F68 | 1020D020 | 1020D020 | 10201020 | | DF61 | 40 | 40 | 40 | | CDCVM | N/A | N/A | N/A | | 9F77 | 000000000000 | 000000000000 | 000000000000 | | 9F78 | 000000000000 | 000000000000 | 000000000000 | | 9F79 | 000000000000 | 000000000000 | 000000000000 | | 9F6B | 000000999999 | 000000999999 | 000000999999 | | DF77 | N/A | N/A | N/A | | DF78 | N/A | N/A | N/A | | DF79 | N/A | N/A | N/A | | DF72 | N/A | N/A | N/A | | RSA Len | 768 | 1024 | 1408 | | 9F46 | 04 | 04 | 94 | | 9F10 | 07010103000000010A01 | 07010103000000010A01 | 07 02 01 03000000 01 0F 07 02 00000000008030400000000000 | | 8E | 42031E031F00 | 42031E031F00 | 42031E031F00 | [Test Card Examples: Cards 01-03] | Description | Card 04 | Card 05 | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------| | Test Card Scenario | HCE device Signature Non-matching Currency Transaction CVM not required CVM limit = 9999 CDCVM performed PAR available AID=A0000003330101021111111111111110 9F63 present | Signature Non-matching Currency Transaction CVM not required CVM limit = 9999 BIN NOT in deny list | | Card Type | Qusi Credit | Credit | | PAN/Token | 621 094 366 600 000 005 6 | 621 094 344 406 6 | | PAR | / | / | | Support ODA | YES | YES | | PAN Len | 19 | 13 | | Curr | RMB | RMB | | Track 2 | 6210943666000000056=30102010000000000 | 6210943444066=30102010000000000000 | | CA Index | 0B | 0B | | 9F08 | 0030 | 0030 | | 9F51 | 0156 | 0156 | | DF71 | N/A | N/A | | 9F52 | C000 | C000 | | qUICS CVN | 01 | 01 | | 9F63 | 3632313039343336 00 20 65 00 00 00 00 00 | N/A | | 9F68 | 10201020 | 10201020 | | DF61 | 40 | 40 | | CDCVM | YES | N/A | | 9F77 | 000000000000 | 000000000000 | | 9F78 | 000000000000 | 000000000000 | | 9F79 | 000000000000 | 000000000000 | | 9F6B | 000000999999 | 000000999999 | | DF77 | N/A | N/A | | DF78 | N/A | N/A | | DF79 | N/A | N/A | | DF72 | N/A | N/A | | RSA Len | 1408 | 1152 | | 9F46 | 94 | 04 | | 9F10 | 07 02 01 03000000 01 0D A1 00000000 0000000000000000 | 07010103000000010A01 | | 8E | 42031E031F00 | 42031E031F00 | [Test Card Examples: Card 04-05] Mass Transit Models and Workflows {#um-transit-models-flows-intro} ================================================================== The Mass Transit solution supports a variety of payment models and workflows for transit fare collection and management. This section describes card-specific mass transit models and workflows. Each card type has a distinct mass transit model and transaction workflow that defines how fares are authorized, processed, and settled. Common workflows that are not card specific are also discussed. `China UnionPay` Mass Transit Workflows {#um-models-flows-cup-intro} ==================================================================== The Mass Transit solution supports single fare, aggregated fare, and debt recovery workflows for `China UnionPay` (CUP). `China UnionPay` Single Fare Transaction Workflow {#um-models-flows-cup-single-fare} ==================================================================================== The `China UnionPay` (CUP) single fare transaction workflow begins when the rider taps a payment card on a contactless terminal at a point of access to a transit system. This workflow is a Pay As You Go (PAYG) model. Tap-in and tap-out data are collected and sent to the transit system for fare calculation after a single trip. #### Figure: {#um-models-flows-cup-single-fare_fig_yqg_2g2_j3c} Single Fare PAYG Transaction Workflow ![Diagram showing Single Fare Transaction workflow](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/mass-transit/images/cup-mt-single-fare-600x425.svg/jcr:content/renditions/original) 1. The cardholder taps the card to enter the transit system. 2. The gate validates the card using offline data authentication (ODA), the card expiration date, and the deny list. 3. When the card is valid, the gate allows the passenger to enter the transit system. 4. When the ODA fails, the card is added to the deny list, and the debt recovery process begins. See [Debt Recovery Workflows](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-transit-models-flows-intro/um-models-flows-cup-intro/um-models-flows-common-debt-recovery.md ""). 5. You send an authorization request for a nominal amount. 6. When the authorization is successful, you calculate the fare for the travel period. 7. You submit a purchase request via Visa Acceptance Solutions. `China UnionPay` Aggregated Fare Workflow {#um-models-flows-cup-aggregated-fare} ================================================================================ The `China UnionPay` (CUP) aggregated fare workflow begins at the at a contactless terminal of a point of access to the transit system. The final fare that is charged is not always available at the time of travel. It is calculated at the end of a travel period, based on journeys made during that period, and typically within 24 hours. #### Figure: {#um-models-flows-cup-aggregated-fare_fig_tvf_yxr_wtb} Aggregated Fare Transaction Flow ![Diagram showing aggregated fare transaction workflow](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/mass-transit/images/cup-mt-aggregate-fare-600x655.svg/jcr:content/renditions/original) 1. The cardholder taps the card at a terminal to enter the transit system. 2. The gate validates the card using offline data authentication (ODA), the card expiration date, and the deny list. 3. You send an authorization request for a nominal amount. 4. You calculate and aggregate subsequent trip fares for the customer until the Cumulative Spend Limit (CSL) or Maximum Travel Time (MTT) is reached. 5. If the CSL or MTT is exceeded, you request an additional authorization request. 6. You submit a purchase request for the cumulative trip fares to Visa Acceptance Solutions at the end of the journey. {#um-models-flows-cup-aggregated-fare_ol_uvd_h3n_w2c} Debt Recovery Workflows {#um-models-flows-common-debt-recovery} =============================================================== Debt recovery workflows show how to use debt recovery transactions to collect outstanding debt when an aggregated end-of-day transaction is declined. Card schemes require merchants to support merchant-initiated debt recovery. This type of transaction can also be required to remove a card from a deny list. Each card scheme has its own transaction-processing rules for debt recovery retry attempts, transaction time limits, and related mass transit transactions. For more information, see each card scheme's rules for transit debt recovery retry attempts and transaction time limits. IMPORTANT Use a debt recovery transaction to remove a card from a deny list. This action must be completed within one hour of receiving the authorization approval. These debt recovery transactions are supported: * A scheduled transaction that uses the card number. * A tap-initiated transaction that uses the EMV track 2 equivalent and EMV tags created when the cardholder re-enters the transit system. * A cardholder-initiated transaction that the customer requests by contacting you. {#um-models-flows-common-debt-recovery_ul_kxv_bsd_xhc} When a debt recovery transaction is declined, you can request payment using the First Ride Risk liability model. For more information, see each card scheme's rules for mass transit transaction chargebacks. Scheduled Debt Recovery Transaction Resubmission ------------------------------------------------ A *scheduled debt recovery* transaction is a system-generated transaction that originates from your back office. This transaction typically uses the card number and references the original, end-of-day transaction that was declined. Multiple authorization resubmissions might be triggered within 14 days. #### Figure: {#um-models-flows-common-debt-recovery_fig_ibv_nh1_zhc} Scheduled Debt Recovery Workflow ![Workflow diagram showing Scheduled Debt Recovery workflow](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/mass-transit/images/system-gen-debt-recovery-flow-600x345.svg/jcr:content/renditions/original) 1. You configure your payment system to generate scheduled debt recovery authorization requests. 2. The scheduled authorizations attempt debt recovery submissions within 14 days of the initial transaction. 3. When the number of retry attempts for the scheduled debt transaction exceeds the card scheme's limit, stop further processing and keep the card on the deny list. 4. When the amount is below the debt recovery amount limit, send a sale request. 5. When the transaction is declined, keep the card on the deny list. 6. When the transaction is successful, remove the card from the deny list. Tap-Initiated Debt Recovery --------------------------- A *tap-initiated debt recovery* transaction occurs when the cardholder returns to the transit gate, and the validator recognizes a new contactless tap. You can deny the rider entrance unless the tap-initiated debt recovery transaction is attempted in real time while the cardholder is at the gate. The authorization request includes the EMV track 2 equivalent and EMV tags from the new tap, and a future capture date. #### Figure: {#um-models-flows-common-debt-recovery_fig_xpp_lr3_k3c} Tap-Initiated Debt Recovery Workflow ![Diagram showing Tap-Initiated Debt Recovery Workflow](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/mass-transit/images/tap-initiated-debt-recovery-flow-260x425.svg/jcr:content/renditions/original) 1. The cardholder taps their card to enter the transit system. 2. You submit a new authorization request using the EMV track 2 equivalent and EMV tags created by the validator and a capture date in the future. 3. When the transaction is declined, keep the card on the deny list. 4. When the transaction is successful, remove the card from the deny list. Cardholder-Initiated Debt Recovery ---------------------------------- A *cardholder-initiated debt recovery* transaction occurs when the cardholder contacts you. The method of contact depends on where the transaction occurred such as on your e-commerce website or by phone or email for a mail order or telephone order (MOTO) transaction. #### Figure: {#um-models-flows-common-debt-recovery_fig_ltd_wr3_k3c} Cardholder-Initiated Debt Recovery Flow ![Diagram showing Cardholder-Initiated Debt Recovery Flow](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/mass-transit/images/cardholder-init-debt-recov-flow-240x410.svg/jcr:content/renditions/original) 1. The cardholder contacts you through your website or by phone or email for a MOTO transaction. 2. You process a card-not-present (CNP) authorization. 3. When the request is successful, remove the card from the deny list. 4. When the request fails, leave the card on the deny list. Mass Transit Payment Services Using TMS Tokens {#um-processing-tms} =================================================================== Use TMS tokens to request these mass transit payment services: * Authorization and capture for aggregate fares and debt recovery * Sale for single fares and debt recovery * First ride risk * Stand-alone credit In card-present EMV contactless requests, include the transient token ID in the tokenInformation.jti field in place of track 2 data. When submitting a tap token creation request, you can include EMV tag-length-value (TLV) tags in the paymentInformation.fluidData.value field or as part of the payment transaction request within the pointOfSaleInformation.emv.tags field. If you send EMV tags in the tap token create request, do not send EMV tags in the payment transaction request. When EMV TLV tags are present in both the payment transaction and the token vault, `Visa Acceptance Solutions` reads the value provided in the payment transaction rather than the values stored in the vault. Mastercard EMV transactions include these three field values, which can be handled automatically: * paymentInformation.card.initiationChannel * pointOfSaleInformation.emv.cardSequenceNumber * pointOfSaleInformation.serviceCode Your account can be configured to read these values automatically from the EMV TLV tags and track 2 equivalent. When that option is enabled, do not include those three fields in EMV payment requests. If any of these values are present in both the separate fields and the EMV TLV and track 2 equivalent, `Visa Acceptance Solutions` reads the value provided in the separate fields rather than the values present in the EMV TLV and track 2 equivalent. #### Figure: Payment Processing with a Token Workflow ![Diagram showing Payment Processing with a Token workflow](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/mass-transit/images/mtt-backoffice-390x290.svg/jcr:content/renditions/original) Pre-Authorization with a Token {#um-processing-cup-pre-auth-intro} ================================================================== Use this information to process a pre-authorization. Response Field Handling ----------------------- When you receive the `AUTH_DECLINE_CAPTURE_POSSIBLE` value in the errorInformation.reason field of an authorization response, it indicates that a capture attempt will not be rejected automatically. Before processing the capture, verify that it is permitted in this scenario by reviewing the card scheme's First Ride Risk and shared‑liability rules. For more information about the field, see the errorInformation.reason field description. Endpoint {#um-processing-cup-pre-auth-intro_d7e16} -------------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments`{#um-processing-cup-pre-auth-intro_d7e25} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments`{#um-processing-cup-pre-auth-intro_d7e35} Required Fields for a Pre-Authorization with a Token {#um-processing-cup-pre-auth-reqd-fields} ============================================================================================== clientReferenceInformation.code : Set this field value to `TransitDA BAU nominal value auth`. clientReferenceInformation.partner.thirdPartyCertificationNumber : `Visa Acceptance Solutions` provides the value for this field. clientReferenceInformation.transactionId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.card.type : pointOfSaleInformation.catLevel : Set this field to `2`. pointOfSaleInformation.emv. cardSequenceNumber : pointOfSaleInformation.entryMode : Set this field to `contactless`. pointOfSaleInformation.operatingEnvironment : pointOfSaleInformation.terminalCapability : Set this field to `5`. pointOfSaleInformation.terminalId : pointOfSaleInformation.terminalPinCapability : Set this field to `0`. processingInformation.authorizationOptions.aggregatedAuthIndicator : Set this field to `true`. processingInformation.authorizationOptions.deferredAuthIndicator : Set this field to `true`. processingInformation.commerceIndicator : Set this field to `retail`. processingInformation.industryDataType : Set this field to `transit`. processingInformation.reconciliationId : tokenInformation.jti : REST Example: Pre-Authorization with a Token {#um-processing-cup-pre-auth-ex-rest} ================================================================================== Request ``` { "clientReferenceInformation": { "code": "TransitDA BAU nominal value auth", "transactionId": "12845679", "partner": { "thirdPartyCertificationNumber": "123456789012" } }, "pointOfSaleInformation": { "operatingEnvironment": "2", "terminalPinCapability": "0", "catLevel": "2", "terminalId": "12345678", "entryMode": "contactless", "terminalCapability": "5", "emv": { "cardSequenceNumber": "01" } }, "processingInformation": { "reconciliationId": "7866535268", "commerceIndicator": "retail", "industryDataType": "transit", "authorizationOptions": { "aggregatedAuthIndicator": "true", "deferredAuthIndicator": "true" } }, "orderInformation": { "amountDetails": { "totalAmount": "1", "currency": "THB" } }, "tokenInformation": { "jti": "c76392f4-cde4-11aa-b8bc-0242ac14c074" }, "paymentInformation": { "card": { "type": "062" } } } ``` {#um-processing-cup-pre-auth-ex-rest_codeblock_tms_qh4_jyz} Response to a Successful Request ``` { "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7012384708016080703137/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7012384708016080703137" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7012384708016080703137/captures" } }, "clientReferenceInformation": { "code": "TransitDA BAU nominal value auth", "transactionId": "12845679" }, "id": "7012384708016080703137", "orderInformation": { "amountDetails": { "authorizedAmount": "1.00", "currency": "THB" } }, "paymentAccountInformation": { "card": { "type": "062" } }, "paymentInformation": { "tokenizedCard": { "type": "062" }, "card": { "type": "062" } }, "processorInformation": { "approvalCode": "005290", "settlementDate": "0501", "responseCode": "00", "avs": { "code": "2" } }, "reconciliationId": "333306641171", "status": "AUTHORIZED", "submitTimeUtc": "2023-11-29T06:14:33Z" } ``` Response to a Successful Request Under First Ride Risk Liability ``` { "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7012384708016080703137" } }, "clientReferenceInformation": { "code": "TransitDA BAU nominal value auth" }, "errorInformation": { "reason": "AUTH_DECLINE_CAPTURE_POSSIBLE", "message": "Authorization Declined. Follow-on Capture can be processed." }, "id": "7078109972977125857011", "paymentInsightsInformation": { "responseInsights": { "categoryCode": "97", "category": "PAYMENT_INSIGHTS_INTERNAL_ERROR" } }, "processorInformation": { "responseCode": "58", "avs": { "code": "2" } }, "status": "AUTHORIZED" } ``` Tap-Initiated Sale for Debt Recovery with a Token {#um-processing-sale-debtrecov-tkn-intro} =========================================================================================== Use this information to process a tap-initiated sale for debt recovery with a token. A sale transaction combines an authorization and capture. When a cardholder attempts to use a blocked card at the transit reader, create a fresh debt recovery sale request using the chip data from the new tap, along with the fare amount of the previous declined authorization. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments` **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments` Required Fields for a Tap-Initiated Sale for Debt Recovery with a Token {#um-processing-sale-debtrecov-tkn-reqd-fields} ======================================================================================================================= clientReferenceInformation.code : clientReferenceInformation.partner.thirdPartyCertificationNumber : clientReferenceInformation.transactionId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.card.type : pointOfSaleInformation.catLevel : pointOfSaleInformation.emv.cardSequenceNumber : Set this field to `01`. pointOfSaleInformation.entryMode : pointOfSaleInformation.operatingEnvironment : pointOfSaleInformation.terminalCapability : pointOfSaleInformation.terminalId : pointOfSaleInformation.terminalPinCapability : processingInformation.authorizationOptions.debtRecoveryIndicator : Set this field to `true`. processingInformation.authorizationOptions.deferredAuthIndicator : Set this field to `true`. processingInformation.capture : Set this field to `true`. processingInformation.commerceIndicator : Set this field to `retail`. processingInformation.industryDataType : Set this field to `transit`. processingInformation.linkId : processingInformation.reconciliationId : tokenInformation.jti : REST Example: Tap-Initiated Sale for Debt Recovery with a Token {#um-processing-sale-debtrecov-tkn-ex-rest-cup} =============================================================================================================== Request ``` { "clientReferenceInformation": { "code": "CUP Purchase Transit", "transactionId": "12845674448", "partner": { "thirdPartyCertificationNumber": "123456789012" } }, "processingInformation": { "commerceIndicator": "retail", "industryDataType": "transit", "reconciliationId": "8897YHGTH09Y", "linkId": "7007351831836009903681", "capture": "true", "authorizationOptions": { "debtRecoveryIndicator": "true", "deferredAuthIndicator": "true" } }, "tokenInformation": { "jti": "c76392f4-cde4-11aa-b8bc-0242ac14c074" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "THB" } }, "pointOfSaleInformation": { "operatingEnvironment": "2", "terminalId": "3444", "catLevel": "2", "entryMode": "contactless", "terminalCapability": "5", "terminalPinCapability": "0", "emv": { "cardSequenceNumber": "01" } }, "paymentInformation": { "card": { "type": "062" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/payments/7012410160086081703137/voids" }, "self": { "method": "GET", "href": "/pts/v2/payments/7012410160086081703137" } }, "clientReferenceInformation": { "code": "CUP Purchase Transit", "transactionId": "12845674448" }, "id": "7012410160086081703137", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "authorizedAmount": "100.00", "currency": "THB" } }, "paymentAccountInformation": { "card": { "type": "062" } }, "paymentInformation": { "tokenizedCard": { "type": "062" }, "card": { "type": "062" } }, "processorInformation": { "approvalCode": "005290", "settlementDate": "0501", "responseCode": "00", "avs": { "code": "2" } }, "reconciliationId": "8897YHGTH09Y", "status": "AUTHORIZED", "submitTimeUtc": "2023-11-29T06:56:57Z" } ``` Merchant-Initiated Sale for Debt Recovery with a Token {#um-processing-sale-mit-tkn-intro} ========================================================================================== Use this information to process a merchant-initiated sale for debt recovery with a token. Endpoint -------- **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments` **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Sale for Debt Recovery with a Token {#um-processing-sale-mit-tkn-reqd-fields} ====================================================================================================================== clientReferenceInformation.code : clientReferenceInformation.partner.thirdPartyCertificationNumber : clientReferenceInformation.transactionId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.card.cardType : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.instrumentIdentifier.id : processingInformation.authorizationOptions.debtRecoveryIndicator : Set this field to `true`. processingInformation.authorizationOptions.deferredAuthIndicator : Set this field to `true`. processingInformation.authorizationOptions.ignoreAvsResult : processingInformation.authorizationOptions.ignoreCvResult : processingInformation.capture : Set this field to `true`. processingInformation.commerceIndicator : Set this field to `internet`. processingInformation.industryDataType : Set this field to `transit`. processingInformation.linkId : processingInformation.reconciliationId : REST Example: Merchant-Initiated Sale for Debt Recovery with a Token {#um-processing-sale-mit-tkn-ex-rest-cup} ============================================================================================================== Request ``` {     "clientReferenceInformation": { "code": "CUP Purchase Transit",         "transactionId": ""12845678",         "partner": {             "thirdPartyCertificationNumber": "123456789012"         }     },     "processingInformation": {         "commerceIndicator" : "internet",         "industryDataType": "transit",         "reconciliationId": "897YHGTHJUY", "linkId": "7007351831836009903681",         "capture": "true",         "authorizationOptions": {             "debtRecoveryIndicator": "true", "deferredAuthIndicator": "true",             "ignoreAvsResult": "true",             "ignoreCvResult": "true"             }         }     },     "paymentInformation": {         "card": {             "expirationMonth": "12",             "expirationYear": "2033",             "cardType": "062"         },         "instrumentIdentifier": {             "id": "0ABF155EB33E8FC2E0633F36CF0A0220"         }     },     "orderInformation": {         "amountDetails": {             "totalAmount": "100.00",             "currency": "THB"         }     } } ``` Response to a Successful Request ``` {     "_links": {         "void": {             "method": "POST",             "href": "/pts/v2/payments/7012397101156081303137/voids"         },         "self": {             "method": "GET",             "href": "/pts/v2/payments/7012397101156081303137"         }     },     "clientReferenceInformation": {         "code": "CUP Purchase Transit",         "transactionId": "12845678"     },     "id": "7012397101156081303137",     "orderInformation": {         "amountDetails": {             "totalAmount": "100.00",             "authorizedAmount": "100.00",             "currency": "THB"         }     },     "paymentAccountInformation": {         "card": {             "type": "062"         }     },     "paymentInformation": {         "tokenizedCard": {             "type": "062"         },         "instrumentIdentifier": {             "id": "0ABF155EB33E8FC2E0633F36CF0A0220",             "state": "ACTIVE"         },         "card": {             "type": "062"         }     "processorInformation": {         "approvalCode": "005290",         "settlementDate": "0501",         "responseCode": "00",         "avs": {             "code": "2"         }     },     "reconciliationId": "8897YHGTHJUY",     "status": "AUTHORIZED",     "submitTimeUtc": "2023-11-29T06:35:11Z" } ``` Mass Transit Follow-On Payment Services {#um-processing-followon} ================================================================= The Mass Transit solution supports these follow-on transactions: * Capture * Authorization reversal * Refund * Void a capture * Credit Capture {#um-processing-capture-intro} ====================================== Use this information to process a capture. Use the capture service to complete a pre-authorization. When a transaction is below the threshold for First Ride Risk protection, use the capture service to capture funds from a declined authorization. For more information, see [First Ride Risk](/docs/vas/en-us/urban-mobility/developer/cup/rest/mass-transit/um-intro-overview/um-workflow-first-ride-risk.md ""). Endpoint {#um-processing-capture-intro_d7e127} ---------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/captures`{#um-processing-capture-intro_d7e136} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/captures`{#um-processing-capture-intro_d7e149} The *{id}* is the transaction ID returned in the authorization response. Required Fields for a Capture {#um-processing-capture-reqd-fields} ================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Capture {#um-processing-capture-ex-rest-cup} ========================================================== Request ``` {    "clientReferenceInformation": {         "code": "TCCUP1"     },   "orderInformation": {     "amountDetails": {       "totalAmount": "5",       "currency": "THB"     }   } } ``` Response to a Successful Request ``` {     "_links": {         "void": {             "method": "POST",             "href": "/pts/v2/captures/7012404694986081603137/voids"         },         "self": {             "method": "GET",             "href": "/pts/v2/captures/7012404694986081603137"         }     },     "clientReferenceInformation": {         "code": "TCCUP1"     },     "id": "7012404694986081603137",     "orderInformation": {         "amountDetails": {             "totalAmount": "5.00",             "currency": "THB"         }     },     "reconciliationId": "333306641171",     "status": "PENDING",     "submitTimeUtc": "2023-11-9T06:47:50Z" } ``` Authorization Reversal {#um-processing-rev-intro} ================================================= Use this information to reverse an unnecessary authorization. Endpoint {#um-processing-rev-intro_d7e85} ----------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/reversals`{#um-processing-rev-intro_d7e94} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/reversals`{#um-processing-rev-intro_d7e107} The *{id}* is the transaction ID returned in the authorization response. Required Fields for an Authorization Reversal {#um-processing-rev-reqd-fields} ============================================================================== clientReferenceInformation.code : reversalInformation.amountDetails.totalAmount : reversalInformation.reason : Set this field to `Authreversal`. REST Example: Authorization Reversal {#um-processing-rev-ex-rest-cup} ===================================================================== Request ``` { "clientReferenceInformation": { "code": "FE978755" }, "reversalInformation": { "amountDetails": { "totalAmount": "999.87" }, "reason": "Authreversal" } } ``` Response to a Successful Request ``` {     "_links": {         "self": {             "method": "GET",             "href": "/pts/v2/reversals/7167830399586147504953"         }     },     "clientReferenceInformation": {         "code": "FE978755"     },     "id": "7167830399586147504953",     "orderInformation": {         "amountDetails": {             "currency": "THB"         }     },     "processorInformation": {         "responseCode": "000"     },     "reversalAmountDetails": {         "reversedAmount": "999.87",         "currency": "THB"     },     "status": "REVERSED",     "submitTimeUtc": "2024-05-27T04:10:40Z" } ``` Void a Capture {#um-processing-void-intro} ========================================== Use this information to void a capture that was submitted but not yet processed by the processor. Endpoint {#um-processing-void-intro_d7e387} ------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/captures/`*{id}*`/voids`{#um-processing-void-intro_d7e396} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/captures/`*{id}*`/voids`{#um-processing-void-intro_d7e409} The *{id}* is the transaction ID returned in the capture response. Required Fields to Void a Capture {#um-processing-void-reqd-fields} =================================================================== clientReferenceInformation.code : paymentInformation.card.expirationYear : REST Example: Void a Capture {#um-processing-void-ex-rest} ========================================================== ``` { "clientReferenceInformation": { "code": "FE5690997" }, "paymentInformation": { "card": { "expirationYear": "2033" } } } ``` ``` { "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/7025612536246445304953" } }, "clientReferenceInformation": { "code": "FE5690997" }, "id": "7025612536246445304953", "orderInformation": { "amountDetails": { "currency": "THB" } }, "status": "VOIDED", "submitTimeUtc": "2024-06-02T18:08:59Z", "voidAmountDetails": { "currency": "THB", "voidAmount": "10" } } ``` Stand-Alone Credit with a Token {#um-processing-credit-intro} ============================================================= Use this information to process a stand-alone credit with a token. A *stand-alone credit* is a credit that is not linked to a previous transaction. When you process a stand-alone credit, there is no set limit on the amount because there is no reference to the original transaction amount. There is no time limit for requesting a stand-alone credit. IMPORTANT Restrict access to the stand-alone credit service and do not make it available directly on your customer-facing interface. Instead, include the feature in your internal customer-service process to prevent misuse and make sure all requests are reviewed. When a stand-alone credit request is successful, the issuing bank for the payment card takes money out of the merchant bank account and returns it to the customer. It typically takes two to four days for the acquiring bank to transfer funds from the merchant bank account. Endpoint {#um-processing-credit-intro_d7e169} --------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/credits/`{#um-processing-credit-intro_d7e178} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/credits/`{#um-processing-credit-intro_d7e188} Required Fields for a Stand-Alone Credit with a Token {#um-processing-credit-tkn-reqd-fields} ============================================================================================= clientReferenceInformation.code : clientReferenceInformation.partner.thirdPartyCertificationNumber : clientReferenceInformation.transactionId : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : paymentInformation.card.expirationMonth : paymentInformation.card.expirationYear : paymentInformation.card.type : paymentInformation.instrumentIdentifier.id : REST Example: Stand-Alone Credit with a Token {#um-processing-credit-tkn-cup-ex-rest} ===================================================================================== Request ``` { "clientReferenceInformation": { "code": "1234567hgh8" }, "paymentInformation": { "instrumentIdentifier": { "id": "D6B858CAD38A1B7CE0531D588D0ADB5D" }, "card": { "expirationMonth": "03", "expirationYear": "2031", "type": "062" } }, "orderInformation": { "amountDetails": { "totalAmount": "225.00", "currency": "THB" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/6538345097226017503265/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/6538345097226017503265" } }, "clientReferenceInformation": { "code": "1234567hgh8" }, "creditAmountDetails": { "currency": "TBH", "creditAmount": "225.00" }, "id": "6538345097226017503265", "orderInformation": { "amountDetails": { "currency": "TBH" } }, "paymentAccountInformation": { "card": { "type": "062" } }, "paymentInformation": { "tokenizedCard": { "type": "062" }, "instrumentIdentifier": { "id": "D6B858CAD38A1B7CE0531D588D0ADB5D", "state": "ACTIVE" }, "card": { "type": "062" } }, "reconciliationId": "6538345097226017503265", "status": "PENDING", "submitTimeUtc": "2024-04-25T12:06:44Z" } ``` Refund {#um-processing-refund-intro} ==================================== Use this information to process a refund. A refund is linked to a previous capture or sale. You must request a refund within 180 days of the authorization. For `China UnionPay`, use the refund service to reverse pre-authorization completions and sales. Endpoint {#um-processing-refund-intro_d7e199} --------------------------------------------- **Production:** `POST ``https://api.visaacceptance.com``/pts/v2/payments/`*{id}*`/refunds`{#um-processing-refund-intro_d7e207} **Test:** `POST ``https://apitest.visaacceptance.com``/pts/v2/payments/`*{id}*`/refunds`{#um-processing-refund-intro_d7e220} The *{id}* is the transaction ID returned in the capture or sale response. Required Fields for a Refund {#um-processing-refund-reqd-fields} ================================================================ clientReferenceInformation.code : orderInformation.amountDetails.currency : orderInformation.amountDetails.totalAmount : REST Example: Refund {#um-processing-refund-ex-rest} ==================================================== Request ``` { "clientReferenceInformation": { "code": "FE56907" }, "orderInformation": { "amountDetails": { "totalAmount": "200", "currency": "THB" } } } ``` Response to a Successful Request ``` { "_links": { "void": { "method": "POST", "href": "/pts/v2/refunds/7025605918856084604951/voids" }, "self": { "method": "GET", "href": "/pts/v2/refunds/7025605918856084604951" } }, "clientReferenceInformation": { "code": "FE56907" }, "id": "7025605918856084604951", "orderInformation": { "amountDetails": { "currency": "THB" } }, "processorInformation": { "approvalCode": "831000" "retrievalReferenceNumber": "334813163319", "responseCode": "00" }, "reconciliationId": "7025605722066080204951", "refundAmountDetails": { "currency": "THB", "refundAmount": "200" }, "status": "PENDING", "submitTimeUtc": "2022-04-18T12:28:23Z", } ```