On This Page

Card Present Connect | Mass Transit Developer 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.
Customer Support
For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.04.1

Added Sample Test Cards. See Test Cards.
Added transaction workflows with graphics. See Single Fare Workflow and Aggregated Fare Workflow.

25.02

Transaction Types
Updated the first ride risk (FRR) transaction type descriptions.

24.01

Initial Release

Introduction to Card Present Connect | Mass Transit

Card Present Connect | Mass Transit is the
Cybersource
 solution for processing transactions using card scheme mass transit models.
Cybersource
 mass transit processing is based on the global standards established by the card schemes for a reliable, scalable, and secure EMV contactless fare collection system.
Supported card types:
  • China UnionPay International

First Ride Risk

First Ride Risk (FRR) refers to the liability for the first use of a payment credential that fails pre-authorization and might result in a refusal for travel. With FRR,
Cybersource
 allows you to capture a pre-authorization that fails. The merchant or acquirer bears responsibility for FRR.

First Ride Risk Eligibility Reason 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

This table shows the EMV tags that are designated as mandatory (M), prohibited (P), optional (O), or conditional (C).
EMV Data Elements and Tags
Data Element
EMV Tag
China UnionPay
Transaction Currency Code
5F2A
M
Application Interchange Profile
82
M
Terminal Verification Result (TVR)
95
M
Transaction Date
9A
M
Transaction Type
9C
M
Transaction Amount or Amount Authorized
9F02
M
Amount Other
9F03
M
Issuer Application Data (IAD)
9F10
M
Terminal Country Code
9F1A
M
Application Cryptogram (AC)
9F26
M
Cryptogram Information Data
9F27
M
Terminal Capabilities
9F33
M
Application Transaction Counter (ATC)
9F36
M
Unpredictable Number
9F37
M
Card Product Identification Information
9F63
M
Sample EMV Data
Tag
Length
Example Data
5F2A
02
0446
82
02
2000
95
05
0000000000
9A
03
240109
9C
01
03
9F02
06
000000001000
9F03
06
000000000000
9F10
08
0700010300000001
9F1A
02
0156
9F26
08
5E3890A05B8F8BAF
9F27
01
80
9F33
03
204040
9F36
02
0006
9F37
04
30373634
9F63
10
36323130393433360020650000000000
Example: 5F2A02044682022000950500000000009A032401099C01039F02060000000010009F0306000000 0000009F100807000103000000019F1A0201569F26085E3890A05B8F8BAF9F2701809F33032040 409F360200069F3704303736349F631036323130393433360020650000000000

Rider Benefits

Mass transit riders should experience these benefits:
  • Retail-like experience where the contactless device and the reader communicate over the contactless interface to perform a contactless transaction.
  • Fast, contactless tap to enter and exit.
  • Payment card data protection.
  • Single, combined payment for multiple trips during a set period, usually at the end of the day.
  • Ability to request journey history and corresponding receipt.
  • Travel fare total on payment card statements.
  • Similar fare collection experience on multiple transit systems in other cities and countries.

Transit System Benefits

Mass transit systems will benefit in these ways:
  • Lower ticketing overhead without ticket booths or paper tickets.
  • Ability to track riders when they tap to enter and exit.
  • Flexible fare management
    • Riders pay as they go.
    • Fares are aggregated for one payment transaction each travel period.
  • Merchant protection.
    • Encrypted payment data.
    • First Ride Risk in supported regions.
    • Debt Recovery.

Mass Transit Terminology

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.
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.
Cybersource
 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

Before integrating
Cybersource
 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
    .
  • Cybersource
     account for payment services.
  • Payment technology provider (PTP) that is integrated with
    Cybersource
     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.

Mass Transit Transactions

Cybersource
 offers these types of transactions for mass transit fare collection and management.

Single Fare

This type of transaction uses a contactless terminal at points of access to the transit service. The single fare model functions on a "pay as you go" basis, where each journey's fare is individually processed after every trip. Since the fare might not be known at the time of tapping, both tap-in and tap-out data are collected and sent to the transit system.

Figure:

Single Fare Transaction Flow
Diagram that illustrates an aggregated transit transaction.

Aggregated

This type of transaction uses a contactless terminal at points of access to the transit service. The final fare charged is not always known at the time of travel. Each fare is calculated at the end of a trip. The fares are then aggregated together and charged to the customer at the end of a travel period or when the aggregated fare limit is breaches.
The travel period is also called as Maximal Travel Time (MTT) which should not exceed beyond 14 days. The aggregated total fare limit is called as Cumulative Spend Limit (CSL). The Cumulative Spend Limit (CSL) is decided by the merchant.

Figure:

Aggregated Fare Transaction Flow
Diagram that illustrates an aggregated transit transaction.

Debt Recovery

This type of transaction retrieves outstanding debt in the event of a decline of the aggregated, end-of-day transaction. A debt recovery transaction is also required in order to remove a card from a deny list. Card schemes require you to process merchant-initiated debt recovery. You can also offer tap-initiated debt recovery at the transit entry point or cardholder-initiated debt recovery online.

Figure:

Merchant-Initiated Debt Recovery Flow
Diagram that illustrates a merchant-initiated debt recovery.

Stand Alone Credit

A
stand-alone credit
 is a credit that is not linked to a capture. There is no time limit for requesting a stand-alone credit.
When a request for a credit is successful, the issuing bank for the payment card takes money out of your merchant bank account and returns it to the customer. It usually takes two to four days for your acquiring bank to transfer funds from your merchant bank account.
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.

Test Cards

You can request these payment services for mass transit with EMV and card data:
  • Authorization and capture for aggregate fares and debt recovery
  • Sale for single fares and debt recovery
  • First ride risk
  • Stand-alone credit
Test Card Examples
Card 01
Card 02
Card 03
Overall Description
PIN + Signature
PIN preceding
Non-matching Currency Transaction
CVM limit = 9999
PIN + Signature
PIN preceding
Nonmatching 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
Additional Test Card Examples
Card 04
Card 05
Overall Description
HCE device
Signature
Nonmatching Currency Transaction
CVM not required
CVM limit = 9999
CDCVM performed
PAR available
AID=A0000003330101021111111111111110
9F63 present
Signature Nonmatching 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

Mass Transit Transaction Workflows

Each transaction type has a unique workflow.
Additional workflows:

American Express Pay As You Go Workflow

The American Express Pay As You Go (PAYG) is a delayed authorization using the Expresspay transit policy workflow. It begins when the rider taps a payment card at the fare collection terminal.

Figure:

Pay As You Go Delayed Authorization Model
Diagram of the American Express Pay As You Go Aggregated transaction model.
  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.
  5. You send an authorization request for a nominal amount. See American Express Delayed Online Authorization with EMV Data.
  6. When the authorization is successful, you calculate the fare for the travel period.
  7. At the last tap of the day, submit a follow-on capture request for the day's aggregated fare amount. For authorization and capture options, see American Express Authorization and Capture Options.

Discover Pay As You Go Workflow

The Discover Pay As You Go (PAYG) workflow begins when the rider taps a payment card at the fare collection terminal.

Figure:

Pay As You Go Model
Diagram of the Discover Pay As You Go Aggregated transaction model.
  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.
  5. You send an authorization request for a nominal amount. See Discover Authorization with EMV Data.
  6. When the authorization is successful, you calculate the fare for the travel period.
  7. When the fare is more than 15.00 USD, send an authorization or sale request for the higher amount. See Discover Sale with EMV Data.
  8. At the last tap of the day, submit a follow-on capture request for the day's aggregated fare amount.

Mastercard Pay As You Go Workflow

The Mastercard Pay As You Go (PAYG) workflow begins when the rider taps a payment card at the fare collection terminal.

Figure:

Pay As You Go Model
Diagram of the Mastercard Pay As You Go Aggregated transaction model.
  1. The cardholder taps the card to enter the transit system.
  2. The gate validates the card using Mastercard combined data authentication (CDA), 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 CDA fails, the card is added to the deny list, and the debt recovery process begins. See Debt Recovery Workflows.
  5. You send an authorization request for a nominal amount. See Mastercard Authorization with EMV Data.
  6. When the authorization is successful, you calculate the fare for the travel period and submit a sale request at the end of the travel period.

Visa Mobility and Transport Transaction Workflow

The Visa Mobility and Transport Transaction (MTT) workflow begins when the rider taps a payment card at the fare collection terminal.

Figure:

Visa Mobility and Transport Transaction Workflow
Flow diagram that describes the Visa Mobility and Transport Transaction model.
  1. The cardholder taps the card to enter the transit system.
  2. The validator checks the deny list to determine card validity, and allows the rider to enter the transit system.
  3. The back office submits an account verification request (AVR) to
    Cybersource
    . See Visa Account Verification Request (AVR) with EMV Data.
  4. When the authorization fails, the card is added to the deny list, and the debt recovery process begins. See Debt Recovery Workflows.
  5. During the travel period, the back office collects the rider's tap data to calculate the fare.
  6. At the end of the travel period, the back office submits a deferred authorization and capture request. See the Fare Calculation and Submission Workflow.

Additional Workflows

This section describes additional workflows.

Near Real-Time Workflow

The near real-time workflow begins when the cardholder taps a payment card at the validator to enter the transit system.

Figure:

Near Real-Time Workflow
Diagram illustrating the deny list flow.
  1. The validator checks the deny list for the payment card.
  2. When the card is on the deny list due to a previous failed payment, the validator does not open the gate, and the payment is processed through a debt recovery workflow. See the Debt Recovery Workflows.
  3. When the card is not on the deny list, the validator opens the transit gate for the cardholder to travel.
  4. A new transient token is generated for processing the account verification request (AVR).
  5. The back office sends an account verification request (AVR) to
    Cybersource
    .
  6. When the AVR fails, the card is added to the deny list and might be eligible for the first ride risk debt recovery.
  7. When the AVR is successful, the card data is used to track subsequent taps, calculate fares for the day, and capture the deferred authorization.

Fare Calculation and Submission Workflow

The fare calculation workflow begins at the end of the travel period.

Figure:

Visa Fare Calculation and Submission Flow
Flow diagram illustrating the process of calculating and submitting transit fares
  1. The back office calculates the fare of all rides taken during the travel period.
  2. You request a sale transaction for the accumulated fare. See Visa Deferred Sale with EMV Data.
  3. When the sale is successful, the process is complete.
  4. When the sale is declined, the card hash is added to the deny list.
  5. When the declined sale amount is above the chargeback threshold, the transaction is moved to debt recovery. See Debt Recovery Workflows.
  6. When the declined sale amount is for a first ride and below the chargeback threshold, you can request the payment using the first ride risk chargeback rules as defined by each card scheme.

Debt Recovery Workflows

A debt recovery transaction is required so that you can retrieve outstanding debt if the end-of-day transaction is declined. A debt recovery transaction is also required in order to remove a card from a deny list. You must remove the card from the deny list within one hour of receiving the authorization approval. These are the ways to recover debt:
  • Scheduled transaction, resubmitted using the card number.
  • Tap-initiated transaction using the EMV track 2 equivalent and EMV tags created when the cardholder returns to enter the transit system.
  • Cardholder-initiated transaction through an e-commerce website.
When the debt recovery transaction is declined, you can request payment using the first ride risk liability model. See the card scheme rules for mass transit transaction chargebacks.

Scheduled Debt Recovery

A scheduled debt recovery is a system-generated transaction that originates from your back office. This transaction typically references the original declined end-of-day transaction and uses the card number. Multiple authorization resubmissions might be triggered within 14 days.

Figure:

Scheduled Debt Recovery Flow
Flow diagram illustrating the merchant-initiated Visa debt recovery process.
  1. You set up a scheduled debt recovery authorization request process within your operating system.
  2. The scheduled authorization(s) attempt debt recovery submissions within 14 days of the initial transaction.
  3. When the amount exceeds the debt recovery amount limit, the card remains 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

Tap-initiated debt recovery 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 is attempted in real time while the cardholder is at the gate. The authorization request uses the EMV track 2 equivalent and EMV tags from the new tap and includes a future capture date.

Figure:

Tap-Initiated Debt Recovery Flow
Flow diagram illustrating the tap-initiated debt recovery process.
  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

Cardholder-initiated debt recovery occurs when the cardholder contacts you for debt recovery.
For e-commerce payment services, see the
Payments Developer Guide
 .

Figure:

Cardholder-Initiated Debt Recovery Flow
Flow diagram illustrating the tap-initiated debt recovery process.
  1. Cardholder contacts you through your website or by phone call.
  2. You process a card-not-present 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.

Single Fare Workflow

The single fare workflow begins when the rider taps a payment card at the fare collection terminal. It is a
pay as you go
 model, where each trip's fare is processed individually after each trip.

Figure:

Single Fare Transaction Flow
Diagram that illustrates an aggregated transit transaction.
  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.
  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
    Cybersource
    .

Aggregated Fare Workflow

This type of transaction occurs at a contactless terminal at a point of access to the transit service. The final fare charged is not always available at the time of travel. It is calculated at the end of a travel period (typically 24 hours) based on journeys made during that period.

Figure:

Aggregated Transaction Flow
Diagram that illustrates an aggregated transit transaction.
  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 Maxiumum 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
    Cybersource
     at the end of the journey.

Mass Transit Payment Services Using TMS Tokens

You can 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 the card-present EMV contactless request, include the transient token ID in the
tokenInformation.jti
 field in place of track 2 data.
When making 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,
Cybersource
 reads the value provided in the payment transaction rather than the values stored in the vault.
Mastercard EMV transactions include three field values that 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,
Cybersource
 reads the value provided in the separate fields rather than the values present in the EMV TLV and track 2 equivalent.
Merchant initiated card-not-present payment requests use the
paymentInformation.instrumentIdentifier.id
 field instead of the card number.

Figure:

Payment Processing with a Token
Diagram that show the flow of payments with tokens.

Pre-Authorization with a Token

This section describes how to process a pre-authorization.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

REST Example: Pre-Authorization with a Token Using the REST API

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"
    }
  }
}
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"
}

Mass Transit Tap-Initiated Sale for Debt Recovery with a Token

This section describes how to process a tap-initiated sale for debt recovery with a token.
A sale transaction is a bundled 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.cybersource.com
/pts/v2/payments
Production:
POST
https://api.cybersource.com
/pts/v2/payments

REST Example: Performing a Tap-Initiated Sale for Debt Recovery with a Token

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"
}

Mass Transit Merchant-Initiated Sale for Debt Recovery with a Token

This section describes how to process a merchant-initiated sale for debt recovery with a token.

Endpoint

Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Production:
POST
https://api.cybersource.com
/pts/v2/payments

REST Example: Performing a Merchant-Initiated Sale for Debt Recovery with a Token

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

You can request these follow-on transactions for mass transit:
  • Capture
  • Authorization reversal
  • Refund
  • Void a capture
  • Credit

Capture an Authorization

This section describes how to process a capture.
Use the capture service to complete a pre-authorization.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments/
{id}
/captures
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/captures
The
{id}
 is the transaction ID returned in the authorization response.

REST Example: Capturing a Pre-Authorization

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

This section describes how to reverse an authorization.
Use the authorization reversal service to reverse an unnecessary or undesired authorization.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments/
{id}
/reversals
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/reversals
The
{id}
 is the transaction ID returned in the authorization response.

Required Fields for a Mass Transit Authorization Reversal

REST Example: Reversing a Mass Transit Authorization

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"
}

Refund

This section describes how to process a refund. A refund is linked to a 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

Production:
POST
https://api.cybersource.com
/pts/v2/payments/
{id}
/refunds
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/refunds
The
{id}
 is the transaction ID returned in the capture or sale response.

REST Example: Refunding a Capture

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",
}
Response to a Failed Request for Refund When a Refund is Not Allowed for First Ride Risk
{
  "id": "7078037920207111957011",
"submitTimeUtc": "2024-02-13T05:56:33Z",
"status": "INVALID_REQUEST",
"reason": "INVALID_DATA",
"message": "Decline - The referenced request id is invalid for all follow-on transactions."
}

Voiding a Capture

This section describes how to void a capture that was submitted but not yet processed by the processor.

Endpoint

Void a Capture
Production:
POST
https://api.cybersource.com
/pts/v2/captures/
{id}
/voids
Test:
POST
https://apitest.cybersource.com
/pts/v2/captures/
{id}
/voids
The
{id}
 is the transaction ID returned in the capture response.

REST Example: Voiding a Capture

{ 
    "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"
    }
}

Credit with a Token

This section describes how to process a stand-alone credit.
IMPORTANT
Follow these guidelines to prevent unauthorized credits.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/credits/
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits/

REST Example: Credit with a Token

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"
}

Single Fare Workflow

The single fare workflow begins when the rider taps a payment card at the fare collection terminal. It is a
pay as you go
 model, where each trip's fare is processed individually after each trip.

Figure:

Single Fare Transaction Flow
Diagram that illustrates an aggregated transit transaction.
  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.
  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
    Cybersource
    .

American Express Authorization and Capture Options

You have two options for handling authorizations and captures.
Option 1:
  1. Send an authorization request for a nominal amount.
  2. During the travel period, collect the rider's tap data to calculate the aggregated fare.
  3. When the floor limit is reached, send a capture to collect the accumulated amount.
  4. After completing the capture, return to step 1 to handle subsequent trips and journeys.
Option 2:
  1. Send an authorization request for a nominal amount.
  2. During the travel period, collect the rider's tap data to calculate the aggregated fare.
  3. If the number of trips exceeds the floor limit, send a delayed online authorization.
  4. Upon completion of the delayed online authorization, return to step 1 to handle subsequent trips and journeys.
Implement the version that suits your business model. However, American Express requires your payment technology partner (PTP) to support nominal and full value authorizations during the L3 certification.

Discover Sale with EMV Data

A sale transaction comprises an authorization and capture. When the fare is more than 15.00 USD, request a sale with EMV data.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Visa Deferred Sale with EMV Data

This section describes how to process a deferred sale transaction at the end of the travel period for an aggregated payment.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Test Cards

You can request these payment services for mass transit with EMV and card data:
  • Authorization and capture for aggregate fares and debt recovery
  • Sale for single fares and debt recovery
  • First ride risk
  • Stand-alone credit
Test Card Examples
Card 01
Card 02
Card 03
Overall Description
PIN + Signature
PIN preceding
Non-matching Currency Transaction
CVM limit = 9999
PIN + Signature
PIN preceding
Nonmatching 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
Additional Test Card Examples
Card 04
Card 05
Overall Description
HCE device
Signature
Nonmatching Currency Transaction
CVM not required
CVM limit = 9999
CDCVM performed
PAR available
AID=A0000003330101021111111111111110
9F63 present
Signature Nonmatching 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

American Express Delayed Online Authorization with EMV Data

This section describes how to process an American Express delayed online authorization with EMV data for a nominal amount of 1.00 USD or more. The required function code is 100.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Visa Account Verification Request (AVR) with EMV Data

This section describes how to process a Visa account verification request (AVR) with EMV data for a zero amount.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Discover Authorization with EMV Data

A Discover authorization with EMV data is an authorization request that can be for a nominal amount of 1.00 USD or a fare amount up to 15.00 USD. Mass transit Discover transactions are supported only in the U.S.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Mastercard Authorization with EMV Data

This section describes how to process a Mastercard authorization with EMV data for a nominal amount.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Aggregated Fare Workflow

This type of transaction occurs at a contactless terminal at a point of access to the transit service. The final fare charged is not always available at the time of travel. It is calculated at the end of a travel period (typically 24 hours) based on journeys made during that period.

Figure:

Aggregated Transaction Flow
Diagram that illustrates an aggregated transit transaction.
  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 Maxiumum 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
    Cybersource
     at the end of the journey.

Reference Information

This section contains useful reference information for integrating Card Present Connect | Mass Transit.