By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >Account Service >Virtual Card Control Platform
Virtual Card Control Platform
Account Service Merchant Issuer
The Virtual Card Control Platform (VCCP) provides the virtual card request and lifecycle management service for companies, such as Online Travel Agents (OTAs) and other Virtual Card Requestors (VCRs).
Sandbox Testing
API Introduction
API Introduction
What is it?

Virtual cards are used for procurement settlement in the following typical scenario: OTA companies apply for commercial cards from issuers, and request virtual cards from UPI Virtual Card Control Platform. Each virtual card has its own credit limit and applicable scope, including MCC(Merchant Category), MID(Merchant ID), etc.

The Virtual Card Control Platform (VCCP) provides the virtual card request and lifecycle management service for companies, such as Online Travel Agents (OTAs) and other Virtual Card Requestors (VCRs).


Who Use it?
Issuers and Travel Agencies
Where to Use it?
This API is available globally except for mainland China.
Things to Know

1. Travel Agencies apply for commercial cards from issuers, and request virtual cards from UPI VCCP. Each virtual card has its own credit limit and applicable scope, including MCC, MID, etc.

2. The virtual card number can be flexibly obtained through various channels (such as encrypted email).

3. Acquirer submits virtual card transaction as regular card transaction.

4. Virtual card can support RMB settlement.


API Reference
API Reference
  • REQUEST_VIRTUAL_CARD
  • RETRIEVE_VIRTUAL_CARD
  • UPDATE_TOKEN_STATE
  • REPLACE_TOKEN_DOMAIN
  • RETRIEVE_TOKEN_INFORMATION
Interface description
After the VCR user completes its internal authorization management procedure, REQUEST_VIRTUAL_CARD is for them to requests a virtual card.
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 Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the VCR initiates on any day. The value in the response must match the value in the request. “R” is used to indicate this request is generated from a VCR system. Components: "R"+ VCR ID +Serial Number
Time Stamp timeStamp N 14 M:Mandatory The value in response must match the value in the request. Format：YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "REQUEST_VIRTUAL_CARD"
VCR ID vcrID AN 16 M:Mandatory The distinctive value associated to a VCR.
Transaction Information trxInfo Object M:Mandatory
Login ID loginID ANS 1-2048 M:Mandatory The login ID of the VCR processor. It must be encrypted with the public key of the VCCP Encryption Certificate.
Primary Account Number pan AN 1-2048 M:Mandatory Encrypted with the public key of the VCCP Encryption Certificate
Note note S 1-255 O:Optional The VCCP will not process this field. In the "REQUEST_VIRTUAL_CARD" message, it can be used to explain the usage of the requested virtual card.
Order Number orderNo ANS 1-50 O:Optional The order number that triggers the message. The VCCP will not process this field
Single Transaction Limit singleTrxLimit NS 1-13 O:Optional The upper limit of a single transaction amount
Accumulated Transaction Limit accumulatedTrxLimit NS 1-16 O:Optional The upper limit of the accumulated transaction amount
Limit Currency Code limitCurrencyCode N 1-3 C:Conditional The currency code of Single Transaction Limit or Accumulated Transaction Limit. When both limits are present, they must be present with the same currency. Present if either "Single Transaction Limit" or "Accumulated Transaction Limit" exists in the message
Maximum Times of Use maxTimesUse N 1-3 O:Optional The upper limit of the allowed transaction count of the Token. The transaction will be declined by the UPI system once the transaction count exceeds this value. Valid Values: "1"-"999"
Merchant Category Code mcc N 4 O:Optional The Merchant Category Code. The virtual card is allowed to be used in this merchant type. Refer to the UPI Operating Regulations for the valid value.
Token Expiry Time tokenExpiryTime N 12 M:Mandatory This field indicates the Token Expiry Time the Token Requestor expects. But the Token Expiry Time will eventually be determined by the TSP. Format: YYMMDDhhmmss
List of Country listCountry Array 1-255 O:Optional The white list of country/region codes. The virtual card is allowed to be used in these countries. Each country/region code shall be Numeric-3 ISO 3166
List of Merchant listMerchant Array 1-255 O:Optional The white list of merchants. The virtual card is allowed to be used in these merchants. Each merchant can be uniquely identified by the combination of MID and Acquirer IIN.
Acquirer IIN acquirerIIN AN 1-11 O:Optional Currently the Acquirer IIN contains 8 characters.
Merchant ID mid AN 1-15 O:Optional Each MID shall be alpha and numeric characters only and shall not exceed 15 characters. The space is not allowed in the MID
Supported Channel Bitmap supportedChannelBitmap N 7 O:Optional The terminal type bitmap indicates if the Token can be used in the terminal type. Valid Values: 0: indicates that the Token must not be used in the terminal type; 1: indicates that the Token can be used in the terminal type. Terminal Type bitmap combination: First byte: ATM or counter; Second byte: Mobile; Third byte: PC; Fourth byte: Multimedia terminal; Fifth byte: Fixed phone terminal; Sixth byte: POS; Seventh byte: Others
Certificate and Signature certificateSignature Object M:Mandatory
VCR Signature Certificate ID vcrSignCertID N 1-128 M:Mandatory The serial number of the certificate. The VCR uses the private key of this certificate for signature.
VCCP Encryption Certificate ID vccpEncCertID AN 1-128 O:Optional The serial number of the certificate. The application uses the public key of this certificate for encryption. Present if encrypted information exists in the request message.
Signature signature ANS 1-100 M:Mandatory Please refer to the Signature for details.
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 Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the VCR initiates on any day. The value in the response must match the value in the request. “R” is used to indicate this request is generated from a VCR system. Components: "R"+ VCR ID +Serial Number
Time Stamp timeStamp N 14 M:Mandatory The value in response must match the value in the request. Format：YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "REQUEST_VIRTUAL_CARD"
VCR ID vcrID AN 16 M:Mandatory The distinctive value associated to a VCR.
Transaction Information trxInfo Object M:Mandatory
Token token N 16-19 M:Mandatory Token PAN
Payment Account Reference par AN 29 M:Mandatory A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens.
Token State tokenState ANS 1-15 M:Mandatory Valid values: "ACTIVE"；"SUSPENDED"; "DELETED"
Token Begin tokenBegin N 14 M:Mandatory The Token effective time. Format：YYYYMMDDhhmmss
Token End tokenEnd N 14 M:Mandatory The Token expiry time. Format：YYYYMMDDhhmmss
Token Verification Number 2 tvn2 N 3 M:Mandatory The Token Verification Number 2. Its usage is the same as that of CVN2.
Message Response msgResponse Object M:Mandatory
Response Code responseCode AN 2 M:Mandatory It contains a code that defines the response to a request. Please refer to the Response Code and Message for the valid values.
Response Message responseMsg S 1-100 M:Mandatory It contains the message response and the rejection reason if the request is declined by the VCCP. The value of this field can be displayed by the VCR to notify the user of the outcome. Please refer to the Response Code and Message for details.
Certificate and Signature certificateSignature Object M:Mandatory
VCCP Encryption Certificate ID vccpEncCertID AN 1-128 M:Mandatory The serial number of the certificate. The application uses the public key of this certificate for encryption. Present if encrypted information exists in the request message.
Signature signature ANS 1-100 M:Mandatory Please refer to the Signature for details.
Sequence Chart
Sequence Chart

1. Request Virtual Card

1.Request virtual card.png

(1)After the VCR user completes its internal authorization management procedure, and requests a virtual card, the VCR shall submit a REQUEST_VIRTUAL_CARD message to the VCCP.

(2)The VCCP checks the authenticity of the user’s login ID and the PAN, requests a Token from TSP, establishes a virtual card profile, and sends the Token of the virtual card and related information back to the VCR in the REQUEST_VIRTUAL_CARD response message.

Exceptional flows: 

(1)When the VCR does not receive the REQUEST_VIRTUAL_CARD response message within 10 seconds, it can initiate a RETRIEVE_VIRTUAL_CARD message, using the Message ID of the REQUEST_VIRTUAL_CARD to check if the request of the virtual card is successful and retrieve the Token of the virtual card.

(2)The VCCP system will return the REQUEST_VIRTUAL_CARD outcome and the Token of the virtual card to the VCR.


2. Virtual Card State Management

2 virtual card management.png

(1)The VCR can change the Virtual Card through UPDATE_TOKEN_STATE, e.g., DELETED, ACTIVE.

(2)The VCCP checks the authenticity of the user’s login ID and changes the virtual card state in the system.

Exceptional flows: 

When the VCR does not receive the UPDATE_TOKEN_STATE response message within 10 seconds, it can resend the UPDATE_TOKEN_STATE request.


3. Update Virtual Card Control Information

3 update virtual card.png

(1)The VCR submits a REPLACE_TOKEN_DOMAIN request to update the Virtual Card Token Domain Restriction Control, including but not limited to:

• Single Transaction Limit  

• Accumulated Transaction  Limit

• Maximum Times of Use

• Merchant Category Code

• List of Country/Region

• List of Merchants

• Supported Channel

• Token Expiration

If a data element, for example, the Single Transaction Limit, is not present, the VCCP will consider that the VCR has no Single Transaction Limit restriction.

(2)The VCCP replaces the new Token Domain, and responds with the updated Token Expiration Time, and new TVN2.

Exceptional flows: 

When the VCR does not receive the REPLACE_TOKEN_DOMAIN response message within 10 seconds, it can resend the REPLACE_TOKEN_DOMAIN request.


4. Retrieve Virtual Card Control Information

4 retrieve vc.png

(1)The VCR submits the RETRIEVE_TOKEN_INFORMATION to inquire the Token Domain, Current Times of Use, Amount Used, etc.

(2)The VCCP returns the Virtual Card Restriction Control information.

Exceptional flows: 

When the VCR does not receive the RETRIEVE_TOKEN_INFORMATION response message within 10 seconds, it can resend the RETRIEVE_TOKEN_INFORMATION request.
Steps to Launch
Steps to Launch

Production Process

1.Issuer registers on UPI VCCP and issues primary UnionPay commercial card to OTA/Travel Agencies;

2.OTA/Travel Agencies connect with UPI VCCP through APIs, and then generate virtual card through APIs;

3.OTA/Travel Agencies send out virtual card to travel suppliers, and travel suppliers initiate transaction of virtual card.


Issuers and OTA/Travel Agencies are required to send following information to Developer@unionpayintl.com to have further assistance.

1. Company Name

2. Role (Issuer/OTA/Travel Agency)

3. Country

4. Contact Person

5. Contact Information
Response Code Reference
Response Code Reference
Response code Description
00 Approved
01 Please refer to the card issuer
03 Invalid merchant
04 Pending. Transaction result is unknown. Please check later
05 Cardholder verification fails
12 Invalid transaction
13 Invalid amount
14 Invalid card number
15 No such issuer
21 Card status error
25 Unable to locate the original transaction
30 Message format error
34 Fraud card
40 The transaction is not supported by the issuer
41 Lost card
43 Stolen card
51 Insufficient balance
54 Expired card
57 Transaction not permitted to cardholder
61 Exceeds approval amount limit
62 Restricted card
90 The system is in cut-off
91 Issuer system error
92 Network error
94 Duplicated transaction
96 UnionPay system error
98 Timeout
A0 Signature verification fails
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2022. All rights reserved