mVisa Receive Side & Refund
Application Program Interfaces (API)
Client Implementation Guide
Visa Supplemental Requirements
20 July 2017
RELEASE
Important Information on Confidentiality and Copyright
© 2014 Visa. All Rights Reserved.
Confidentiality Notice: This information is proprietary and CONFIDENTIAL to Visa. It is distributed to Visa
participants for use exclusively in managing their Visa programs. It must not be duplicated, published,
distributed or disclosed, in whole or in part, to merchants, cardholders or any other person without prior
written permission from Visa.
The trademarks, logos, trade names and service marks, whether registered or unregistered (collectively the
“Trademarks”) are Trademarks owned by Visa. All other trademarks not attributed to Visa are the property
of their respective owners.
Note: This document is not part of the Visa Core Rules. In the event of any conflict between any content in
this document, any document referenced herein, any exhibit to this document, or any
communications concerning this document, and any content in the Visa Core Rules, the Visa Core
Rules shall govern and control.
Disclaimers
mVisa is made available by Visa as a network solution to Visa Clients. In all cases, the Visa Client is the
service provider to a user and must ensure that all necessary licenses, registrations, notifications,
authorizations, and approvals necessary to engage in the mVisa program are obtained from the competent
authorities in the Client‘s local jurisdiction. This mVisa Program Implementation Guide is strictly for
information purposes only and is not an approval to commercially launch an mVisa program.
Visa may at any time change or remove any of the attributes, requirements and functional specifications of
mVisa or withdraw the mVisa program entirely. Changes and enhancements to mVisa are made
continuously and are communicated to Clients through periodic Visa communications and as updates to
this mVisa Program Implementation Guide and other related documents.
Visa is not responsible for your use of the information contained herein (including errors, omissions,
inaccuracy or non-timeliness of any kind) or any assumptions or conclusions you might draw from its use.
Visa makes no warranty, express or implied, and explicitly disclaims the warranties of merchantability and
fitness for a particular purpose, any warranty of non-infringement of any third party's intellectual property
rights. To the extent permitted by applicable law, Visa shall not be liable to a client or any third party for
any damages under any theory of law, including, without limitation, any special, consequential, incidental
or punitive damages, nor any damages for loss of business profits, business interruption, loss of business
information, or other monetary loss, even if advised of the possibility of such damages.
For More Information
Note: For more details on mVisa or about this guide, please contact your Regional Visa Client Support
Services Representative.
mVisa Receive Side API - Client Implementation Guide
Contents
Contents.......................................................................................................................................................................... 2
Tables ............................................................................................................................................................................... 4
Figures ............................................................................................................................................................................. 5
About This Guide ......................................................................................................................................................... 7
Audience for this guide .......................................................................................................................................................... 7
Key Terms ....................................................................................................................................................................... 9
Related Publications .................................................................................................................................................. 11
1
Overview ................................................................................................................................................................ 13
1.1 Receive Side APIs .......................................................................................................................................................... 14
1.2 Refund APIs..................................................................................................................................................................... 14
1.3 Benefits of Implementing APIs ................................................................................................................................ 15
2
Transaction Flow of the APIs ............................................................................................................................ 16
2.1 Receive Merchant Payment API .............................................................................................................................. 16
2.2 Receive Cash In API...................................................................................................................................................... 18
2.3 Receive Cash Out API .................................................................................................................................................. 20
2.4 Merchandise Return API ............................................................................................................................................ 21
2.5 Merchandise Return Reversal API .......................................................................................................................... 22
3
Implementation Considerations ..................................................................................................................... 23
3.1 Forms, Licenses, and Registration .......................................................................................................................... 23
3.2 Reporting and Settlement ......................................................................................................................................... 25
3.3 Dispute Managment.................................................................................................................................................... 25
3.4 API Sandbox Testing.................................................................................................................................................... 25
3.5 API Sandbox VisaNet Certification Management (VCMS) Testing ............................................................ 25
3.6 API Production Launch ............................................................................................................................................... 26
4
API Onboarding .................................................................................................................................................. 27
4.1 Step 1: Complete Client Onboarding Form ........................................................................................................ 27
4.2 Step 2: Setup Mutual SSL Authentication ........................................................................................................... 28
5
API Development................................................................................................................................................ 28
5.1 Managing Decryption of Data Elements.............................................................................................................. 28
July 21, 2017
Visa Confidential
2
Content
mVisa Receive Side API - Client Implementation Guide
5.2 Managing Encryption of Data Elements .............................................................................................................. 29
5.3 Exception Handling ...................................................................................................................................................... 29
5.3.1
HTTP 400 – Inability to process payload ...................................................................................................... 30
5.3.2
HTTP 500 – System Error .................................................................................................................................... 31
5.4 Handling of Advices..................................................................................................................................................... 32
6
5.4.1
Acquirer Timeout................................................................................................................................................... 32
5.4.2
VIP Reject ................................................................................................................................................................. 33
5.4.3
STIP Decline Advice .............................................................................................................................................. 35
5.4.4
STIP Decline Advice (Velocity Exceeded)...................................................................................................... 35
API Specifications ............................................................................................................................................... 37
6.1 Receive Merchant Payment API.......................................................................................................................... 37
6.1.1
Receive Merchant Payment API Request ..................................................................................................... 37
6.1.2
Receive Merchant Payment API Response .................................................................................................. 41
6.2 Receive Cash In API...................................................................................................................................................... 44
6.2.1
Receive Cash In API Request............................................................................................................................. 44
6.2.2
Receive Cash In API Response.......................................................................................................................... 47
6.3 Receive Cash Out API .................................................................................................................................................. 48
6.3.1
Receive Cash Out API Request ......................................................................................................................... 48
6.3.2
Receive Cash Out API Response ...................................................................................................................... 51
6.4 Advices API...................................................................................................................................................................... 53
6.4.1
7
Advice Message Specification .......................................................................................................................... 53
Sample Codes ...................................................................................................................................................... 55
7.1 Receive Merchant Payment API Sample Code .................................................................................................. 55
7.2 Receive Cash In API Sample Code.......................................................................................................................... 56
A.1 Receive Cash Out API Sample Code ...................................................................................................................... 57
7.3 Receive Merchant Payment Advice Sample Code ........................................................................................... 59
7.4 Receive Cash In Advice Sample Code ................................................................................................................... 61
7.5 Receive Cash Out Advice Sample Code ............................................................................................................... 63
8
Reference Codes ................................................................................................................................................ 65
8.1 Response Code ............................................................................................................................................................ 65
July 21, 2017
Visa Confidential
3
mVisa Receive Side API - Client Implementation Guide
Tables
Table 1–1:
Description of the Service Offerings ......................................................................................................... 13
Table 1–2:
Overview of the Receive Side APIs ............................................................................................................ 14
Table 1–3:
Overview of the Refund APIs ....................................................................................................................... 14
Table 3–1:
Forms .................................................................................................................................................................... 23
Table 4–1:
Receive Side API Client Onboarding Form: Key Information .......................................................... 27
Table 4–2:
Receive Side API Client Onboarding: Information to client ............................................................. 27
Table 5–1:
Receive Side API Response Code ............................................................................................................... 29
Table 6–1:
Receive Side API TransactionTypes ........................................................................................................... 37
Table 6–2:
Advice Types ...................................................................................................................................................... 53
Table 7–1:
Receive Merchant Payment API Request Sample Code .................................................................... 55
Table 7–2:
Receive Merchant Payment API Response Sample Code (HTTP 200) .......................................... 55
Table 7–3:
Receive Merchant Payment API Response Sample Code (HTTP 400/500) ................................ 56
Table 7–4:
Receive Cash In API Request Sample Code ........................................................................................... 56
Table 7–5:
Receive Cash In API Response Sample Code (HTTP 200) ................................................................. 57
Table 7–6:
Receive Cash In API Response Sample Code (HTTP 400/500) ........................................................ 57
Table 7–7:
Receive Cash Out API Request Sample Code ........................................................................................ 57
Table 7–8:
Receive Cash Out API Response Sample Code (HTTP 200) ............................................................. 58
Table 7–9:
Receive Cash Out API Response Sample Code (HTTP 400/500) .................................................... 58
Table 7–10: Receive Merchant Payment API – STIP Decline Advice Sample Code ......................................... 59
Table 7–11: Receive Merchant Payment API – VIP Reject Advice sample code ............................................... 59
Table 7–12: Receive Cash In API – STIP Decline Advice Sample Code ................................................................. 61
Table 7–13: Receive Cash In API – VIP Reject Advice sample code....................................................................... 61
Table 7–14: Receive Cash Out API – STIP Decline Advice Sample Code ............................................................. 63
Table 7–15: Receive Cash Out API – VIP Reject Advice sample code ................................................................... 63
July 21, 2017
Visa Confidential
4
Content
mVisa Receive Side API - Client Implementation Guide
Figures
Figure 2–1:
Receive Merchant Payment API Flow ....................................................................................................... 16
Figure 2–2:
Receive Cash In API Flow............................................................................................................................... 18
Figure 2–3:
Receive Cash Out API Flow ........................................................................................................................... 20
Figure 2–4:
Merchandise Return API Flow ..................................................................................................................... 21
Figure 2–5:
Merchandise Return Reversal API Flow ................................................................................................... 22
Figure 5–1:
HTTP 400 – Inability to process payload ................................................................................................. 30
Figure 5–2:
HTTP 500 – System Error ............................................................................................................................... 31
Figure 5–3:
Acquirer Timeout.............................................................................................................................................. 32
Figure 5–4:
VIP Reject ............................................................................................................................................................ 33
Figure 5–5:
STIP Decline Advice ......................................................................................................................................... 35
Figure 5–6:
STIP Decline Advice (Velocity Exceeeded) .............................................................................................. 35
July 21, 2017
Visa Confidential
5
mVisa Receive Side API - Client Implementation Guide
THIS PAGE INTENTIONALLY LEFT BLANK.
July 21, 2017
Visa Confidential
6
About
mVisa Receive Side API - Client Implementation Guide
About This Guide
For any financial services provider, payments are the gateway to and foundation of the customer
relationship. mVisa is an interoperable mobile payment solution that adds robust and scalable payment
functionality to accounts from participating clients to strengthen this foundation. The mVisa solution is
adapted for a cardless, digital world and serves many needs and applications: various merchant payment
use cases, person-to-person money transfer, deposits and withdrawals, and cardless interaction with
existing Visa infrastructure. mVisa is an acceptance mark, and delivers its value by combining the power
of ubiquitous mobile connected devices with "push payment" as the primary underlying transaction.
To support service providers easily implement mVisa, a set of Application Program Interfaces (APIs) is
made available. These APIs can be used to faciliate the receiving leg of an mVisa Original Credit
Transaction (OCT) message.
This guide provides the detailed technical specifications of the mVisa-related APIs.
Audience for this guide
The mVisa API technical specifications and other information in this guide are intended for Visa Clients
participating in the mVisa program and wishing to use the API services. It is a reference guide for issuer
and acquirer staff that manages the technical implementation and ongoing support of an mVisa
program.
July 21, 2017
Visa Confidential
7
mVisa Receive Side API - Client Implementation Guide
THIS PAGE INTENTIONALLY LEFT BLANK.
July 21, 2017
Visa Confidential
8
Key Terms
mVisa Receive Side API - Client Implementation Guide
Key Terms
Term
Definition
API
Application Programming Interface, Set of pre defined protocols to
transact with Visa over HTTP layer.
EAS
Extended Access Server. Provides secure connnectivy to VisaNet.
Edit Package
Visa proprietary software available to Visa clients for processing
clearing and settlement transaction files sent to, and recevied from
VisaNet
VFES
Visa File Exchange Service. Option to securely exchange files with Visa.
Protocol supported include SFTP, HTTPS and Connect:Direct Secure
plus
VROL
Visa Resolve Online. An automated service that supports management
of transaction dispute lifecycle.
VOL
Visa Online. Offers Visa members a secured access to the information
and tools.
VSS
Visa settlement service
VDP
Visa Developer Portal. Offers mVisa send side API. Access to Refund
API
OCT
Original Credit Transaction. API exposed by visa to push payments for
a card/merchant.
Issuer
Issuer of the consumer who is also the originator of the OCT
transaction. This is also referred to as the Originater in the case of
merchant payment and cash out.
Cash in transaction is originated by the agent.
Acquirer
July 21, 2017
Merchant or agent Acquirer and also the recipient of the OCT
transaction. This is aslo referred to Recipient Institution. Cash in
transaction is originated by the agent. And recipient in this case is the
consumer.
Visa Confidential
9
THIS PAGE INTENTIONALLY LEFT BLANK.
July 21, 2017
Visa Confidential
10
Related Publications
mVisa Receive Side API - Client Implementation Guide
Related Publications
Title
mVisa
Guide
Description
Product
Implementation
Provides product description, business considerations and
implementation information required to implement an mVisa
program.
mVisa Brand Standards
Provides the branding rules, brand usage and brand specifications for
the mVisa program.
mVisa Program Registration Form
Information to be provided by issuers and acquirers to Visa to
participate in the mVisa program.
mVisa Mobile User Experience Guide
(USSD, Mobile app)
Provides the user experience on the mobile device deployed by issuers
and acquirers participating in the mVisa program.
Visa
International
Regulations (VIOR)
Visa network participation and operating rules.
Operating
VIP system SMS POS, technical
specifications volume 1 & 2
July 21, 2017
VisaNet specification
Visa Confidential
11
THIS PAGE INTENTIONALLY LEFT BLANK.
July 21, 2017
Visa Confidential
12
mVisa Receive Side API - Client Implementation Guide
1
Overview
To facilitate the implementation of mVisa, Visa provides mVisa Receive Side API specification (the
Specification) to clients who implement a set of outbound RESTful APIs (Receive Side APIs) so that Visa
can call these APIs to request clients to process the transactions over the Internet. Clients have the
option of implementing these APIs with JSON to receive enhanced OCT messages through a secure
internet connection.
Table 1–1:
Description of the Service Offerings
Function
Description
Transaction Processing
Visa Receive Side API Server
Refund Processing

Faciliates the routing of merchant payment, cash in and cash out requests to the
Acquirer by call Receive Side APIs developed by Acquirer in accordance with the
Specification.

Any advices generated by VIP as a result of exception will also be sent to Acquirer by
calling Receive Side APIs developed by Acquirer in accordance with the Specification.
Visa Send Side API Server

Back office Reports
Facilitates initiation of refund transaction to the consumer by using Visa APIs
Visa File Exchange Service (VFES)
Back office reports (SMS raw data) is accessible via VFES. Uses SFTP or HTTPS for sending
of reports.
Settlement Reports
Extended Access Server (EAS)
Extended Access Server (EAS) uses the existing TCP/IP connectivity between VisaNet and
client’s host for delivering settlement report (VSS)
Dispute Management
Visa Resolve Online (VROL)
Reviewing/responding to disputes raised by Issuer.
The following transactions are supported in Receive Side APIs :

Merchant payments (MP)

Cash-in (CI)

Cash-out (CO)
July 21, 2017
Visa Confidential
13
In addition, refund initiation can be implement using the following API:

Merchandise refund

Merchandise refund reversal
1.1
Receive Side APIs
The following table provides an overview of the supported Receive Side APIs.
Table 1–2:
Overview of the Receive Side APIs
APIs
Description
Receive
Payment
merchant
Receive cash in
Receive cash out
1.2

Receiving payment to a merchant for goods or services purchased, either face-toface or remote. Transaction initiated by a consumer.

Results in funds being credited to the merchant account.

Receiving request to deposit cash into consumer account at an agent. Transaction
initiated by an agent.

Results in funds being credited to the customer’s account.

Receving request to withdraw cash from consumer account at an agent. Transaction
initiated by a consumer.

Results in funds being credited to the agent’s account.
Refund APIs
The following table provides an overview of the supported Visa refund APIs.
Table 1–3:
Overview of the Refund APIs
APIs
Description
Merchandise return

Initiates a refund (full or partial) sales amount to the customer. A merchant may, at its
discretion, process a credit into consumer account when a valid transaction was
previously processed. This occurs when the consumer cancels the purchase, or returns
the goods in part or in full, or the merchant agrees to return a part of the payment.
Initiates a refund to the consumer.

Results in funds being credited to the customer account.
July 21, 2017
Visa Confidential
14
mVisa Receive Side API - Client Implementation Guide
APIs
Description
Merchandise
reversal
1.3
return

This transaction is used to reverse a refund amount that was sent to the customer.

Results in funds being returned to the merchant’s account.

This API can only be used when there is an associated merchandise return transaction.
Benefits of Implementing APIs
The mVisa Receive Side APIs have the following benefits:

Reduces overall implementation costs, timelines, and complexities especially for those
environments that are not familiar with traditional VisaNet payment processing or support
VisaNet processing but do not have a Single-Message System (SMS) infrastructure.

Provides a solution that is easier to integrate with consumer/agent/merchant applications.

Provides greater flexibility. Clients can use all the APIs or select those that best meet their
business needs.
Clients will however be required to review their operational processes for settlement, reconciliation and
chargeback.
July 21, 2017
Visa Confidential
15
2
Transaction Flow of the APIs
This chaper provides information on how each API works. It outlines the transaction flow of each of the
API
2.1
Receive Merchant Payment API
The Receive Merchant Payment API is used to receive the merchant payment sent by the Sending
insititution. The Acquirer credits the Merchant’s account with the funds.
Figure 2–1: Receive Merchant Payment API Flow
1. Consumer makes a purchase of goods or services at a merchant that accepts mVisa for payment.
The transaction is initated via mobile device.
2. Consumer’s instructions reaches the Issuer’s processing system. The system confirms the consumer’s
request and initiates OCT request1 to VisaNet.
3. VisaNet routes the transaction request to the Acquirer’s processing system with API Request2
payload.
1 OCT request can be initiated either as SMS OCT or API. Refer to
https://developer.visa.com/products/visa_direct/reference#visa_direct__mvisa for more details about mVisa Send Side API
2 HTTP request https://{host}:{port}/pushpayment/transactions/receive/p2m. The host and port number are configured
during the onboarding.
July 21, 2017
Visa Confidential
16
mVisa Receive Side API - Client Implementation Guide
4. Acquirer’s processing system validates the merchant credentials and transaction, records payment
favoring the merchant. Acquirer returns HTTP 2003 with response payload to Visa.
5. The response message is routed from the Acquirer to the Issuer over VisaNet.
6. Acquirer’s processing system also simultaneously triggers confirmation message to the merchant’s
device.
7. Issuer’s processing system completes the transaction by debiting the consumer’s account and it also
triggers a confirmation message to the consumer’s mobile device.
8. On receipt of the notifications, the merchant gives the consumer goods and services and the
transaction is complete.
3 Refer to exception handling for other HTTP response code.
July 21, 2017
Visa Confidential
17
2.2
Receive Cash In API
The Receive Cash In API is used to receive cash deposit request initiated by the agents. The
Issuer credits the consumer’s account with the funds.
Figure 2–2: Receive Cash In API Flow
1. Consumer approaches the mVisa agent for cash deposit into his account. Agent initiates the cashin transaction via their mobile device by entering the consumer’s PAN.
2. Agent’s instructions reaches the Acquirer’s processing system. The system confirms the agent’s
request and initiates OCT request4 to VisaNet.
3. VisaNet routes the transaction request to the Issuer’s processing system as API Request5.
4. Issuer’s processing system validates the consumer’s credentials and then credit consumer account.
Issuer returns HTTP 2006 with response payload to Visa.
4 OCT request can be initiated either as SMS OCT or API. Refer to
https://developer.visa.com/products/visa_direct/reference#visa_direct__mvisa for more details about mVisa Send Side API
5 HTTP request https://{host}:{port}/pushpayment/transactions/receive/ci. The host and port number are configured during
the onboarding.
6 Refer to exception handling for other HTTP response code.
July 21, 2017
Visa Confidential
18
mVisa Receive Side API - Client Implementation Guide
5. The response message is routed from the Issuerto the Acquirer over VisaNet.
6. Issuer processing system also simultaneously triggers confirmation message to the consumer’s
device.
7. Acquirer processing system completes the transaction by debiting the agent’s account and it also
triggers a confirmation message to the agent’s mobile device.
8. On receipt of the notifications, the consumer gives the cash to the agent and the transaction is
complete.
July 21, 2017
Visa Confidential
19
2.3
Receive Cash Out API
The Receive Cash Out API is used to receive cash outrequest initiated by the consumer. The Acquirer
credits the agent’s account with the funds.
Figure 2–3: Receive Cash Out API Flow
1. Consumer approaches the mVisa agent for cash withdrawal from his account. Consumer initiates
the cash-out transaction via the mobile device.
2. Consumer’s instructions reaches the Issuer processing system. The system confirms the consumer’s
request and initiates OCT request7 to VisaNet.
3. VisaNet routes the transaction request to the Acquirer processing system as API Request8.
4. Acquirer processing system validates the agent’s credentials and then credit agent account. Acquirer
returns HTTP 2009 with response payload to Visa.
5. The response message is routed from the Acquirer to the Issuer over VisaNet.
7 OCT request can be initiated either as SMS OCT or API. Refer to
https://developer.visa.com/products/visa_direct/reference#visa_direct__mvisa for more details about mVisa Send Side API
8 HTTP request https://{host}:{port}/pushpayment/transactions/receive/co. The host and port number are configured during
the onboarding.
9 Refer to exception handling for other HTTP response code.
July 21, 2017
Visa Confidential
20
mVisa Receive Side API - Client Implementation Guide
6. Acquirer processing system also simultaneously triggers confirmation message to the agent’s
device.
7. Issuer processing system completes the transaction by debiting the consumer’s account and it also
triggers a confirmation message to the consumer’s mobile device.
8. On receipt of the notifications, the agent gives the cash to the consumer and the transaction is
complete.
2.4
Merchandise Return API
The merchandise return API is used to a refund (full or partial) sales amount to the customer. The Issuer
credits the consumer’s account with the funds.
The flow below describes the refund process if the Issuer is setup to receive refund online. In the case
where Issuer processes Base II refund, it will only be sent end of day for processing. Notification to
consumer will not happen in this instance.
Figure 2–4: Merchandise Return API Flow
1. A consumer has come to an agreement with the merchant to cancel a purchase and be refunded.
Merchant initates a refund transaction, entering the amount in part of in full.
2. Merchant’s instructions reaches the Acquirer’s processing system10. The system confirms the
merchant’s request and originates merchandise refund API to Visa.
10 Acquirer should ensure that processes and checks are put in place to ensure that merchant is refunding to a previously
processed payment.
July 21, 2017
Visa Confidential
21
3. VisaNet routes the transaction request to the Issuer’s processing system if the Issuer is setup to
receive the refund request online.
4. Issuer’s processing system validates the refund request transaction, records payment favoring the
consumer either online or offline. Issuer sends approval response to Visa.
5. The response message is routed from the Issuer to the Acquirer over VisaNet.
6. Acqurier’s processing system completes the transaction by debiting the merchant’s account and it
also triggers a confirmation message to the merchant’s mobile device.
7. On receipt of the notifications, the consumer returns the goods and services to the merchant (if
applicable)
Note: IRF: Issuer is debited, and Acquirer is credited. Settlement: Issuer is credited and
Acquirer is debited
2.5
Merchandise Return Reversal API
The merchandise return reversal API is used to reverse a refund that was processed previously. This API
results in funds being returned to the merchant’s account. Return reversal API is only valid if the
transaction is sent within the same day.
The flow below describes the refund reversal process if Issuer is setup to receive refund onlne. In the case
where Issuer processes Base II refund, it will only be sent at end of day for processing. Notification to
consumer will not happen in this instance.
Figure 2–5: Merchandise Return Reversal API Flow
July 21, 2017
Visa Confidential
22
mVisa Receive Side API - Client Implementation Guide
1. Merchant initates a refund reversal transaction, cancelling a refund transaction.
2. Merchant’s instructions reaches the Acquirer’s processing system. The system confirms the
merchant’s request and originates merchandise refund reversal API to Visa.
3. VisaNet routes the transaction request to the Issuer processing system.
4. Issuer processing system validates the refund reversal request transaction, debiting the requested
amount from the consumer’s account. Issuer sends approval response to Visa.
5. The response message is routed from the Issuer to the Acquirer over VisaNet.
6. Issuer processing system also simultaneously triggers confirmation message to the consumer’s
device.
7. Acquirer processing system completes the transaction by crediting the merchant’s account and it
also triggers a confirmation message to the merchant’s mobile device.
Note: IRF: Issuer is credited, and Acquirer is debited. Settlement: Issuer is debited and Acquirer
is credited
3
Implementation Considerations
This chapter provides the clients with an overview of the implementation considerations associated with
using the Receive Side APIs.
3.1
Forms, Licenses, and Registration
The following table outlines the forms, licenses, and registration activities for clients implementing
Receive Side API. Client must complete any required form to participate in the mVisa program. Visa
Account Representative should be contacted for information on obtaining any necessary forms and/or
licenses.
Table 3–1:
Forms
Form
mVisa Program
Form (PRF)
July 21, 2017
Requirements
Registration
Mandatory
All acquirers (recipient institution) must complete this form prior to beginning
a mVisa program.
Visa Confidential
23
Form
Requirements
Visa Acquiring Licenses
Mandatory
Each region needs to be aware of the requirements in their markets related to
Visa acquiring licenses. A client wanting to participate in mVisa acquiring,
should be eligible to acquire in that country.
BIN License Agreement (for new
SMS Issuing BIN)
Mandatory
The BIN License Agreement is used to request a new BIN or change the
licensing status of an existing BIN.
The Acquirer should use a new BIN for supporting mVisa merchant payment
and cash out, and may request Visa to assign same BIN ranges for merchant
PAN and agent PAN. VisaNet will decline any merchant payment or cash-out
transaction to a PAN outside the range setup on VisaNet
The recipient BIN will also be setup on VisaNet to allow origination of refund
transaction.
Client
Information
Questionnaire (CIQ)
Mandatory
mVisa Receive Side API - Client
Onboarding Form
Mandatory
mVisa Refund API – Client
Onboarding Form
Mandatory
mVisa Receive Side API Server
Certificate
Mandatory
mVisa Refund API Certificate
Signing Request Form
Mandatory
Third Party Agent Registration
Conditional
A CIQ will need to be completed by the mVisa acquirer for configuration and
installation of the BIN at Visa
Required for client using any of the Receive Side APIs
Required for application promotion to Sandbox-VCMS for refund API. This is
an online request that is available on Visa Developer Portal (VDP) dashboard
Client uses mVisa Receive Side API will have to provide server certificate signed
by an authorized Certificate Authority (CA).
Certificate Signing Request (CSR) for obtaining a valid client certificate from
Visa. This is an online request that is available on Visa Developer Portal (VDP)
dashboard.
Required if the mVisa acquirer is using a third party agent in the management
of any aspect of their mVisa program.
July 21, 2017
Visa Confidential
24
mVisa Receive Side API - Client Implementation Guide
3.2
Reporting and Settlement
While APIs can be used to receive mVisa requests, traditional VisaNet channels must be used for
settlement and reconciliation. VSS Settlement reports (which can be used to understand settlement
positions) can be delivered to existing Acquirers through an existing and standard VisaNet endpoint
connection.
Clients may receive SMS reports and raw data (which can be used for reconciliation) via Visa File
Exchange Service (VFES) which is an internet-based option used to securely exchange files with Visa.
The protocol supported includes SFTP, HTTPS and Connect:Direct Secure Plus. Please contact your Visa
Representative for details.
Clients may also opt to receive SMS reports and raw data using VOL.
3.3
Dispute Managment
Visa Resolve Online (VROL) is used to support dispute resolution for an mVisa push payment. The
originating institution can initiate a dispute if it meets the criteria. The Acquirer may refute the dispute
by responding in VROL. Clients must refer to the Visa Core Rules & Visa Product and Service Rules for
the time limits, chargeback and representment requirements. Clients should also refer to mVisa Program
Implementation Guide for more details on dispute resolution process.
In order to process disputes, the recipient BIN will need to subscribe to SMS VROL. This setup process
follows normal business-as-usual procedures. The Visa Representative will work with the client to ensure
that the BIN is properly setup to support dispute resolution.
3.4
API Sandbox Testing
Once API development has been completed, clients can proceed with integration testing. API integration
testing takes place in an environment call the Sandbox.
The objective of Sandbox testing is to ensure the recipient interface can properly receive and respond
to the messages, as well as managing exceptions associated to the mVisa Receive Side API and refund
API. Test scripts will be provided for guiding the clients to complete the testing. VCMS certification
testing will only be arranged after the Sandbox testing is successfully completed.
3.5
API Sandbox VisaNet Certification Management (VCMS) Testing
Once basic Receive Side API Sandbox integration testing has been completed successfully, clients are
to perform end-to-end testing in the VisaNet Certification Management Testing (VCMS) environment
before going live.
July 21, 2017
Visa Confidential
25
The testing approach for VCMS testing are as follow:


Receive Side API: This is an attended certification testing administrated by the Global Client
Testing (GCT).
Refund API: VCMS environment will be setup for client to perform self testing via VDP portal.
Certification with Visa is not required.
In both cases, the testing environment allows the clients to test all components in the transaction
lifecycle all the way through settlement and exception management.
3.6
API Production Launch
It is recommended that the client begins its mVisa program with a pilot run prior to mass rollout. The
pilot will enable them to ensure that all aspects of the program are working as planned including
reconciliation, customer service, and operations.
July 21, 2017
Visa Confidential
26
mVisa Receive Side API - Client Implementation Guide
4
API Onboarding
This chapter briefly describes the onboarding process with Receive Side APIs.
For onboarding and testing of refund APIs, clients should register at the Visa Developer Portal. Please
visit the website portal for details - https://developer.visa.com/vdpguide
4.1
Step 1: Complete Client Onboarding Form
Clients are required to complete the Receive Side API – Client Onboarding Form, providing information
about the client and the setup required to be configured. Separate forms are required to be completed
for onboarding to Sandbox, VCMS and Production.
The following table contains some of the key information that have to be provided to complete the
setup:
Table 4–1:
Receive Side API Client Onboarding Form: Key Information
BIN
The recipient BIN to be setup to receive the mVisa transactions.
BIN ranges
The BIN ranges that are allowed to receive mVisa transactions (i.e. merchant
payment, cash out).
Recipient base URL
URL of the recipient to be used by Visa to send HTTP call.
This is in the format of https://{host}:{port}/{path}/
Port 443 should be used.
Client public domain/List of IP
addresses
Contains list of public domain and IP addresses that Visa should white list in
order to send the traffic.
Visa will provide the following information to client once the onboarding is successfully completed:
Table 4–2: Receive Side API Client Onboarding: Information to client
Visa IP addresses for white list
Client to ensure that their firewall rules allow transactions traffics from these
IP addresses
Key ID
A unique ID which is used to determine the shared secret key needed to
decrypt the encrypted data.
Shared
secret
(encryption/decryption key)
Private key to be used decrypt encrypted value.
July 21, 2017
Visa Confidential
27
Note:
4.2
Senitive information such as PAN and names are encrypted before sending to the Acquirer. Client
should use Key ID and Shared secret to decrypt these data elements. Refer to section ‘API Development’
for details on how to manage decryption.
Step 2: Setup Mutual SSL Authentication
Receive Side API secures its connection with client using mutual SSL authentication. This is a process
which both the server and client have to authenticate each other, to ensure each other’s identity.
To establish the SSL connection, the following are required:

Visa will provide root certificate and intermediate certificate to client. Client is to load the
certificates into the Certificate Management Systems trust store.

Client to provide server certificate signed by an authorized Certificate Authority (CA) to Visa.
Separate certificates are required for onboarding to Sandbox, VCMS and Production.
5
API Development
This chapter provides the clients with an overview of the development considerations of Receive Side
APIs in accordance with the Specification, and exception handlings.
5.1
Managing Decryption of Data Elements
Sensitive information such as PAN and names are encrypted by Visa using the Key ID and shared secret
assigned to the Acquirer (i.e. client) before adding them with other data elements and send the entire
payload to the Acquirer for processing. All the data elements in the payload that have the prefix ‘enc’ are
encrypted, example, ‘encMerchantPan. These data elements will have to be decrypted with the Key ID
and shared secret before it can be used. Key ID and shared secret are given to the client during the
onboarding as mentioned in Section 4.3.
The following outlines the key steps to implement decryption of the data element of the request payload
from Visa.
July 21, 2017
Visa Confidential
28
mVisa Receive Side API - Client Implementation Guide
1. Get the necessary software library that supports AES GCM mode encryption in client preferred
programming languages (e.g. Java, PHP, C#, etc.) for software development. E.g. Download and install
Java Cryptography Extension (JCE) unlimited strength jurisdiction policy files.
2. When received the request payload data from Visa,

Identify the data field that requires decryption, i.e field name starts with prefix enc

Parse the encrypted value using the software library and extract “Key ID”.

Use “Key ID” to fetch the corresponding shared secret required for decryption. Client may have
more than one “Key ID” and “shared secret” from Visa stored in their system due to key
management

Decrypt the encrypted data field using the shared secret to get the field value.
5.2
Managing Encryption of Data Elements
Client is not required to perform encryption of their response payload data as there is no sensitive data
field in the response payload.
5.3
Exception Handling
When implementing Receive Side API, clients should ensure that the appropriate HTTP response is used,
and all exceptions are properly managed.
The following table summarizes the list of HTTP response code available to the client for implementation.
Table 5–1:
Receive Side API Response Code
HTTP Response Code
Description
200
Transaction successfully processed.
400

Missing required/mandatory field

The value exceeds the length specified for this field.

Field formatting does not match the expected format.

Type mismatch like Non-numeric values in Numeric fields

Invalid JSON request /The recipient API server could not understand the
request.

Base64 decoding failed

Decryption of the encrypted fields failed
July 21, 2017
Visa Confidential
29
HTTP Response Code
Description
500
Any unexpected error that happened on the recipient server while processing
the request.
The next section outlines the list of possible exceptions and the recommended response. .
5.3.1
HTTP 400 – Inability to process payload
Figure 5–1: HTTP 400 – Inability to process payload
1. Issuer initiates a payment request
2. The transaction request is routed to the Acquirer’s processing system with API Request payload.
3. The Acquirer is unable to process the payload due to one of the following error:

Missing required/mandatory field

The value exceeds the length specified for this field.

Field formatting does not match the expected format.

Type mismatch like Non-numeric values in Numeric fields

Invalid JSON request /The recipient API server could not understand the request.

Base64 decoding failed

Decryption of the encrypted fields failed
Acquirer responded with HTTP 400. There is no response body.
July 21, 2017
Visa Confidential
30
mVisa Receive Side API - Client Implementation Guide
4. VisaNet returns response code 96, system malfunction to the Issuer.
5. The Acquirer should ensure that fund is not credited to the merchant’s account.
5.3.2
HTTP 500 – System Error
Figure 5–2: HTTP 500 – System Error
1. Issuer initiates a payment request.
2. The transaction request is routed to the Acquirer’s processing system with API Request payload.
3. The Acquirer encounters error at their server while processing the request. The processing cannot
be completed. Acquirer responded with HTTP 500. There is no response body.
4. VisaNet returns response code 96, system malfunction to the Issuer.
5. The Acquirer should ensure that the fund is not credited to the merchant’s account.
Note:
July 21, 2017
Acquirer may respond as HTTP 400, 500 if the institution continues to encounter error at their server.
Visa will continue to retry sending the advice message until timeout, or retry threshold exceeded.
Visa Confidential
31
5.4
Handling of Advices
Advice messages are generated if one of the following exceptions occur:




Timeout occurs at Acquirer’s processing system when Visa is waiting for a response of a payload
request.
VisaNet has declined a transaction initiated by the Issuer.
VisaNet has declined a transaction on behalf of the Acquirer, as the velocity setup by Acquirer
has exceeded.
VisaNet has rejected a response from the Acquirer, as invalid values were detected in the
message.
The next section outlines the list of possible advices and the recommended responses.
5.4.1
Acquirer Timeout
Figure 5–3: Acquirer Timeout
1. Issuer initiates a payment request.
2. The transaction request is routed to the Acquirer’s processing system with API Request payload.
3. Timeout occurs when the Acquirer failed to respond within the expected timeframe.
4. VisaNet declines the transaction with response code 91, timeout.
5. An Advice message (message type – Advice) generated by the VisaNet is routed to the Acquirer’s
processing system as API advice.
July 21, 2017
Visa Confidential
32
mVisa Receive Side API - Client Implementation Guide
Note:
Refer to Receive Side API specification for different types of Advice messages.
6. Acquirer responded with HTTP 200 if it is able process the advice message successfully. There is no
response body.
7. The Acquirer should ensure that the fund is not credited to the merchant’s account.
Note:
5.4.2
Acquirer may respond as HTTP 400, 500 if the institution continues to encounter error at their server.
Visa will continue to retry sending the advice message until timeout, or retry threshold exceeded.
VIP Reject
Figure 5–4: VIP Reject
1. Issuer initiates a payment request.
2. The transaction request is routed to the Acquirer’s processing system with API Request payload.
3. Acquirer responded with HTTP 200 if it is able process the message successfully. The response will
also contain the response attributes.
4. VisaNet declines the transaction as the transaction contains invalid value/attributes.
5. An Advice message (message type – Reject) generated by the VisaNet is routed to the Acquirer
processing system as API advice.
Note:
July 21, 2017
Refer to Receive Side API specification for different types of Advice messages.
Visa Confidential
33
6. Acquirer responded with HTTP 200 if it is able process the advice message successfully. There is no
response body.
7. The Acquirer should ensure that the fund is not credited to the merchant’s account.
Note:
July 21, 2017
Acquirer may respond as HTTP 400, 500 if the institution continues to encounter error at their server.
Visa will continue to retry sending the advice message until timeout, or retry threshold exceeded.
Visa Confidential
34
mVisa Receive Side API - Client Implementation Guide
5.4.3
STIP Decline Advice
Figure 5–5: STIP Decline Advice
1. Issuer initiates a payment request.
2. VisaNet declines the transaction.
3. An Advice message generated by the VisaNet is routed to the Acquirer’s processing system as API
advice.
Note:
Refer to Receive Side API specification for different types of Advice messages.
4. Acquirer responded with HTTP 200 if it is able process the advice message successfully. There is no
response body.
Note:
5.4.4
Acquirer may respond as HTTP 400, 500 if the institution continues to encounter error at their server.
Visa will continue to retry sending the advice message until timeout, or retry threshold exceeded.
STIP Decline Advice (Velocity Exceeded)
Figure 5–6: STIP Decline Advice (Velocity Exceeeded)
1. Issuer initiates a payment request.
2. VisaNet declines the transaction as the receipient BIN has exceeded the velocity limit setup at
VisaNet.
3. An Advice message generated by the VisaNet is routed to the Acquirer’sprocessing system as API
advice.
July 21, 2017
Visa Confidential
35
Note:
This happens when Acquirer has opted to receive Advice message for any transaction VisaNet declines
on their behalf.
Refer to Receive Side API specification for different types of Advice messages.
4. Acquirer responded with HTTP 200 if it is able process the advice message successfully. There is no
response body.
Note:
July 21, 2017
Acquirer may respond as HTTP 400, 500 if the institution continues to encounter error at their server.
Visa will continue to retry sending the advice message until timeout, or retry threshold exceeded.
Visa Confidential
36
6
API Specifications
The table below shows the URL structure for the three transactions supported for Receive Side API:
Table 6–1:
Receive Side API TransactionTypes
Transaction Type
HTTP Method
Accept
Description
Person to Merchant
Cash In
https://{host}:{port}/pushpayment/transactions/receive/p2m
POST
application/json
Cash Out
https://{host}:{port}/pushpayment/transactions/receive/ci
https://{host}:{port}/pushpayment/transactions/receive/co
The API specifications for Refund APIs are published on Visa Developer Portal. Please visit the portal (https://developer.visa.com/) for
the specification details.
6.1
6.1.1
Receive Merchant Payment API
Receive Merchant Payment API Request
VisaNet field
number
Field function
Conditional/ Data type
Optional/
mandatory
Content/remarks
16-digit PAN created from the mVisa merchant ID as captured
by the consumer from the merchant information display.
encMechantPAN
July 21, 2017
Field 2
Mandatory
Encrypted
String(500)
Visa Confidential
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided. The field data type will
be Numeric(16-19) after decryption.
37
Original Credit Transaction API (OCT)
mVisa API Technical Specification
Field function
VisaNet field
number
Conditional/ Data type
Optional/
mandatory
transactionAmount
Field 4
Mandatory
Numeric(12)
transmissionDateTime
Field 7
Mandatory
String(10)
Format: MMDDhhmmss.
Content/remarks
Transaction amount in merchant currency.
systemTraceAuditNumber Field 11
Mandatory
String(6)
It is a key data element used to match a response to its
request or to match a message to others for a given
transaction.
localTransactionTime
Field 12
Mandatory
String(6)
The time the transaction takes place, expressed in the local
time of the originator. The time is in hhmmss format.
localTransactionDate
Field 13
Mandatory
String (4)
It contains the month and day on which the transaction was
originated. The date is in mmdd format.
originatorCountryCode
Field 19
Mandatory
String(3)
A 3-digit ISO-4217 code that identifies the country of the
originating BIN.
In certain case the merchant display information could contain
convenience fee applicable to the transaction.
transactionFeeAmount
Field 28
Conditional
Numeric(8)
Originators are required to populate convenience fee amount
in this field, if presented by merchant.
This field will be sent as NULL if it is not populated.
July 21, 2017
Visa Confidential
38
Field function
VisaNet field
number
Conditional/ Data type
Optional/
mandatory
Content/remarks
originatorBIN
Field 32
Mandatory
Numeric(11)
Identifies the originator of the merchant payment transaction.
Numeric(12)
It is a key data element for matching a message to others
within a given transaction set. The same number appears in all
related messages: response, advice, reversal, chargeback,
chargeback reversal, or representment. The format is
recommended to be ydddhhnnnnnn
retrievalReferenceNumber Field 37
Mandatory
This field contains the velocity limit related information that
Acquirer can use in making the authorization decision:
velocityLimitIndicator
Field 48,
Usage 37,
position 11
Conditional
Numeric(1)

1 = 1 day count or amount exceeded

2= 7 day count or amount exceeded

3 = 30 day count or amount exceeded
The field is populated with priority of 1, 2 and then 3.
This field is sent if recipient has opted for VisaNet to forward
them the OCT when a velocity limit has been exceeded.
This field will be sent as NULL if it is not populated.
transactionCurrencyCode
Field 49
Mandatory
String(3)
The 3-digit ISO-4217 code in this field reflects the currency
associated to the transactionAmount field.
It is added by VisaNet
visaTransactionId
Field 62.2
July 21, 2017
Mandatory
String(15)
Visa Confidential
It contains a right-justified, VisaNet generated Transaction
Identifier (TID) that is unique for each request. The identifier
links original messages to subsequent messages, such as those
39
Original Credit Transaction API (OCT)
mVisa API Technical Specification
VisaNet field
number
Field function
Conditional/ Data type
Optional/
mandatory
Content/remarks
for exception item processing and clearing record PCR/BIN Flag
for receiving this field must be turned on for this.
Populate 0
Field 62.7
Position 1
billIdFormat
Conditional
String(1)
(Primary ID, as defined by mVisa)
This field will be sent as NULL if it is not populated.
This is the invoice number or some other reference for billing
purposes.
billId
Field 62.7
Conditional
String(25)
E.G. For Airtime top up, this should contain the MSISDN that is
being topped up.
This field will be sent as NULL if it is not populated.
refId
Field 102
encConsumerPAN
Field 104
DataSet ID 5F,
Tag 02
encConsumerName
Field 104
DataSet ID 5F,
Tag 03
July 21, 2017
Conditional
String(28)
This field is sent if it is reflected in the merchant information
display. It will otherwise be sent as NULL if it is not populated.
This field contains the consumer PAN as defined by mVisa
specifications.
Mandatory
Mandatory
Encrypted String
(500)
Encrypted
String(500)
Visa Confidential
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided. The field data type will
be Numeric(16-19) after decyption.
Contains consumer name. If consumer name is greater than 30
characters, then only first 30 characters will be expected.
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided.
40
VisaNet field
number
Field function
decimalPositionIndicator
6.1.2
Field 63.13
Position 1-2
Conditional/ Data type
Optional/
mandatory
Mandatory
Numeric (1)
Content/remarks
Indicates the number of decimal positions following the
amount field.
This field is to be sent as NULL if it is not populated.
Receive Merchant Payment API Response
VisaNet field Conditional/ Data type
Optional
number
/Mandatory
Field function
receiverTransactionId
NA
Optional
String(16)
Content/remarks
Acquirer may provide a transaction ID that can be used for
investigation if required.
This field is to be sent as NULL if it is not populated.
Recipient should populate the MCC of the merchant in the
response message. If replaced by recipient Visa settlement
reports would contain the value provided by recipient.
merchantCategoryCode
Field 18
Mandatory
String(4)
authIdResponse
Field 38
Conditional
String(6)
July 21, 2017
Visa Confidential
This field accept only numeric data. If there is non numeric data
provided in this field the default "0000" translation will be sent
to VIP
Contains the authorization code provided by the recipient
when a transaction is approved.
41
Original Credit Transaction API (OCT)
mVisa API Technical Specification
VisaNet field Conditional/ Data type
number
Optional
/Mandatory
Field function
Content/remarks
Visa recommends that recipients maintain uniqueness of this
code for a given merchant PAN, however Visa would not
maintain any checks for uniqueness.
This field is to be sent as NULL if it is not populated.
responseCode
Field 39
Mandatory
String(2)
Contains a code that defines the response to a request. Refer to
section 8.1 Response Code for list of possible responses.
This is called Card Acceptor Name in the Visa Spec.
merchantName
Field 43
Mandatory
Position 1-25
String(25)
Recipient must replace this field with the ‘doing business as’
name of Merchant.
Visa settlement reports would contain the value provided by
recipient.
Field 43
Position 2638
merchantCity
merchantCountryCode
Field 43
Position 3940
This is called Card Acceptor Location
Mandatory
Conditional
String(13)
String(2)
Recipient must replace this field with the city name of
Merchant. Visa settlement reports would contain the value
provided by recipient.
Recipient may replace this field with the 2-letter ISO 3166
country code of the merchant, if the country code of recipient
is different than originator. Visa settlement reports would
contain the value provided by recipient.
This field is to be sent as NULL if it is not populated.
July 21, 2017
Visa Confidential
42
VisaNet field Conditional/ Data type
number
Optional
/Mandatory
Field function
merchantTerminalID
Field 48
Position 6 –
13
Conditional
String(8)
Content/remarks
Recipient may replace this field with card acceptor terminal ID
as defined in recipient system. If replaced by recipient, all
occurrences of card acceptor terminal ID in reports, files,
transaction inquiries, etc. will contain the value provided by the
recipient.
This field is to be sent as NULL if it is not populated.
Field 48
Position 14 28
merchantID
Conditional
String(15)
Recipient may replace this field with card acceptor ID code of
the merchant as defined in recipient system. If replaced by
recipient, all occurrences of card acceptor ID code in reports,
files, transaction inquiries, etc. will contain the value provided
by the recipient.
This field is to be sent as NULL if it is not populated.
merchantVerificationValue Field 62.20
Optional
String(10)
Recipient are expected to populate the Merchant Verification
Value used to identify merchants that participate in a variety of
programs in this field
This field is to be sent as NULL if it is not populated.
feeProgramIndicator
Field 63.19
Optional
String(3)
Optional field which may be populated by recipient where
applicable.
This field is to be sent as NULL if it is not populated.
July 21, 2017
Visa Confidential
43
Original Credit Transaction API (OCT)
mVisa API Technical Specification
6.2
6.2.1
Receive Cash In API
Receive Cash In API Request
VisaNet field
number
Field function
Conditional/ Data type
Optional/
mandatory
Content/remarks
16-digit PAN as provided by the consumer to agent.
encConsumerPAN
Field 2
Mandatory
Encrypted String
(500)
transactionAmount
Field 4
Mandatory
Numeric(12)
Transaction amount in local currency. mVisa program rules do
not permit cross border cash deposit transactions.
transmissionDateTime
Field 7
Mandatory
String(10)
Format: MMDDhhmmss.
systemTraceAuditNumber
Field 11
Mandatory
String(6)
It is a key data element used to match a response to its
request or to match a message to others for a given
transaction.
localTransactionTime
Field 12
Mandatory
String(6)
The time the transaction takes place, expressed in the local
time of the originator. The time is in hhmmss format
July 21, 2017
Visa Confidential
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided. The field data type will
be Numeric (16-19) after decryption.
44
Field function
VisaNet field
number
Conditional/ Data type
Optional/
mandatory
localTransactionDate
Field 13
Mandatory
String(4)
It contains the month and day on which the transaction was
originated. The date is in mmdd format
originatorCountryCode
Field 19
Mandatory
String(3)
A 3-digit ISO-4217 code that identifies the country of the
originator BIN.
originatorBIN
Field 32
Mandatory
Numeric(11)
Identifies the originator of the cash in transaction.
Mandatory
Numeric(12)
It is a key data element for matching a message to others
within a given transaction set. The same number appears in all
related messages: response, advice, reversal, chargeback,
chargeback reversal, or representment. The format is
recommended to be ydddhhnnnnnn
Mandatory
String(13)
Agent Location
retrievalReferenceNumber
Field 37
Field 43
Position 26-38
agentCity
Content/remarks
This field contains the velocity limit related information that
Acquirer can use in making the authorization decision:
velocityLimitIndicator
Field 48,
Usage 37,
position 11
Conditional
Numeric(1)

1 = 1-day count or amount exceeded

2= 7-day count or amount exceeded

3 = 30-day count or amount exceeded
The field is populated with priority of 1, 2 and then 3.
July 21, 2017
Visa Confidential
45
Original Credit Transaction API (OCT)
mVisa API Technical Specification
VisaNet field
number
Field function
Conditional/ Data type
Optional/
mandatory
Content/remarks
This field is sent if recipient has opted for VisaNet to forward
them the OCT when a velocity limit has been exceeded.
This field will be sent as NULL if it is not populated.
transactionCurrencyCode
Field 49
Mandatory
String(3)
The 3-digit ISO-4217 code in this field reflects the currency
associated to the transactionAmount field.
It is added by VisaNet.
visaTransactionId
Field 62.2
Mandatory
String(15)
decimalPositionIndicator
Field 63.13
Position 1-2
Conditional
Numeric(1)
encAgentName
Field 104
DataSet ID 5F
Tag 03
July 21, 2017
Mandatory
Encrypted
String(500)
It contains a right-justified VisaNet generated Transaction
Identifier (TID) that is unique for each original authorization
and financial request. The identifier links original messages to
subsequent messages, such as those for exception item
processing and clearing record PCR/BIN Flag for receiving Field
this field must be turned on for this.
Indicates the number of decimal positions in the amount field.
This field is to be sent as NULL if it is not populated.
Contains Agent’s Doing Business as name (25 characters
only). If the name is greater than 25 characters then the first 25
characters are populated.
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided.
Visa Confidential
46
6.2.2
Receive Cash In API Response
VisaNet field
number
Field function
receiverTransactionId
NA
Conditional/ Data type
Optional/
Mandatory
Optional
String(16)
Content/remarks
Acquirer may provide a transaction ID that can be used for
investigation if required.
This field is to be sent as NULL if it is not populated.
authIdResponse
Field 38
Conditional
String(6)
Contains the authorization code provided by the participant
when a transaction is approved.
This field is to be sent as NULL if it is not populated.
responseCode
Field 39
July 21, 2017
Mandatory
String(2)
Visa Confidential
Contains a code that defines the response to a request. Refer to
section 8.1 Response Code for list of possible responses.
47
Original Credit Transaction API (OCT)
mVisa API Technical Specification
6.3
6.3.1
Receive Cash Out API
Receive Cash Out API Request
VisaNet field
number
Field function
Conditional/ Data type
Optional/
Mandatory
Content/remarks
16-digit PAN as created from the mVisa agent ID captured by
the consumer from agent information display option
Field 2
encAgentPAN
Mandatory
Encrypted
String(500)
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided. The field data type will
be Numeric(16-19) after decryption.
Transaction amount in agent on currency
transactionAmount
Field 4
Mandatory
Numeric(12)
In case the agent currency is not the same as the consumer
currency, then originator will perform currency conversion
before submitting the transaction.
transmissionDateTime
Field 7
Mandatory
String(10)
Format: MMDDhhmmss.
systemTraceAuditNumber Field 11
Mandatory
String(6)
It is a key data element used to match a response to its
request or to match a message to others for a given
transaction.
localTransactionTime
Mandatory
String(6)
The time the transaction takes place, expressed in the local
time of the originator. The time is in hhmmss format
Field 12
July 21, 2017
Visa Confidential
48
Field function
VisaNet field
number
Conditional/ Data type
Optional/
Mandatory
localTransactionDate
Field 13
Mandatory
String(4)
It contains the month and day on which the transaction was
originated. The date is in mmdd format
originatorCountryCode
Field 19
Mandatory
String(3)
A 3-digit ISO-4217 code that identifies the country of the
originating BIN.
originatorBIN
Field 32
Mandatory
Numeric(11)
Identifies the originator of cash-out transaction.
Numeric(12)
It is a key data element for matching a message to others
within a given transaction set. The same number appears in all
related messages: response, advice, reversal, chargeback,
chargeback reversal, or representment. The format is
recommended to be ydddhhnnnnnn
retrievalReferenceNumber Field 37
Mandatory
Content/remarks
This field contains the velocity limit related information that
Acquirer can use in making the authorization decision:
velocityLimitIndicator
Field 48,
Usage 37,
position 11
Conditional
Numeric(1)

1 = 1 day count or amount exceeded

2= 7 day count or amount exceeded

3 = 30 day count or amount exceeded
The field is populated with priority of 1, 2 and then 3.
This field is sent if recipient has opted for VisaNet to forward
them thee OCT when a velocity limit has been exceeded.
This field will be sent as NULL if it is not populated.
July 21, 2017
Visa Confidential
49
Original Credit Transaction API (OCT)
mVisa API Technical Specification
Field function
VisaNet field
number
Conditional/ Data type
Optional/
Mandatory
transactionCurrencyCode
Field 49
Mandatory
String(3)
Content/remarks
The code in this field reflects the currency associated to the
transactionAmount field 3-digit ISO-4217 currency code.
It is added by VisaNet.
visaTransactionId
Field 62.2
Mandatory
String(15)
decimalPositionsIndicator
Field 63.13
Position 1-2
Mandatory
Number(1)
encConsumerPAN
Field 104
Dataset ID 5F
Tag 02
encConsumerName
Field 104
Dataset ID 5F
Tag 03
July 21, 2017
It contains a right-justified, VisaNet generated Transaction
Identifier (TID) that is unique for each original authorization
and financial request. The identifier links original messages to
subsequent messages, such as those for exception item
processing and clearing record PCR/BIN Flag for receiving this
field must be turned on for this.
Indicates the number of decimal positions following the
amount field.
This field contains the consumer PAN as defined by mVisa
specifications.
Mandatory
Mandatory
Encrypted
String(500)
Encrypted
String(500)
Visa Confidential
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided. The field data type will
be Numeric(16-19) after decyption.
Contains consumer name. If consumer name is greater than 30
characters, then only first 30 characters will be expected.
The field is sent in encrypted format which the recipient must
decrypt using the instructions provided.
50
6.3.2
Receive Cash Out API Response
VisaNet field
number
Field function
receiverTransactionId
NA
Conditional/ Data type
Optional/
Mandatory
Optional
String(16)
Content/remarks
Acquirer may provide a transaction ID that can be used for
investigation if required.
This field is to be sent as NULL if it is not populated.
authIdResponse
Field 38
Conditional
String(6)
Contains the authorization code provided by the issuer when a
transaction is approved
This field is to be sent as NULL if it is not populated.
responseCode
Field 39
Mandatory
String(2)
Contains a code that defines the response to a request. Refer to
section 8.1 Response Code for list of possible responses.
This is called Card Acceptor Name in the Visa Spec.
Field 43
Position 125
agentName
Field 43
Position 26-38
agentCity
agentCountryCode
Mandatory
String (25)
Visa settlement reports would contain the value provided by
recipient.
This is called Card Acceptor Location
Mandatory
String(13)
Field 43
Conditional
Position 39-40
String(2)
July 21, 2017
Recipient must replace this field with the ‘doing business as’
name of Agent.
Recipient must replace this field with the city name of agent.
Visa settlement reports would contain the value provided by
recipient.
Recipient may replace this field with 2-letter ISO 3166 country
code of the agent, if different than the value provided by the
originator
Visa settlement reports would contain the value provided by
recipient.
Visa Confidential
51
Original Credit Transaction API (OCT)
mVisa API Technical Specification
Field function
VisaNet field
number
Conditional/ Data type
Optional/
Mandatory
Content/remarks
This field is to be sent as NULL if it is not populated.
July 21, 2017
Visa Confidential
52
6.4
Advices API
The following table summarizes the list of Advices and respective URL available to the client for implementation.
Table 6–2: Advice Types
Advice Transaction Type
HTTP Method
Accept
Description
Person to Merchant
Cash In
https://{host}:{port}/pushpayment/advice/receive/p2m
POST
https://{host}:{port}/pushpayment/advice/receive/ci
application/json
Cash Out
https://{host}:{port}/pushpayment/advice/receive/co
Note:
6.4.1
Refer to section ‘Exception Handling’ for details on how each of these advices should be handled.
Advice Message Specification
An advice message is made up of the original payload request and additional information specific to the Advice request. The additional
fields are outline below in the table:
Field function
VisaNet field Conditional/ Data type
Optional/
number
Mandatory
Content/remarks
Possible values based on Message Type Identifier are:
0200 : "Recipient Timeout"
messageType
NA
Mandatory
String
0220 : "Advice" (STIP decline advice)
0210 : "Reject" (VIP reject)
July 21, 2017
Visa Confidential
53
Original Credit Transaction API (OCT)
mVisa API Technical Specification
Field function
VisaNet field Conditional/ Data type
number
Optional/
Mandatory
Content/remarks
authIdResponse
Field 38
Conditional
String(6)
Auth ID of the original request
responseCode
Field 39
Mandatory
String(2)
Response code of the original request
rejectionCode
Reject codes
appear in field
14 of a reject Mandatory
message
header
Note:
Only populated if Advice message type is ‘Reject’. This field
contains the VIP rejection code
String
For list of rejection codes, please refer to VIP system SMS POS,
technical specifications volume 2
HTTP Response will not have body.
July 21, 2017
Visa Confidential
54
Action Code
mVisa API Technical Specification
7
Sample Codes
7.1
Receive Merchant Payment API Sample Code
Table 7–1:
Receive Merchant Payment API Request Sample Code
{
"encMerchantPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6InBYUV84eDk3N0lxOUF0ZEEiLCJ0YWciOiJ5SVNQbUp0TGZiOUJfd1
9VWm9CNTRBIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6Il
NIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTE0MjQ1In0.s1vyRXwdVndiTHeUwS6YEOF5f6LZXqNMe5dKDoKq5w.copxyXAO-ciSuO64.2ruzAYIRo8WjTb5x8WPfxw.wyBxF_Xr_bdsnoV0CZf45Q",
"transactionFeeAmount":null,
"billIdFormat":null,
"billId":null,
"refId":"field102",
"encConsumerName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IjdPMXM2c3NBY1pjcnluaEIiLCJ0YWciOiI5R3dBQTQ3cTVqZ2Nx
WjhyTlBZeTNRIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6Il
NIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTE0MjQ2In0.e3aVkOnOiw16bhsXiYEBqTk7ZIGfMJHV6S06687CTI0.X3lA1KusCejn
9u-b.vRLYMfnAx4UsvGVMLg.-jF_6jT4EBctEI7D-iiU-w",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":18034471349,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6InJlLXpsVE1mVHk3UVg4dXQiLCJ0YWciOiJFRTVQN3FEX1Myc1FQ
R3BHUDVEYUJRIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6I
lNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTE0MjQ2In0.oncFtO5s4nIHycnLmRHEz0muCweqIPbCisRemwZO0w.me2vEcKdFRcrNDq_.jsWVyYtdwT-_jJpYQy0S3w.ZWcxjZXrb0v4anddlUOt2w"
}
Table 7–2:
Receive Merchant Payment API Response Sample Code (HTTP 200)
{
"receiverTransactionId": "70967035",
"merchantCategoryCode": 6012,
"authIdResponse": "231043",
"responseCode": "00",
"merchantName": "M1",
"merchantCity": "Foster City",
July 21, 2017
Visa Confidential
55
Action Code
mVisa API Technical Specification
"merchantCountryCode": "US",
"merchantTerminalID": "123",
"merchantID": "1011",
"merchantVerificationValue": 111222333,
"feeProgramIndicator": "210"
}
Table 7–3:
Receive Merchant Payment API Response Sample Code (HTTP 400/500)
{
"receiverTransactionId": "XXXX1234",
"responseCode": "00",
"responseMessage" : "Invalid Data"
}
7.2
Receive Cash In API Sample Code
Table 7–4: Receive Cash In API Request Sample Code
{
"encConsumerPAN":
"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IlRTUHdrckxHeVV6bERycWUiLCJ0YWciOiJfSk43a05vendsbXdCY2VNeG9fR
U1nIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6
IlNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTA5Mjc5In0.C42vdWXya3XwN1wWEW0MbElVA9beNQRlhmicuFkh2k.wIRmINck92L8-uVL.YYHPGJEbj-d4hdWdgyPbCw.SlmK6vqXE0AfmcM18LVQZQ",
"encAgentName":
"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6InFiR1BZWko1Rzl3UUR4cVEiLCJ0YWciOiJlbExXYWhROXFuTnM3OUxhcUN
HVnh3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4d
CI6IlNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTA5Mjc5In0.EucRRgXOeBS0fsMejiPpyH_y7fkZXn7kQDEAcGiCvM.Ds01yikTZn2lIcKx.08qpkdmzpa6BgAK2mg.mJILF1NyxR4V539DYQXdIw",
"agentCity":"City
",
"transactionAmount": 7500,
"transmissionDateTime": "1030160507",
"systemTraceAuditNumber": "001636",
"localTransactionTime": "090507",
"localTransactionDate": "1030",
"originatorCountryCode": "710",
"originatorBIN": 400552,
"retrievalReferenceNumber": 87825237775,
"velocityLimitIndicator": null,
"transactionCurrencyCode": "710",
"visaTransactionId": "302304579070680",
"decimalPositionIndicator": null
}
July 21, 2017
Visa Confidential
56
Action Code
mVisa API Technical Specification
Table 7–5:
Receive Cash In API Response Sample Code (HTTP 200)
{
"receiverTransactionId": "70967835",
"authIdResponse": "231043",
"responseCode": "00"
}
Table 7–6:
Receive Cash In API Response Sample Code (HTTP 400/500)
{
"receiverTransactionId": "XXXX1234",
"responseCode": "00",
"responseMessage" : "Invalid Data"
}
A.1
Receive Cash Out API Sample Code
Table 7–7:
Receive Cash Out API Request Sample Code
{
"encAgentPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6Im45VWNOM2pvekNiUDZHeHYiLCJ0YWciOiJ4eGswaC13a1BqcUx0bk
1JRlJFRGFRIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNIQ
VJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTEyODk5In0._eGcMlbXrUPqZtw2QXR2VfkFgMhxHhVrQ2fgFlaz_oQ.9C3rurtGyVtpX2i
T.yO2Y0CvO4kAICrcHyPeyFQ._5M21Y8YbJ2m_PQQkKkYsw",
"encConsumerName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6Ik9TMlhkd3dTVXhkUEJoQWciLCJ0YWciOiJOWUdGcmI3eF9GZD
BObHNKNFEwNGZ3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4
dCI6IlNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTEyODk5In0.7DE3GOM83p9eXhAIrGL1DgSgLEPflpZNQGBPq5eWV3U.csb
Awhqe-9i0FwGX.D4EZXezm-ece_Jm3Rw.83BX87W1Hi32juoZl3amaw",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":97920888748,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6ImRjQnpGT2VVMVU1Uzd6SFMiLCJ0YWciOiJrNzdUOC1TQ0FLbW
8yVHAweXlsdTJRIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI
6IlNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTEyODk5In0.D9yytevVlsBcwbZwe4BtCTHiR-dAnTSBQTbZJzf2xw.dCYDrXvYFldaMMth.9X-ExewjiuqBqzkGLA_9jw.egIZHRPOm-NhvxAqhewRWg"
}
July 21, 2017
Visa Confidential
57
Action Code
mVisa API Technical Specification
Table 7–8:
Receive Cash Out API Response Sample Code (HTTP 200)
{
"receiverTransactionId": "70967836",
"authIdResponse": "231043",
"responseCode": "00",
"agentName": "Test Name",
"agentCity": "Singapore",
"agentCountryCode": "SG"
}
Table 7–9:
Receive Cash Out API Response Sample Code (HTTP 400/500)
{
"receiverTransactionId": "XXXX1234",
"responseCode": "00",
"responseMessage" : "Invalid Data"
}
July 21, 2017
Visa Confidential
58
Action Code
mVisa API Technical Specification
7.3
Receive Merchant Payment Advice Sample Code
Table 7–10: Receive Merchant Payment API – STIP Decline Advice Sample Code
{
"encMerchantPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6ImsxWjUyWlBady1yaWlGNEYiLCJ0YWciOiJMNHJrWUF2dWRUT0t4
ZjJiVXl4dVBRIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNI
QVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTk0MjI3In0.BCZpCbnsSAj-xb4ONqX_fwptYQXdgkWpT03KGObxqU.hPN0jsJhs7I6hxWa.OjhTzHNi_jQPo-pmlj-njQ.NM8Gd3QNx3Bgzq9HzOdQaw",
"transactionFeeAmount":null,
"billIdFormat":null,
"billId":null,
"refId":null,
"encConsumerName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6InhGcUFNdm9qaVljdWtZMHIiLCJ0YWciOiIxOEREQURRU0tGMX
owZGd5M1gtTEdBIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4d
CI6IlNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTk0MjI3In0.2UOL0f3ZhwOokqE2GZ7YYmXtmkQybAZO8287UigQ8WM.G4N
TS9Qp968RwN7v.G86QrVSBWsNqRHevCg.k3xqEzMzyNoDBPY6hJYuZA",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":90695537641,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"messageType":"Advice",
"rejectionCode":null,
"authIdResponse":null,
"responseCode":null,
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6Ik1DNU91a0NOVkRvS2VlWEgiLCJ0YWciOiJZeVBCNmFqMkppcVl1
V0xxcmZqdmx3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6I
lNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTk0MjI3In0.UU5GOcKEiYmgmVqH1i9f9dWvmQ5zr9G83sCz3qR6sKg.suwxeGJM
9ZyesoM-.sxJutx8Zl4c2BL56wMwyCA.lFBshz-rTOe-VVTvcesF9A"
}
Table 7–11: Receive Merchant Payment API – VIP Reject Advice sample code
{
"encMerchantPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IlIyQXNCa1hIVGR6cHp2UDAiLCJ0YWciOiJWVWpmNUE3NnRUZ2V
lVjBBYUVpcGxnIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6Il
NIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTk0NTA4In0.ByzZKS-rv_kMPx8SvOBKGeyZ4_Ku1RcvLAtGLlXaSM.PDCKp4MRPVHXHm5Z.DKj6kqZYHfA3z5ePA9os9Q.fwDSlORxaBeRIlu_0FWNfQ",
"transactionFeeAmount":null,
"billIdFormat":null,
"billId":null,
"refId":null,
July 21, 2017
Visa Confidential
59
Action Code
mVisa API Technical Specification
"encConsumerName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IkJDYmxONmFOdi1iWkxjVGwiLCJ0YWciOiJnZFJIYnJGWlR5RHNI
UGduNFJFN0V3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6I
lNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTk0NTA4In0.jmevsm1Kr316cULyYKvoZ-K0BGIzbFrbo13OrcRhvM.0Cj6_PJTwmQZifxK.oMwr1nLArdSFIUqOGw.dU3ZHHXzoDBnuxv1LY7kAQ",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":56990607296,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"messageType":"Reject",
"rejectionCode":"0294",
"authIdResponse":null,
"responseCode":null,
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IlVPTmFqVGMtckdKMFZQOVEiLCJ0YWciOiIydkVYYVVsSFpDLXBjR
Go2V2hGRGF3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6Il
NIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTk0NTA4In0.d-j8adNGw2y3ujUFIKep6ayCLe1zJIkJr4x96BwMz8.tQgQGV4C11BKhzHA.L98UlcE30Ue1j0KaVB1dVw.e3p8KKHn1z0MY-JWkeMwOA"
}
July 21, 2017
Visa Confidential
60
Action Code
mVisa API Technical Specification
7.4
Receive Cash In Advice Sample Code
Table 7–12: Receive Cash In API – STIP Decline Advice Sample Code
{
"encAgentName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6Ik8wS05CbGNLaktOckotVHMiLCJ0YWciOiJZQS1XVmtWVjN0T0loTEJ
JcXRmMW9RIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNI
QVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkyOTI3In0.b7l4TlFQGMZtObbP_lVyTCWeuHfjC1zzLa1lwvvtcg.varH8BeanmVEeJds.2PqkWOPRYzVqxdxxQA.UNvXl1FreeTR2VhQoRSi7g",
"agentCity":"City
",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":57450827499,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"messageType":"Advice",
"rejectionCode":null,
"authIdResponse":null,
"responseCode":null,
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IlRTbjVPT2t6dXREd0c0VU8iLCJ0YWciOiJIN1RIUGxZVG5SV2kzaHZ
HbGRnVWR3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNI
QVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkyOTI3In0.0lXKaEVGHg4JmpMT453q_Gf0thVX5UtZxyF8lnhgru4.vOZwnQ4t7gcSie
2b.J8AKIK1f7YkHTyhhcBYByQ.0edyrtVr6burg4NVmCDPqQ"
}
Table 7–13: Receive Cash In API – VIP Reject Advice sample code
{
"encAgentName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6ImdXQjQtOVlnTmx5VE1UZVUiLCJ0YWciOiJESXZ3Y1ctWGp5ZDFJT2
NrSm0zb09BIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNI
QVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzNDExIn0.PhcVj_byug9FCrDj8y8Fddw8HeR0Wbr_C6NwaIQ5pk.c6EA_F442UVBndw-.QvgJbhhu-CPOJCuqDg.5Uso_aShxqSU8WD0Z3TwoQ",
"agentCity":"City
",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":51744774010,
"velocityLimitIndicator":null,
July 21, 2017
Visa Confidential
61
Action Code
mVisa API Technical Specification
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"messageType":"Reject",
"rejectionCode":"0294",
"authIdResponse":null,
"responseCode":null,
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6InRmNHpqek83YnZDNzV3WFAiLCJ0YWciOiJjbVJEX2R6VHl1eWdU
QjVfUWVVTzRnIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6I
lNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzNDExIn0.0XC79z9p_9GQ17IFAS1KQS2Qroo7qeOBUAf2uJQ4o8.rWG8JN3UDREaQG6I.FD5aLJ42OG2u68HR59HTLQ.kvSZSkCskbRQFdf1Jb82sQ"
}
July 21, 2017
Visa Confidential
62
Action Code
mVisa API Technical Specification
7.5
Receive Cash Out Advice Sample Code
Table 7–14: Receive Cash Out API – STIP Decline Advice Sample Code
{
"encAgentName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6InZJdnA5dm1WSHJqZUc4anIiLCJ0YWciOiJTWWF5SFdHNGg2SmVZd
mtXem5IaVRRIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6Il
NIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzNTg4In0.CULZQY4Hw5ZTu2rXthAchvwNiwgfTEKqy2bQGzR4GA8.5Xad7XoH
R2ek4jPo.Jsw5BxeLc7sL0poJww.k9ycmI8LFatXkusOI1yXjA",
"agentCity":"City
",
"agentCountryCode":"SG",
"encAgentPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6ImpVTUVoWmpyXzhhWHlBSjAiLCJ0YWciOiJLY29sVjB3WFZoM1oxWT
NlajE2SXp3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNIQ
VJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzNTg4In0.fYi16-gsVXTlBMgp7eSZ4cxHLXRsEP5IKUrWPyPFmM.3iiafxXoBZmX9xlm.GJO8-A_gJTSYOuNOcP8wIw.N27uMFUp-YPFDIaN1oyw-A",
"encConsumerName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IjEzWGw3Z3E3MUZiX3RWZlMiLCJ0YWciOiJuMEFqc2lwR1V5d0p
BYm1aOUpaWkN3IiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4d
CI6IlNIQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzNTg4In0.SKTtvqAB8RDYACVsqj95n5S9Fjz_MAHcgG8wmhymMv0.gazfuE
BYT2e63Wye.BC6bIF60iZBXT8KoYA.EixFMEM0-IAOf4ZA5lZbqA",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":43312702177,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"messageType":"Advice",
"rejectionCode":null,F
"authIdResponse":null,
"responseCode":null,
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IkpmQ0lINExpcHFOekFSbVYiLCJ0YWciOiJocFhmS0F0X3lrLTVFWFc
4UHppQnRnIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNI
QVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzNTg4In0.q6zBMfcs30G5ttv0qAUttVqr3ajO3pEAx1ZWBh5xNlo.QKd2OcBmExnm
XuQp.0BioasDfkNYnM1m_kxMJjw.sfXmLWyxDSSuyUKte5wSfA"
}
Table 7–15: Receive Cash Out API – VIP Reject Advice sample code
{
"encAgentName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IlRjaEZVQlZfQ3JEazVrb0IiLCJ0YWciOiJPYU9fTmlSWjFaS3VXRGJzMS1
PSlpnIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlNIQVJFRF
9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzOTY3In0.elTMYvflGMYuxBIn0T9iHTJbGJqiWu7NV5qA8bvycE4.UKXL38zrCEnphC_b.nssL
ibGbzXBErhoCug.3fZxRhzQ-FgpB5nRvSD5lg",
"agentCity":"City
",
July 21, 2017
Visa Confidential
63
Action Code
mVisa API Technical Specification
"agentCountryCode":"SG",
"encAgentPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IkxqQmR2NDFwU2ZWOF8xRHUiLCJ0YWciOiJZSmRJSnhuWWtzR2ZhT
0l3aGdoSDVnIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlN
IQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzOTY3In0.PWLBeDsUOoUCbRP8vFb05RHk2khlm115g06Szfmpz5Q.U6T7BdiAsM
qomeD7.qEkCeQiH0ELeHhKiDgRF9A.0buByXKmNP-GCcvbAL27Sw",
"encConsumerName":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6Imc5bTZzVFVyYUwxc2lpVVEiLCJ0YWciOiI2aEp1VjJqcDZVY0h1O
FZkNkI0TDNBIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlN
IQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzOTY3In0.gdZRgSVFzWLC8ra7iGZakSzTgWn-V8g-gJmV03gJybY.LBPo44fRcn5f0ff.TDHQqD0NeENiatgo0g.M_K5M2nbZ2G7jdg366Nnpg",
"transactionAmount":7500,
"transmissionDateTime":"1030160507",
"systemTraceAuditNumber":"001636",
"localTransactionTime":"090507",
"localTransactionDate":"1030",
"originatorCountryCode":"710",
"originatorBIN":400552,
"retrievalReferenceNumber":26339435435,
"velocityLimitIndicator":null,
"transactionCurrencyCode":"710",
"visaTransactionId":"302304579070680",
"messageType":"Reject",
"rejectionCode":"0294",
"authIdResponse":null,
"responseCode":null,
"decimalPositionIndicator":null,
"encConsumerPAN":"eyJhbGciOiJBMjU2R0NNS1ciLCJpdiI6IlRJT09IMmkwX2g4Y0ZYZHIiLCJ0YWciOiI4eHM3WmRZbDBnZVpj
cnAxQzItckhnIiwiZW5jIjoiQTI1NkdDTSIsInR5cCI6IkpPU0UiLCJraWQiOiIxMDAxIiwiY2hhbm5lbFNlY3VyaXR5Q29udGV4dCI6IlN
IQVJFRF9TRUNSRVQiLCJpYXQiOiIxNDcwOTkzOTY3In0.IksPV97FsVSptSa9PvoMrq31C1zW8tX4HrbPFKz6EzU.4D3vksW_tevuA
Oht.l43vHxFoYN3DYbgQtsXEtg._eEhBmhSDQ7EKcU_k1FG1Q"
}
July 21, 2017
Visa Confidential
64
Action Code
mVisa API Technical Specification
8
Reference Codes
8.1
Response Code
Code Description
00
Approved and completed successfully
01
Refer to card issuer
02
Refer to card issuer, special condition
03
Invalid merchant
04
Pick up card (no fraud)
05
Do not honor
06
Error
07
Pick up card, special condition (fraud account)
10
Partial approval
11
Approved (V.I.P)
12
Invalid transaction
13
Invalid amount or currency conversion field overflow
14
Invalid account number (no such number)
15
No such issuer
19
Re-enter transaction
21
No action taken
25
Unable to locate record in file
28
File temporarily not available for update or inquiry
39
No credit account
41
Lost card, pick up (fraud account)
43
Stolen card, pick up (fraud account)
51
Not sufficient funds
52
No checking account
July 21, 2017
Visa Confidential
65
Action Code
mVisa API Technical Specification
53
No savings account
54
Expired card or expiration date is missing
55
Incorrect PIN or PIN missing
57
Transaction not permitted to cardholder
59
Suspected fraud
61
Exceeds approval amount limit
62
Restricted card (card invalid in this region or country)
63
Security violation (source is not correct issuer)
64
Transaction does not fulfill AML requirement
65
Exceeds withdrawal frequency limit
75
Allowable number of PIN entry tries exceeded
76
Unsolicited reversal
79
Already reversed (by Switch)
80
No financial impact
81
Cryptographic error found in PIN
82
Negative CAM, dCVV, iCVV, or CVV results
85
No reason to decline a request for address verification, CVV2 verification, or a credit voucher or
merchandise return
86
Cannot verify PIN; for example, no PVV
89
Ineligible to receive financial position information (GIV)
91
Issuer or switch inoperative and STIP not applicable or not available for this transaction; Time-out when
no stand-in; POS Check Service: Destination unavailable; Credit Voucher and Merchandise Return
Authorizations: V.I.P. sent the transaction to the issuer, but the issuer was unavailable.
92
Financial institution or intermediate network facility cannot be found for routing (receiving institution
ID is invalid)
93
Transaction cannot be completed - violation of law
94
Duplicate transmission.
96
System malfunction
B1
Surcharge amount not permitted on Visa cards or EBT food stamps (U.S. acquirers only)
B2
Surcharge amount not supported by debit network issuer.
July 21, 2017
Visa Confidential
66
Action Code
mVisa API Technical Specification
N0
Force STIP
N3
Cash service not available
N4
Cash request exceeds issuer or approved limit
N5
Ineligible for resubmission
N7
Decline for CVV2 failure
N8
Transaction amount exceeds preauthorized approval amount
Q1
Card Authentication failed
R0
Stop Payment Order
R1
Revocation of Authorization Order
R2
The transaction does not qualify for Visa PIN
R3
Revocation of All Authorizations Order
T0
First-time check
T1
Check is OK but cannot be converted
T2
Invalid Routing Transit Number or check belongs to a category that is not eligible for conversion;
Transaction failed ABA check digit validation
T3
Amount greater than established service limit
T4
Unpaid items, failed negative file check
T5
Duplicate check number
T6
MICR error
T7
Too many checks (over merchant or bank limit)
Y1
Offline-approved
Y3
Unable to go online; offline-approved
Z1
Offline-declined
Z3
Unable to go online; offline-declined
July 21, 2017
Visa Confidential
67
Action Code
mVisa API Technical Specification
July 21, 2017
Visa Confidential
68