Open API >QR Code Payments >USSD Wallet Gateway
USSD Wallet Gateway
QR Code Payments Issuer Mobile Payment
UnionPay USSD is a product of for feature phone mobile payments. Through UPI system with API Interfaces, issuers in specific market will be able to support UnionPay USSD payment for its cardholders.
API Introduction
API Introduction
What is it?

UnionPay USSD payment can allow cardholder to make mobile payment by feature phone and GSM network. Merchant will display UnionPay USSD till number and the cardholder can enter bank’s USSD menu, input the till number other transaction information to make payment. This set of API allows issuer’s USSD Gateway to query merchant information linked to a UnionPay USSD merchant till number, so that UnionPay USSD payment can be supported.

Key Features

Open


The platform is open. Merchant USSD till number can be displayed along with merchant QRC. The transaction can be completed with any USSD menu that can support UnionPay USSD payment.


Security 


Security is a basic requirement for payments. UPI adopts Tokenization technology which supports risk control for whole transaction process, making sure of safety and preventing leakage of account information.


Integrity


UnionPay USSD payment sticks to 4-party mode which is almost the same with bank card transaction only except for the information interaction. UnionPay USSD payment has almost the same integrated mechanism of business, risk control, techniques as UnionPay QRC payment which makes user's capital secured.


When to Use it?

When UnionPay Wallet Issuers want to connect to UPI in order to support USSD payment.

Who Use it?
Issuer, Third-party Service Provider
Where to Use it?
USSD Wallet Gateway API is available in Africa Market.
Flow Chart
Flow Chart

USSD Wallet 流程图.png

1. Customer enter USSD menu and input till number and transaction info

2. Mobile phone send payment request via USSD

3. USSD Gateway send till number query request to UnionPay system

4. UnionPay responds mapping QR code to USSD gateway

5. USSD Gateway sends QRC payment request to UnionPay

6. UnionPay sends QR code verification request to acquirer

7. Acquirer sends response to UnionPay

8. UnionPay sends payment request to issuer

9. Issuer sends payment response to UnionPay

10. UnionPay sends transaction notification to USSD gateway

11. USSD gateway send SMS transaction notification to mobile phone

12. UnionPay forwards the transaction notice to the merchant through the acquirer

API Reference
API Reference
  • TILL_NUMBER_INQUIRY
Interface description
The USSD gateway can initiate the USSD-based payment transaction to the UPI system using this interface
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Message Information msgInfo Object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory "1.0.0" Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory "A0001034420171230235959000033" It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code
Time Stamp timeStamp N 14 M:Mandatory "20170714235959" The value in the response must match the value in the request. Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory "TILL_NUMBER_INQUIRY" Valid Value: "TILL_NUMBER_INQUIRY"
Wallet ID walletID AN 8 M:Mandatory "00010344" The unique value associated to a wallet. In the USSD-based transaction, it refers to the identifier of USSD gateway.
Transaction Information trxInfo Object M:Mandatory
Device ID  deviceID ANS 1-64 M:Mandatory The unique value associated to a device. In the USSD-based transaction, it is filled with the phone number for feature phone. The phone number format is defined in [ITU-T E.164]. Components: Country code (1-3 digits) + “-” + subscriber number. It is used to match a transaction to subsequent messages within a transaction set. The transaction identifier will be the same in all related messages: MPQRC Payment, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the USSD gateway initiates any day. Components: “A”+Wallet ID+ Serial Code.
Transaction ID txnID AN 17-49 M:Mandatory "A0001034420171230235959000091"
Merchant’s Till Number tillNo N 5-10 M:Mandatory The Merchant’s Till Number being displayed on the Merchant’s side is allocated by the UMPS system.
Certificate and Signature certificateSignature Object M:Mandatory
Application Signature Certificate ID appSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The USSD gateway uses the private key of this certificate for signature.
Signature signature ANS 1-2048 M:Mandatory
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message Information msgInfo Object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory "1.0.0" Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory "A0001034420171230235959000033" It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates any day. The value in the response must match the value in the request.Components: “A”+Wallet ID+ Serial Code
Time Stamp timeStamp N 14 M:Mandatory "20170714235959" The value in the response must match the value in the request. Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory "TILL_NUMBER_INQUIRY" Valid Value: "TILL_NUMBER_INQUIRY"
Wallet ID walletID AN 8 M:Mandatory "00010344" The unique value associated to a wallet. In the USSD-based transaction, it refers to the identifier of USSD gateway.
Transaction Information trxInfo Object M:Mandatory
Device ID  deviceID ANS 1-64 M:Mandatory The unique value associated to a device. In the USSD-based transaction, it is filled with the phone number for feature phone. The phone number format is defined in [ITU-T E.164]. Components: Country code (1-3 digits) + “-” + subscriber number. It is used to match a transaction to subsequent messages within a transaction set. The transaction identifier will be the same in all related messages: MPQRC Payment, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the USSD gateway initiates any day. Components: “A”+Wallet ID+ Serial Code.
Transaction ID txnID AN 17-49 M:Mandatory "A0001034420171230235959000091"
Merchant-presented QRC Payload mpqrcPayload S 1-512 M:Mandatory It contains the raw payload data in the Merchant-presented QRC, which is corresponding to the Merchant’s Till Number.
Message Response msgResponse Object M:Mandatory
Response Code responseCode AN 2 M:Mandatory "00" It contains a code that defines the response to a request.
Response Message responseMsg S 1-100 M:Mandatory "Approved" It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the Consumer of the payment outcome.
Certificate and Signature certificateSignature Object M:Mandatory
UMPS Signature Certificate ID umpsSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The UMPS system uses the private key of this certificate for signature.
Signature signature ANS 1-2048 M:Mandatory
Sequence Chart
Sequence Chart

USSD-based Payment

In a USSD-based transaction, the Consumer can make a purchase on a feature phone via USSD messages. After the Consumer inputs a code string (e.g. *#150#) provided by Issuer to enter STK menu and chooses UPI network from the menu, the Consumer shall input Merchant’s Till Number, transaction amount, PIN, and confirm the transaction. Then the USSD gateway can initiate the USSD-based payment transaction to the UPI system. The message flow is as follows.

时序图1.png

1. After the Consumer inputs Merchant’s Till Number, transaction amount, PIN, and confirms the transaction on a feature phone, the USSD gateway will submit a TILL_NUMBER_INQUIRY request message to the UPI system.

2. The UPI system returns the Merchant-presented QRC payload corresponding to the Merchant’s Till Number to the USSD gateway in the TILL_NUMBER_INQUIRY response message.

3. The USSD gateway sends the MPQRC_PAYMENT_EMV request message to the UPI system. The following steps are consistent with the steps in Figure 1: Flow of Merchant-presented QRC-based Payment (EMV mode).

Exceptional flow: 

•USSD gateway: When the USSD gateway does not receive the TILL_NUMBER_INQUIRY response message within 10 seconds from the UPI system, the USSD gateway may initiate the inquiry again.


Steps to Launch
Steps to Launch

The prerequisite of USSD Wallet is to support merchant-presented QRC payment at system level. The USSD platform should be owned and operated by the issuer, and the issuer should apply for a new wallet ID which is especially used for its USSD wallet.

For issuer, please contact Developer Team.


  • Contact Us
  • If you have any further questions, please register and submit order in your user center.