VeriTrans4G Unified API (1.1.1 RC)
Download OpenAPI specification:Download
It describes the common items for carrier payments (*) as well as the items specific to each carrier payment.
(As one of the methods of consumer payment, it is possible to select Telephone charges total payment.)
In case of this guide, the 'carrier' refers to the following providers:
- Docomo
- au
Each carrier will send an email to the consumer at the time of OpenID issuance, authorization, etc.
Note that this e-mail will not be sent if the Testing ID and requestMode are set in the sandbox.
The table below lists each carrier/service and the timing of email transmission.
| Carrier/Service | Transmission Timing | ||||||
| At the time of OpenID issuance | At the time of Payment Request (Authorization only) | At the time of authorization cancellation | At the time of Capture | At the time of Capture Cancellation | At the time of On-demand payment (Authorization only) | ||
| d Payment | Total payment | None | ○ | None | None | △ (Partial refund only) |
○ |
| Docomo account payment | None | △ | ○ | None | ○ | None | |
| auPAY (au Easy Payment), auPAY (Online payment) | ○ | None | None | ○ | ○ | None | |
・d payment
| Payment Method | Delivery Timing | Delivery | Contact Contents |
| Total payment | At the time of Single Payment | sp-mode mail |
Notification of usage details *The body of the email will contain the following information. [Detailed Information] ・The site name you registered at the time of merchant registration application ・Item information (name) at the time of uest (Pay) [Usage Charges] ・Payment amount (amount) at the time of est (Pay) [Payment Type] ・Payment Type (Single Payment) at the time of |
| Docomo account payment | At the time of Single Payment | Message R |
Notification of withdrawal details *The body of the email will contain the following information. [Usage Charges] ・Payment amount (amount) at the time of est (Pay) |
| Docomo account payment | At the time of authorization cancellation | Message R |
Notify the purchase cancellation amount *The body of the email will contain the following information. [Cancellation Amount] ・Payment amount (amount) at the time of est (Pay) |
| Total payment | At the time of partial refund | sp-mode mail |
Notification of partial refund details *The body of the email will contain the following information. [Usage Charges (Before Change)] ・Payment Amount before partial refund [Usage Charges (After Change)] ・Payment Amount after partial refund [Scheduled payment month] ・The billing year and month for the changed amount |
| Docomo account payment | At the time of partial refund | Message R |
Notify the refund amount *The body of the email will contain the following information. [Refund Date and Time] ・Date and time when the merchant processed the partial refund [Refund Amount] ・Amount refunded through partial refund and credited to the Docomo account |
| Docomo account payment | At the time of payment cancellation | Message R |
Notify the purchase cancellation amount *The body of the email will contain the following information. [Cancellation Amount] ・Payment amount (amount) at the time of est (Pay) |
| Total payment | At the time of On-demand payment | sp-mode mail | Notification of usage details *The body of the email will contain the following information. [Detailed Information] ・The site name you registered at the time of merchant registration application ・Item information (name) at the time of On-Demand Payment Request (Subscribe) [Payment Type] ・Payment Type (On-Demand Payment) at the time of On-Demand Payment (Charge) |
・auPAY (au Easy Payment), auPAY (Online payment)
| Charge type | Transmission Timing | Contact Contents |
| Single payment, On-demand payment | At the time of OpenID issuance |
ID linkage notification email *The body of the email will contain the following information. [Partner Name] ・[Company Name Abbreviation] specified by the store at the time of payment request for carrier payment. |
| Single payment, On-demand payment | Capture settlement/ authorization & Capture settlement |
Capture Settlement Email *The body of the email will contain the following information. [Partner Name] ・[Company Name Abbreviation] specified by the store at the time of payment request for carrier payment [Service Name] ・The store's [Site name for user display] specified at the time of the payment request for carrier payment [Description] ・Item information (name) at the time of uest (Pay) [Product Type] ・The type of product provided by the merchant will be displayed. [Contact Information] ・The store will send the [Contact Information: telephone number] specified at the time of the payment request for carrier payment [Item Amount] ・Payment amount (amount) at the time of est (Pay) |
| Single payment, On-demand payment | Capture cancellation |
Capture Cancellation Email *The body of the email will contain the following information. [Partner Name] ・ [Company Name Abbreviation] specified by the store at the time of payment request for carrier payment [Service Name] ・The store's [Site name for user display] specified at the time of the payment request for carrier payment [Description] ・Item information (name) at the time of uest (Pay) In the case of Recurring Payment, before the above, specify contents from the Payment Server to the effect of "Billing on ○○ day of every month". [Product Type] ・The type of product provided by the merchant will be displayed. [Contact Information] ・The store will send the [Contact Information: telephone number] specified at the time of the payment request for carrier payment [Item Amount] ・Payment amount (amount) at the time of est (Pay) |
| Single payment, On-demand payment | At the time of partial refund |
Amount change email *The body of the email will contain the following information. [Partner Name] ・[Company Name Abbreviation] specified by the store at the time of payment request for carrier payment [Service Name] ・The store's [Site name for user display] specified at the time of the payment request for carrier payment [Description] ・Item information (name) at the time of uest (Pay) [Contact Information] ・The store will send the [Contact Information: telephone number] specified at the time of the payment request for carrier payment [Changed Amount] ・Refund Amount (amount) at the time of Cancel (Cancel) *Displayed as a negative amount. *If you do not specify an amount when canceling, the remaining balance from the partial refund will be displayed. |
The Item Name corresponding to the Payment-specific Order ID (providerOrderId) is the following name, respectively.
| Carrier | Item name (number of digits) |
| d Payment | Payment number (12 digits) |
| auPAY (au Easy Payment) / auPAY (Online payment) | Slip number (16~19 digits) |
In the page redirection on the Docomo side in the Payment Request, the page display for entering the SP mode password is as follows.
Display example of Smartphone
On this page, the "Payment Details" displays the contents of the merchant's contract.
However, in the case of a blanket contract, the "Item type (commodityType)" specified in the Payment Request determines the contents to be displayed.
Display contents of payment details
| Combination | Displayed contents |
| Digital contents + Single payment | Digital contents (Single payment) |
| Sale of goods/Service + Single payment | Sale of goods (Single payment) |
The merchant's name will appear as "DG Financial Technology Inc.".
Detailed information is a 2- row configuration.
'Site name' of merchant is displayed in the first row .
Value of 'Item information (name)' specified in the payment request is displayed in the second row.
If the payment request is completed (successful at Docomo side), mail is sent to the consumer from Docomo.
'Payment details', 'Merchant name', 'Detailed information' displayed in the Confirmation page are described even in this mail.
From December 2015, for d Payment, fingerprint and iris biometric authentication is possible on terminals equipped with the biometric authentication function.
(Merchant that concludes the payment aggregator contract will not use it in December 2015. The day of starting this use is currently being considered.)
For biometric authentication function, there is correspondence between pre-installed browser (standard browser and Chrome browser of the terminal ) only at the mobile terminal.
Biometric authentication function is not used in the browser other than this or the browser in the unique merchant application (WebView).
*Precautions when Browser in Unique Merchant Application (WebView) is Used
-
Docomo uses UserAgent (hereinafter referred to as"UA") to determine which devices and browsers can use the biometric authentication function. If all of the following conditions are met, the biometric authentication button is displayed, and if this button is selected, an error message "page not found" is displayed because WebView does not support this function.
Condition 1: WebView is used in service application
Condition 2: It results in the mounting that returns the UA information same as standard browser
Condition 3: docomo ID log- in page and Payment page are displayed in WebView
It should be handled as follows for avoiding this.
*When unique UA that differs with standard browser is already used, it need not be specifically handled.
At the end of UA used in WebView,"/(Optional string)"is added.
*Strings are Single byte alphanumeric characters
Example: In case of F-04G
・UA of standard browser:
Mozilla/5.0 (Linux; Android 5.0.2; F-04G Build/V14R36F) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0
Chrome/37.0.0.0 Mobile Safari/537.36
・Unique UA:
Mozilla/5.0 (Linux; Android 5.0.2; F-04G Build/V14R36F) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0
Chrome/37.0.0.0 Mobile Safari/537.36/nobioauth
Precautions when an error occurs in the partial refund request
-
If partial refund is done in the following cases, processing by the Docomo side system may not be in time and an error may occur.
| Target case | Error code | |
| resultCode | vResultCode | |
| If a partial refund is made immediately after Capture | UA-PRV-001 | WG20 |
| If a partial refund is made again immediately after a partial refund is made | UA-PRV-002 | WG11 |
If you receive the above Error Code in this case, wait a while and then re-execute.
About the priority for refunds at the time of partial refund
-
Partial refund of d Payment will be refunded in the following order:
The amount is preferably reduced (refunded) from the payment method (telephone charges total payment) which is used as basis at the time of payment, and then the amount is reduced (refunded) from Docomo amount appropriation, followed by d points appropriation.
Example: For a payment amount of 300 yen (100 yen via telephone charges total payment and 200 yen via Docomo account credits), if a 200-yen reduction is issued, 100 yen will be refunded to the telephone charges total payment, and 100 yen will be refunded to the Docomo account. As a result, 100 yen charged to the Docomo account will remain as the amount to be billed.
About d points refund
-
When the merchant performs adjustment processes such as cancelling or reducing the amount for the payment made by appropriating d points, the appropriated d points will be refunded to the user.
However, if the points to be refunded have already expired at the time the merchant performs adjustment processes such as a cancellation or reduction process, the points will not be refunded to the user (the merchant's cancel or adjustment process will be processed normally).
If the completion process by the merchant is not completed successfully by the final deadline for the completion request, the usage points are returned to the user.
Flow up to the start of service
-
The following is an explanation of the process flow up to the start of service when a merchant signs a direct contract with Docomo and introduces VeriTrans4G's d Payment.
-
Contract with Docomo
The following ID will be issued upon contract. This ID is required for URL registration, connection test application, etc.
- IPID・・・ID for identifying merchants
- Site ID・・・ID for identifying site of merchant (necessary for connecting from our system to Docomo's system)
- Sub ID・・・ID for logging in to the BP site
-
URL registration at BP site
Log in to Docomo's Merchant Administration Portal "BP site" and register the necessary information for system connection, such as our interface URL.
*Registration work can be carried out by our company.
-
Application for connection test period
In order to conduct the connection test, we will apply to Docomo for the connection test period.
For details on how to apply, please check Docomo's document "d Payment _ Connection Test Procedure".
Please make the following information in the notice when applying.
"[VeriTrans PF] merchant name (site ID)"
-
Implementation of connection test
We will conduct a connection test with our company and Docomo in the merchant's test environment.
For the contents of the test, please check Docomo's document "d Payment _ Connection Test Check Sheet (Single payment)".
*If you can show the test environment, we can do it on our side instead.
-
Submission of the connection test result
Submit the connection test result to Docomo.
For the method of submission, please check Docomo's document "d Payment _ Connection Test Procedure".
-
Start of service
After Docomo's approval of the result of the connection test, service provision can be started.
*For details, please contact our company sales or technical support.
Precautions at the time of using BP site
-
On Docomo's Merchant Administration Portal "BP Site", you can perform operations such as capture and cancel for transactions.
However, if you perform such operations from the BP Site, the results will not be reflected in our system, which may cause inconsistencies in the transaction data status between Docomo and our company.
Therefore, please implement capture and cancellation from our MAP (Merchant Administration Portal).
Target Type: auPAY (au Easy Payment)
auPAY (au Easy Payment) offers two types of payment methods: a payment method that uses the au ID authentication infrastructure based on the OpenID protocol, and a payment method that performs authentication and payment within the au PAY application.
The case where au ID authentication platform is used is described below.
When using the au ID authentication infrastructure, two authentication methods are provided: "au ID Login," which uses an au ID for authentication, and "ID Linkage," which uses the unique ID of the merchant's site for authentication. Either of the authentication methods must be used to use auPAY (au Easy Payment).
The "au ID Login" and "ID Linkage" functions can be used by switching the Settings value of the parameter "Login Type (loginType)" during Payment Request and On-Demand Payment Request.
*When it is not set, it is 'ID linkage'.
*Be sure to use "au ID Login" when providing auPAY (au Easy Payment) without performing your own user authentication on the merchant's site (without having the user log in to the merchant's site).
ID linkage
-
It is a method in which the merchant's unique ID is linked with the au ID, and member management and authentication are performed using the Open ID issued by KDDI together with the merchant's unique ID.
Merchant site is authenticated by unique ID. To link a unique ID with an au ID, end users need to enter their au ID and password only for the first time.
au ID log-in
-
"au ID Login" is a method in which users log in to the merchant's site by entering their au ID and password, and member management and authentication are performed based on the OpenID issued by KDDI.
Merchant site is authenticated by au ID.
■ Pattern for which OpenID issued from KDDI cannot be used is as shown below.
- When end users themselves terminate the linkage from WEB on their PCs/Mobile phones
- When end user does not carry out any of the following within fixed term (1 Year)
- Authentication/Payment process of au ID and merchant site unique ID
- Login to merchant site by au ID
- auPAY (au Easy Payment) processing for merchants' sites
- When an end user has cancelled the contract or has transferred the communication service
Target Type: auPAY (au Easy Payment)、auPAY (Online payment)
To use partial refund, it is necessary to apply to KDDI. When using the partial refund, please contact the sales representative or technical support.
Even if a partial refund is possible, depending on the Payment Method selected by the Consumer at the time of the Payment Request, resultCode=UA-CST-001 and vResultCode=WG24 may be refunded upon the partial refund request.
Since partial refund can not be done in this transaction, study the refunding with alternate means.
Target Type: auPAY (au Easy Payment)
- When On-Demand Payment has usage consent, there is no notification from KDDI to the Consumer, so stores are requested to display the Payment Request Completion screen to the Consumer or notify the Consumer by e-mail if necessary.
-
Since the authorization limit for Payment Request Contents cannot be reserved in advance in On-Demand Payment's usage consent, the process may fail if the Consumer's spending limit is exceeded during On-Demand Payment.
Please explain (show) the above information to the consumer at the time of usage consent, and ensure that items are provided only after settling the Capture Settlement. -
If an error occurs in the Capture settlement, please consider the following measures.
Error Code in Capture settlement Failure Notification to Consumers resultCode vResultCode UA-CST-001 WG39 Necessary WG40 Error codes other than above Optional - Failure Notification to Consumers
-
If the error code in the Capture settlement is resultCode=
UA-CST-001and ResultCode=WG39, or resultCode=UA-CST-001and ResultCode=WG40, the Capture Process cannot be performed due to a Consumer error.
Please consider notifying the consumer of the Capture failure and, if necessary, make the failed Capture with an alternative payment method.
For other error codes, please refer to "Possible Reasons" and "Corrective Action" in the "Result Codes list" and consider how to respond accordingly.
- When On-demand yment's usage consent termination processing is performed or Deregistration notification (Deregistration) is received, respond to the On-demand termination notification to the Consumer via screen display, e-mail, or by other appropriate means.
- Consider an easy-to-understand interface on the merchant store's page so that consumers can smoothly complete the termination process for the On-Demand Payment.