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
These special statements are used in this document:
IMPORTANT
An
Important
statement contains information essential to
successfully completing a task or learning a concept.
WARNING
A
Warning
contains information or instructions, which, if not
heeded, can result in a security risk, irreversible loss of data, or significant cost in
time or revenue or both.
VISA Platform Connect: Specifications and Conditions for Resellers/Partners
The following are specifications and conditions that apply to a Reseller/Partner
enabling its merchants through
Cybersource for Visa Platform Connect
(“VPC”) processing
. Failure to meet any of the specifications and
conditions below is subject to the liability provisions and indemnification
obligations under Reseller/Partner’s contract with Visa/Cybersource.
Before boarding merchants for payment processing on a VPC acquirer’s connection,
Reseller/Partner and the VPC acquirer must have a contract or other legal
agreement that permits Reseller/Partner to enable its merchants to process
payments with the acquirer through the dedicated VPC connection and/or
traditional connection with such VPC acquirer.
Reseller/Partner is responsible for boarding and enabling its merchants in
accordance with the terms of the contract or other legal agreement with the
relevant VPC acquirer.
Reseller/Partner acknowledges and agrees that all considerations and fees
associated with chargebacks, interchange downgrades, settlement issues, funding
delays, and other processing related activities are strictly between Reseller
and the relevant VPC acquirer.
Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is
responsible for payment processing issues, including but not limited to, transaction
declines by network/issuer, decline rates, and interchange qualification, as may be
agreed to or outlined in the contract or other legal agreement between
Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS
OR OMISSIONS BY THE VISA PLATFORM CONNECT ACQUIRER IN PROCESSING TRANSACTIONS.
NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER
BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND
CONDITIONS IMPOSED BY THE RELEVANT VISA PLATFORM CONNECT ACQUIRER.
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:
American Express
Discover (U.S. only)
Mastercard
Visa
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
Account Verification Request (AVR)
Zero amount authorization request that you send to determine whether the
payment card is valid.
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 Validation and Certification
Work with your payment technology provider (PTP) to allocate time to complete the
message-level validation (MLV) and EMV Level 3 certification with your mass transit fare
processing system. You must pass MLV before beginning EMV Level 3 certification. You
must complete validation and certification before your system can go live.
Message-Level Validation
Message-level validation (MLV) is a script-based field-level validation against
Cybersource
specifications.
Your PTP uses amount-based test triggers to send transactions into a test environment and
the Visa Certification Management System for decryption. The test results are XML or
RESTful output,
Business Center
test transactions, and log prints.
Cybersource
validates the results with these activities:
Cross edit checks
Data element validation
Interchange compliance
Data mapping validation
EMV L3 Certification
This topic is an overview of the Level 3 accreditation with
Cybersource
and
Visa Platform Connect
.
For details on how to design an EMV Level 3 certified payment application, find
EMV
Book 3 Application Specification
at:
Certification is a formal process to validate the device and application compliance with
card scheme acceptance regulations. The certification team uses a brand test tool and simulator. The process involves:
Using a card simulator such as UL, ICC, or Fime.
Failed case analysis and resolution.
For Mastercard certification, your PTP submits results to Mastercard and pays the
costs for approved partners that Mastercard uses.
For Visa certification,
Cybersource
submits results to Visa.
Waivers from the card schemes for exceptions.
Card schemes responses or Letter of Approval (LOA) to signify acceptance and Level
3 certification.
The processes and support for Global Card Present Connect projects and direct merchant and acquirer projects are different, but the timelines are essentially the same.
Mass Transit Transactions
Cybersource
offers two types of transactions for mass transit fare
collection and management, aggregated and debt recovery.
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.
It is calculated at the end of a travel period (typically 24 hours) based on
journeys made during that period.
Figure:
Aggregated Transaction Flow
Discover Aggregated Transactions
When the cardholder taps their card for travel, initiate an aggregated transaction by
requesting an authorization for 1.00 USD that includes the
. If the issuer approves the authorization, subsequent
taps do not require an authorization. The capture amount must not exceed 15.00 USD in
the US, and the capture date must not exceed the aggregation duration of up to 14 days
from the first tap transaction.
If the aggregate total nears the maximum aggregation amount, and the next tap will cause
the aggregation amount to exceed 15.00 USD, capture the existing aggregate total. Then,
authorize the current tap for 1.00 USD to begin a new aggregation cycle, and include the
For more details about Discover aggregated transactions, see the
Discover Global Network Contactless D-PAS: Open Loop Transit Implementation Guide
.
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
Card Types and Transaction Models
These card types, transaction types, and acceptance models are supported.
American Express
Aggregated
Pay As You Go (PAYG) delayed authorization with the Expresspay transit
policy
Discover
Aggregated, and only supported in the U.S.
Pay As You Go (PAYG)
Mastercard
Aggregated
Pay As You Go (PAYG)
Visa
Aggregated
Mobility and Transport Transaction (MTT)
All Card Types
Debt Recovery
First ride risk
Merchant Initiated
Tap Initiated
Cardholder Initiated
Aggregated Model with the Token Management
Service
When you integrate aggregated acceptance models with the
Token Management Service
(
TMS
),
customer and payment data is tokenized, securely stored, and managed by
TMS
, which
simplifies your Payment Card Industry Data Security Standard (PCI DSS) compliance for
storing, processing, or transmitting cardholder information. PCI DSS compliance
requirements are for establishing and maintaining a reliable and secure payment
processing environment.
You can use
TMS
to store these types of data:
EMV track 2 equivalent
EMV tag-length-value (TLV) string of tags for use during payment authorization
Card number (
TMS
instrument identifier)
Card hash value (used within deny list management systems)
TMS
uses a cryptographic base derivation key (BDK) to create
tokens that represent the customer and payment data. You store these tokens in your
environment and databases instead of customer payment details.
The aggregated model with
TMS
begins with the first tap of the
card.
Figure:
Transit Transactions with
TMS
First Tap Process with
TMS
This process begins when the rider taps their card at the validator.
Rider taps card at the validator.
The terminal uses the Level 3 payment application to generate a card hash and checks
the deny list for the card hash.
When the card hash is on the deny list, the card is not approved for travel and the
terminal does not open the gate.
When the card hash is not on the deny list, the card is approved for travel and the
terminal opens the gate and begins the account verification request (AVR)
process.
The rider performs additional taps as required by the transit system during the
travel period.
AVR Process with
TMS
This process begins when the validator sends the transient token data to the back
office.
The validator sends this tap data to
TMS
to tokenize the
data:
Transient token, in the ID field
Card hash
Fluid data descriptor, encoding, and value
TMS
creates tokens of the tap data and stores the card hash
with the tokens.
The back office performs a verification request as required by the card scheme
transit model.
The back office uses the transient token ID for these requests:
Retrieving the token IDs for debt recovery and BIN lookup requests
Performing an AVR, deferred authorization, and follow-on transactions
End of Travel Period Process with
TMS
This process begins at the end of the travel period.
At the end of the travel period, the back office calculates the fare and sends a
deferred authorization, which can be a combined authorization and capture, using the
transient token ID in place of the card data.
If the authorization fails, the back office retrieves the card hash from
TMS
, adds the card hash to the deny list, and begins the debt
recovery process.
Debt Recovery Process with
TMS
This process begins when your back office requests debt recovery.
In accordance with the relevant card scheme rule set, the back office requests a
merchant-initiated debt recovery using the instrument identifier token ID in
place of a card number.
When debt recovery is successful, the back office uses the card hash token to
retrieve the full card hash value.
The back office removes the card hashes from the deny list.
When the debt recovery fails, the associated card hashes stay on the deny list.
Mass transit systems can have multiple accounts for each processing function.
Account 1
: This account processes tap token create requests only. For this option,
the validators communicate directly with
Cybersource
. Using a separate
account enables you to deploy a separate security key to the validator system.
Account 2
: This account processes payment requests using tokens. You can also
choose to further separate debt recovery transactions from standard payment
transactions. In that case,
account 2a
is dedicated to standard payment
transactions, and
account 2b
is dedicated to debt recovery transactions.
Account 3
: This account processes card hash retrieval requests only. The responses
include the full, unmasked card hash value. Using a separate account enables you to
deploy a separate security key to the validator system.
Account 4
: This account operates a customer service web portal where riders can
make journey history inquiries. The riders provide the card number to a hosted payment
service (such as
Cybersource
Secure Acceptance) where they register as a
user. Registration produces the
TMS
instrument identifier token
and the card scheme PAR value. These values can be used by your back-office system to
look up journey and billing information.
Figure:
Journey History Request with Token Creation
Journey History Service
Card schemes might require transit operators to provide cardholders with a journey
history service that enables the cardholder to view their journey history and receipt
information. Refer to card scheme documentation for more information about each card
scheme's requirements for journey history.
Payment Account Reference
Cybersource
supports the use of the payment account reference (PAR)
by providing the PAR value in authorization responses when a PAR is available from
the card issuer. The PAR response field is
. Using the
PAR enables you to track card accounts when digital devices, such as smart phones
and smart watches, have a network token or DPAN that the card issuer provided to the
device. You can use the PAR to provide journey history to cardholders and to match
the card account FPAN and DPAN values.
Merchant Descriptor
You can use the merchant descriptor feature to produce a transaction-specific reference
that cardholders can see on their card account statement. To use the merchant
descriptor feature, include the
merchantInformation.merchantDescriptor.name
field in your
authorization, credit, and capture requests. The value for the field must consist
solely of English characters.
Before implementing transit journey history functionality, confirm with your acquirer and card schemes that the PAR and merchant descriptor features are supported.
For documentation regarding
Cybersource
card-not-present services that you can use to support a transit system journey history
service, see the
The American Express mass transit transaction model that is American Express PAYG with
delayed authorization using Expresspay transit policy. See American Express Pay As You Go.
Characteristics of the American Express PAYG Model
The American Express Pay As You Go (PAYG) model is a delayed authorization using the Expresspay transit policy. These are the key characteristics of this model:
Journeys are multimodal.
Fares are based on distance.
Points of entry are contactless.
Accounts are verified with an authorization for a nominal amount or the maximum fare amount.
The deny list is checked so that cardholders with previously declined transactions can be blocked.
Data can be authenticated offline to confirm that the card is valid.
Multiple card taps and fares can be aggregated into a single payment.
The deny list is automatically updated every 20 minutes.
The back office records all trips and fares in order to reconstruct journeys and calculate the final fare.
When the nominal amount authorization is declined, debt recovery can be performed.
Standard follow-on payment services can be used to capture, reverse, or void
transactions.
Figure:
Pay As You Go Delayed Authorization Model
American Express Authorization and Capture Options
You have two options for handling authorizations and captures.
Option 1:
Send an authorization request for a nominal amount.
During the travel period, collect the rider's tap data to calculate the
aggregated fare.
When the floor limit is reached, send a capture to collect the accumulated
amount.
After completing the capture, return to step 1 to handle subsequent trips
and journeys.
Option 2:
Send an authorization request for a nominal amount.
During the travel period, collect the rider's tap data to calculate the
aggregated fare.
If the number of trips exceeds the floor limit, send a delayed online
authorization.
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 Mass Transit Model
The Discover mass transit transaction model is Discover Pay As You Go (PAYG).
Discover Pay As You Go
These are the key characteristics of the Discover PAYG transaction model:
Journeys are multimodal.
Fares are based on distance.
Points of entry are contactless.
Accounts are verified with an authorization for a nominal amount or the maximum fare
amount.
The deny list is checked so that cardholders with previously declined transactions
can be blocked.
Data can be authenticated offline to confirm that the card is valid.
Token Management Service
(
TMS
) option for managing
sensitive authentication data (SAD).
Multiple card taps and fares can be aggregated into a single payment.
The deny list is automatically updated every 20 minutes.
The back office records all trips and fares in order to reconstruct journeys and
calculate the final fare.
When the nominal amount authorization is declined, debt recovery can be
performed.
Standard follow-on payment services can be used to capture, reverse, or void
transactions.
Figure:
Pay As You Go Model
Mastercard Mass Transit Model
The Mastercard mass transit transaction model is Mastercard Pay As You Go. See Mastercard Pay As You Go.
Mastercard Pay As You Go
These are the key characteristics of the Mastercard Pay As You Go (PAYG) transaction
model:
Journeys are multimodal.
Fares are based on distance.
Points of entry are contactless.
Accounts are verified with an authorization for a nominal amount or the maximum fare
amount.
The deny list is checked so that cardholders with previously declined transactions
can be blocked.
Data can be authenticated offline to confirm that the card is valid.
Token Management Service
(
TMS
) option for managing
sensitive authentication data (SAD).
Multiple card taps and fares can be aggregated into a single payment.
The deny list is automatically updated every 20 minutes.
The back office records all trips and fares in order to reconstruct journeys and
calculate the final fare.
When the nominal amount authorization is declined, debt recovery can be performed.
Standard follow-on payment services can be used to capture, reverse, or void
transactions.
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
The cardholder taps the card to enter the transit system.
The gate validates the card using offline data authentication (ODA), the card
expiration date, and the deny list.
When the card is valid, the gate allows the passenger to enter the transit
system.
When the ODA fails, the card is added to the deny list, and the debt recovery
process begins. See Debt Recovery Workflows.
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
The validator checks the deny list for the payment card.
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.
When the card is not on the deny list, the validator opens the transit gate for the
cardholder to travel.
A new transient token is generated for processing the account verification request
(AVR).
The back office sends an account verification request (AVR) to
Cybersource
.
When the AVR fails, the card is added to the deny list and might be eligible for the
first ride risk debt recovery.
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
The back office calculates the fare of all rides taken during the travel
period.
When the sale is successful, the process is complete.
When the sale is declined, the card hash is added to the deny list.
When the declined sale amount is above the chargeback threshold, the transaction
is moved to debt recovery. See Debt Recovery Workflows.
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 in order to retrieve outstanding debt in the
event of a decline of the end-of-day transaction. 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:
Merchant-initiated 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 or by a phone call.
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.
Merchant-Initiated Transaction Resubmission
A merchant-initiated transaction (MIT) resubmission is a deferred authorization
that originates from your back office. This transaction typically references the
original declined end-of-day transaction and uses the card number. Visa allows up to
six authorization resubmissions within 14 days.
Figure:
Merchant-Initiated Visa Debt Recovery Flow
When the amount exceeds the debt recovery amount limit, the card remains on the
deny list.
When the transaction is declined, keep the card on the deny list.
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 may 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:
Cardholder-Initiated Debt Recovery Flow
Cardholder taps their card to enter the transit system.
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.
When the transaction is declined, keep the card on the deny list.
When the transaction is successful, remove the card from the deny list.
Cardholder-Initiated Debt Recovery
These are the scenarios for a cardholder-initiated debt recovery:
E-commerce, at your website.
Mail order or telephone order (MOTO), on a phone call.
Cardholder contacts you through your website or by phone call.
You process a card-not-present authorization.
When the request is successful, remove the card from the deny list.
When the request fails, leave the card on the deny list.
Mass Transit Payment Services Using EMV and Card Data
You can request these payment services for mass transit with EMV and card data:
Authorization for account verification and debt recovery
Sale for aggregated fares and debt recovery
Stand-alone credit
This table shows which EMV tags are:
M: mandatory
P: prohibited
O: optional
C: conditional (Send the tag when it is present in card and terminal.)
EMV Data Elements and Tags
Data Element
EMV Tag
American Express
Discover PAYG
Mastercard PAYG
Visa MTT
Transaction Date
9A
M
M
M
M
Transaction Type
9C
M
M
M
M
Transaction Currency Code
5F2A
M
M
M
M
Terminal Country Code
9F1A
M
M
M
M
Amount Authorized
9F02
M
M
M
M
Amount Other
9F03
M
M
M
M
Application PAN Sequence Number
5F34
M
P
C
O
Application Transaction Counter (ATC)
9F36
M
M
M
M
Application Interchange Profile (AIP)
82
M
M
M
M
Dedicated File (DF) Name
84
M
M
M
M
Terminal Verification Results (TVR)
95
M
M
M
M
Issuer Application Data
9F10
M
M
M
M
Application Cryptogram
9F26
M
M
M
M
Cryptogram Information Data (CID)
9F27
M
O
M
O
Terminal Capabilities
9F33
M
M
M
M
Cardholder Verification Method (CVM) Results
9F34
O
O
M
O
Unpredictable Number (UN)
9F37
M
M
M
M
Form Factor Indicator
9F6E
C*
C
O (Authorizations)
P (Refunds)
C
Mastercard Authenticated Application Data
9F60
Does not apply
Does not apply
O
Does not apply
Mastercard Kernel Identifier‐Terminal
96
Does not apply
Does not apply
O
Does not apply
*For contactless American Express transactions, if the form factor
indicator data is available on the card, the merchant, acquirer, or processor must forward this information to the issuer.
Transaction Types
When you include the transaction type in your request, the description appears in the
Business Center
and transaction reports.
Transactions are grouped into these categories:
TransitDA
: deferred-aggregated (DA) transactions, which are also known as
Visa MTT
and
Mastercard PAYG
transactions.
BAU
: business-as-usual transactions that represent no exceptions or
errors for cardholders.
FRR
: first-ride-risk transactions that occur where first-ride-risk
liability shift is being operated. These are specific to a card scheme and
region.
DR
: debt-recovery transactions initiated by the merchant or when the
cardholder taps a contactless card at a validator to enter the transit system.
DR CIT
: debt recovery customer-initiated transactions initiated by the
cardholder when they explicitly pay a debt, including e-commerce and telephone
orders.
Service
: standard transactions for completing a payment.
Error
: standard transactions for handling transaction errors.
To include the transaction type, set the
clientReferenceInformation.comments
request field to the
transaction value corresponding to the service description. These tables provide the
value for each type of transaction:
Business as Usual (BAU)
Service
Field Value
Description
authorization
TransitDA BAU zero value auth
Zero amount authorization to verify a card.
authorization
TransitDA BAU nominal value auth
Nominal value authorization to verify a card.
authorization
TransitDA BAU full value auth
Deferred aggregated authorization for the aggregated value that is
sent at the end of the travel period.
sale
TransitDA BAU full value sale
Deferred aggregated authorization and capture for the aggregated
value that is sent at the end of the travel period.
capture
TransitDA BAU capture
Capture of any business as usual authorization. Could be a nominal
authorization or full value authorization.
capture
TransitDA BAU capture (split)
Capture without a previous authorization. Used by Mastercard PAYG in
the UK.
authorization
TransitDA BAU registration auth
Zero amount authorization as part of journey history service. Could
include CVV2 and 3-D Secure 2.x.
First Ride Risk (FRR)
Service
Field Value
Description
authorization
TransitDA FRR full auth
Full amount authorization for a previous verification authorization
request that was declined. Decline response is common.
capture
TransitDA FRR capture
Forced capture of a declined authorization when FRR funding
applies.
authorization
TransitDA FRR MIT DR auth
Merchant-initiated authorization to clear a debt status after the
TransitDA FRR authorization is processed. If successful, the FRR capture
is reversed.
reversal
TransitDA FRR MIT DR reversal
Reversal sent if previous TransitDA FRR MIT DR auth was
successful.
authorization
TransitDA FRR tap DR auth
Authorization sent following a card tap to clear a debt status after
TransitDA FRR authorization is processed. If successful, the FRR capture
is reversed.
reversal
TransitDA FRR tap DR reversal
Reversal when a TransitDA FRR tap DR auth was successful.
Debt Recovery (DR)
Service
Field Value
Description
sale
TransitDA Debt recovery MIT sale FPAN
TransitDA Debt recovery MIT sale DPAN
Merchant-initiated debt recovery authorization and capture using a
FPAN or DPAN.
authorization
TransitDA Debt recovery MIT auth FPAN
TransitDA Debt recovery MIT auth DPAN
Merchant-initiated debt recovery authorization using a FPAN or
DPAN.
capture
TransitDA Debt recovery MIT capture
Merchant-initiated debt recovery capture of a previous TransitDA Debt
recovery MIT auth transaction.
sale
TransitDA Debt recovery tap sale
Tap-initiated EMV debt recovery authorization and capture.
authorization
TransitDA Debt recovery tap auth
Tap-initiated EMV debt recovery authorization.
capture
TransitDA Debt recovery tap capture
Tap-initiated EMV debt recovery capture of a previous TransitDA Debt
recovery tap auth transaction.
Cardholder-Initiated Debt Recovery (DR CIT)
Service
Field Value
Description
sale
TransitDA Debt recovery CIT Ecom sale
Cardholder-initiated debt recovery authorization and capture.
authorization
TransitDA Debt recovery CIT Ecom auth
Cardholder-initiated debt recovery authorization.
capture
TransitDA Debt recovery CIT Ecom capture
Cardholder-initiated debt recovery capture of a previous TransitDA
Debt recovery CIT Ecom auth transaction.
sale
TransitDA Debt recovery CIT Ecom 3DS2 sale
Cardholder-initiated debt recovery authorization and capture.
authorization
TransitDA Debt recovery CIT Ecom 3DS2 auth
Cardholder-initiated debt recovery authorization.
capture
TransitDA Debt recovery CIT Ecom 3DS2
capture
Cardholder-initiated debt recovery capture of a previous TransitDA
Debt recovery CIT Ecom 3DS2 auth transaction.
sale
TransitDA Debt recovery CIT Moto sale
Cardholder-initiated debt recovery authorization and capture.
American Express Account Status Check Authorization with EMV Data
This section describes how to process an American Express account status check
authorization with EMV data for a nominal amount of 1.00 USD or more. The required
function code is 190.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Required Fields for a American Express Account Status Check AVR Authorization with EMV
Data Using the REST API
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
Required Fields for a American Express Delayed Online Authorization with EMV
Data Using the REST API
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
Required Fields for a Discover Authorization with EMV Data Using the REST API
Tap-Initiated Authorization for Debt Recovery with EMV Data
This section describes how to process a tap-initiated authorization for debt recovery.
When a cardholder attempts to use a blocked card at the transit reader, create a new
debt recovery authorization request using the chip data from the new tap, along with the
fare amount of the previous declined authorization.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Required Fields for a Tap-Initiated Authorization for Debt Recovery with EMV Data Using
the REST API
Tap-Initiated Sale for Mastercard Debt Recovery with EMV Data
This section describes how to process a tap-initiated sale for Mastercard debt recovery
When a cardholder attempts to use a blocked card at the transit reader, create a new
debt recovery sale request using the chip data from the new tap, along with the fare
amount of the previous declined authorization.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Required Fields for a Tap-Initiated Sale for Mastercard Debt Recovery with EMV Data Using
the REST API
{
"_links": {
"self": {
"method": "GET",
"href": "/pts/v2/payments/650887802747651300400"
}
},
"clientReferenceInformation": {
"code": "10000575MC",
"partner": {
"solutionId": "548UHQ8Z"
},
"transactionId": "20000575MC"
},
"errorInformation": {
"reason": "PROCESSOR_DECLINED",
"message": "Decline - General decline of the card. No other information provided by the issuing bank."
},
"id": "650887802747651300400",
"pointOfSaleInformation": {
"emv": {
"tags": "9F36020015910AB58D60185BEF0247303072179F180430303031860E04DA9F580903B1BAEDFD1438BA48"
}
},
"processorInformation": {
"systemTraceAuditNumber": "162956",
"networktransactionId": "016153570198200",
"retrievalReferenceNumber": "211511162956",
"transactionId": "016153570198200",
"responseCode": "05",
"avs": {
"code": "2"
}
},
"status": "DECLINED"
}
Tap-Initiated Sale for Visa Debt Recovery with EMV Data
This section describes how to process a tap-initiated sale for Visa debt recovery. When a
cardholder attempts to use a blocked card at the transit reader, create a new debt
recovery sale request using the chip data from the new tap, along with the fare amount
of the previous declined authorization.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Required Fields for a Tap-Initiated Sale for Visa Debt Recovery with EMV Data Using the
REST API
{
"_links": {
"self": {
"method": "GET",
"href": "/pts/v2/payments/6508879024886569004002"
}
},
"clientReferenceInformation": {
"code": "10000579",
"partner": {
"solutionId": "548UHQ8Z"
},
"transactionId": "20000579"
},
"errorInformation": {
"reason": "PROCESSOR_DECLINED",
"message": "Decline - General decline of the card. No other information provided by the issuing bank."
},
"id": "6508879024886569004002",
"pointOfSaleInformation": {
"emv": {
"tags": "9F36020015910AB58D60185BEF0247303072179F180430303031860E04DA9F580903B1BAEDFD1438BA48"
}
},
"processorInformation": {
"systemTraceAuditNumber": "162971",
"networktransactionId": "016153570198200",
"retrievalReferenceNumber": "211511162971",
"transactionId": "016153570198200",
"responseCode": "05",
"avs": {
"code": "1"
}
},
"status": "DECLINED"
}
Mass Transit Payment Services Using TMS Tokens
You can use TMS tokens to request these mass transit payment services:
Authorization for account verification and debt recovery
Sale for aggregated fares and debt recovery
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
Mass Transit Mastercard Authorization with a Token
This section describes how to process an authorization with a token.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Required Fields for a Mastercard Authorization with a Token Using the REST
API
This section describes how to process a Visa deferred sale.
A sale transaction is a bundled authorization and capture. At the end of the travel
period, request a Visa deferred sale with a token for an aggregated payment.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Required Fields for a Visa Deferred Sale with a Token Using the REST API
Mass Transit Authorizations for a Tap-Initiated Debt Recovery with a Token
This section describes how to process a tap-initiated authorization for debt recovery with a token.
When a cardholder attempts to use a blocked card at the transit reader, create a fresh
debt recovery authorization 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
Required Fields for a Tap-Initiated Authorization for Debt Recovery with a Token Using
the REST API
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
Required Fields for a Tap-Initiated Sale for Debt Recovery with a Token Using the REST
API
This section describes how to process a stand-alone credit with a token.
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.
WARNING
Follow the preceding guidelines to prevent unauthorized credits.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits
Production:
POST
https://api.cybersource.com
/pts/v2/credits
Required Fields for a Stand-Alone Credit with a Token Using the REST API
{
"id": "6502857670496139204005",
"submitTimeUtc": "2022-04-18T12:42:47Z",
"status": "INVALID_REQUEST",
"reason": "INVALID_DATA",
"message": "Declined - One or more fields in the request contains invalid data"
}
Required Field for Timeout Voids
This table provides information about the field required for timeout voids.
This section describes how to void an authorization, capture, refund, or credit when you do not receive a response within the time allowed and the transaction times out. To use this feature, you must include a unique value in the
clientReferenceInformation.transactionId
field in your payment,
capture, refund, or credit request and use the same unique value for the
{
"id": "6502858209346457804004",
"submitTimeUtc": "2022-04-18T12:43:41Z",
"status": "INVALID_REQUEST",
"reason": "INVALID_DATA",
"message": "Declined - One or more fields in the request contains invalid data"
}
Mass Transit Token Management Services
Use the
Token Management Service
to create, retrieve, and delete tokens for mass
transit.
Creating a Token
This section describes how to create tokens directly from the validator or through your back office system.
When the customer taps their card, the validator generates a unique transaction
identifier that is used to create these tokens:
Transient token: tokenized EMV tag data and track2 data. Used as the transaction
ID to create the instrument identifier and payment instrument tokens, and as the
payment token for the final authorization and sale transactions. You can delete
this token after a success transit payment for the travel period.
Cybersource
stores this token for 7 days.
Instrument identifier: tokenized card number, used for follow-on payment
transactions and BIN lookup.
Payment instrument: stores the card hash that is used to identify the payment
card in the deny list.
This diagram shows the process for creating a token.
Figure:
Creating a Token
The token creation process begins when the when the cardholder taps a payment card at the
fare collection terminal.
This section describes how to use the token retrieval service to get the transient token details such as the instrument
identifier token and payment instrument token. Use the payment instrument token for
token management. Use the instrument identifier for these transactions:
Merchant-initiated debt recovery
Stand-alone credit
Endpoint
Test:
POST
https://apitest.cybersource.com
/tms/v2/taps/{id}
Production:
POST
https://api.cybersource.com
/tms/v2/taps/{id}
REST Example: Retrieve Transient Token Details Using the REST
API
REST Example: Deleting an Instrument Identifier Using the
REST API
Request
{
}
Response 204
No response body
Response 409
{
"_links": {
"paymentInstruments": {
"href": "https://apitest.cybersource.com/tms/v1/instrumentidentifiers/CD776F4472D6AC69E053AF598E0A30F3/paymentinstruments"
}
},
"errors": [
{
"type": "instrumentIdentifierDeletionError",
"message": "Action cannot be performed as the InstrumentIdentifier is associated with one or more PaymentInstruments"
}
]
}
For Visa, an AVR is performed when the card is first used in the
transit system or on a more frequent basis depending on what the PTO/PTP
requires.
2
Deferred sale for aggregated transaction
Visa
9900.00
Visa First Ride
Protection
3.1
Deferred sale for an aggregated transaction
Visa
9904.00
Response is a decline that is eligible for capture.
3.2
Follow-on capture
Visa
9904.00
Even though the amount exceeds what is allowed for captured under
Visa's First Ride Protection rules, proceed with the capture in order to
complete this test case.
Mastercard Authorization and
Capture
4.1
Authorization for an aggregated transaction
Mastercard
10.00
4.2
Follow-on capture of an aggregated transaction
Mastercard
9900.00
Debt Recovery
5.1
Deferred sale
Mastercard, Visa
9904.00
Response is a decline that is not eligible for capture. Attempt to
reclaim debt using MOTO, tap-initiated, merchant-initiated,
card-not-present debt recovery.
5.2
MOTO debt recovery
Mastercard, Visa
9601.00
Response is a decline, but it allows you to validate the Debt
Recovery payload.
6.2
Tap-initiated debt recovery
Mastercard, Visa
9904.00
Response is a decline, but it allows you to validate the Debt
Recovery payload.
7.2
Merchant-initiated debt recovery
Mastercard, Visa
9904.00
Response is a decline, but it allows you to validate the Debt
Recovery payload.
8.2
Card-not-present debt recovery with payer authentication
Mastercard, Visa
9904.00
Response is a decline, but it allows you to validate the Debt
Recovery payload.
9.2
Card-not-present debt recovery without payer authentication
Mastercard, Visa
9904.00
Response is a decline, but it allows you to validate the Debt
Recovery payload.
Follow-On Transactions
12.2
Stand-alone credit on test case 02
Visa
20.00
Illustrates your ability to process a credit for an overcharged
amount.
13.2
Void on stand-alone credit test case 12.2
Visa
9900.00
Illustrates your ability to void a stand-alone credit that was
processed incorrectly.
14
Reversal of test case 02
Visa
9900.00
Illustrates your ability to reverse an authorized amount when the
final fare is higher than what was originally authorized. After a
reversal, resubmit the correct sale amount.
Transaction Search
15.1
Deferred sale
Visa
9900.00
Ignore the response in order to simulate a timeout.
15.2
Transaction Search
—
—
The test case 15.1 should show as successful, and therefore no
further action is required. If the transaction was declined, the
transaction would be placed on the deny list, and first ride protection
or debt recovery process should be initiated.
