VeriTrans4G Unified API (1.1.1 RC)

Download OpenAPI specification:Download

Overview

Introduction


This guide is intended for developers using the VeriTrans4G Unified API and provides supplementary information.
It describes the common items for carrier payments (*) as well as the items specific to each carrier payment.

Each telecommunications provider that provides payment services that can be authenticated only with ID/password is referred to as a ''carrier''.
(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

Common Items for Carrier Payment

About Emails Sent from Carriers to Consumers


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.

Item Name for Payment-specific Order ID for Each Carrier ID in Payments


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)

Docomo

About contents displayed on the Payment confirmation page


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.

Notes about Mails Sent to the Consumers from Docomo


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.

About Biometric Authentication Function


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

About Cancel


 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.

About a Direct Contract with Docomo


 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.
    *For details, please contact our company sales or technical support.

    1. 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

    2. 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.

    3. 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)"

    4. 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.

    5. 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".

    6. Start of service
      After Docomo's approval of the result of the connection test, service provision can be started.


 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).

au

End Users Authentication


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

About Partial Refund


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.

Special Notes on On-Demand Payment


Target Type: auPAY (au Easy Payment)

  1. 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.
  2. 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.
  3. 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-001 and ResultCode=WG39, or resultCode=UA-CST-001 and 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.

  4. 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.
  5. 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.

Revision History

Version Release Update
1.1.0 RC 2025/06  Newly created
1.1.1 RC 2025/09
  1. Added and modified the following items:
    • au
      • Changed the au Easy Payment service name to auPAY (au Easy Payment).
    • Docomo
      • Deleted "About the Capture/Cancellation Request Status"