Download OpenAPI specification:Download
This guide is intended for developers using the VeriTrans4G Unified API and provides supplementary information.
It includes both common items applicable to all payment types and items specific to individual payment types.
When a consumer makes a payment, the provider's application is launched by redirecting from the merchant's site, and after the payment is completed, the "standard browser" is launched and the URL for page redirection (successUrl/cancelUrl/errorUrl) is called in a new tab.
Hence, As a result of this behavior, it is possible that session information and other information from the merchant's web app may not be passed on, but even in such a case, please implement the system so that it can receive and successfully process the payment results linked via the browser from our payment server.
Payment request and On-demand payment request are made on the merchant app screen, and after the consumer completes the payment with each payment provider app, a redirect is executed via a standard browser. At that time, in order to return the consumer line of flow to the merchant app after payment is completed, a landing page must be created to launch the merchant app.
Therefore, please specify the URL of the created landing page in the URL for Page redirection (successUrl/cancelUrl/errorUrl) for Payment Request (pay) and On-Demand Payment Request (subscribe).
At this time, the landing page is displayed in the "standard browser" of the consumer environment.
Here is a sample HTML page for a case where you want to redirect to a merchant application with the following settings:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>App Launch</TITLE>
</HEAD>
<SCRIPT language="javascript" type="text/javascript">
window.location.href = "unifiedApisample://www.example.com/result";
</SCRIPT>
<BODY>
Launch the ○○ app.
</BODY>
</HTML>
A common setting for all commands is the data retention period, which is 400 days.
If the data is not used and the retention period is exceeded, it will no longer be accessible.
The table below outlines the time frame within which each process request can be made for each payment type.
These time frames are determined by the payment provider and are not validated by the VeriTrans4G Unified API.
| Payment Type | API | Period up to which each request can be placed | |
| PayPay | Capture | Up to the payment request expiration date *1 | |
| Cancel before Capture | |||
| Cancel after Capture | 365 days, starting from the day after the payment request date (or the On-Demand Payment date in the case of an On-Demand Payment) | ||
| On-Demand Payment | 365 days, counted from the last On-Demand Payment date or On-Demand Payment request date *2 | ||
| Rakuten Pay | Capture | Up to 365 days from the payment request date (Payment request date), and up to 30 days after the last payment request date | |
| Cancel before Capture | Up to 365 days from the payment request date | ||
| Cancel after Capture | Up to 365 days from the payment request date, and up to 30 days from the capture date | ||
| On-Demand Payment | 400 days, counted from the last On-Demand Payment date or On-Demand Payment request date *3 | ||
| Docomo | d Payment | Capture | 20:00 of Last day of next to next month considering payment request day as the initial date |
| Cancel before Capture | |||
| Cancel after Capture | 20:00 of the 180th day including the payment date (179th day after the payment date) | ||
| On-Demand Payment | 400 days from On-Demand Payment Request date *3 *4 | ||
| au | auPAY (au Easy Payment) | Capture | After 90 days from the payment request date |
| Cancel before Capture | |||
| Cancel after Capture | Last day of the second month following the capture settlement day | ||
| On-Demand Payment | 400 days from On-Demand Payment Request date *3 *4 | ||
| auPAY (Online payment) | Capture | After 45 days from the payment request date | |
| Cancel before Capture | |||
| Cancel after Capture | 90 days considering capture settlement day as the initial date | ||
| On-Demand Payment | 400 days from On-Demand Payment Request date *3 *4 | ||
| Merpay | Capture | 60 days from acquiring authorization | |
| Cancel before Capture | |||
| Cancel after Capture | 365 days from capture settlement | ||
| On-Demand Payment | 1 year, counting from the last On-demand payment date or On-demand payment request date | ||
UA-REQ-006 when the On-demand payment is executed, and the payment process will result in an error.Until the payment is successfully processed (i.e., Settlement of 'Authorization with Capture', Authorization settlement, or Consent settlement), you can retry using the same paymentId.
However, if the paymentId is executed again before the payment failure is confirmed, it may result in a double order depending on the timing.
(resultCode= UA-000-002)
In that case, please check the order information in MAP (Merchant Administration Portal) and cancel the order which is not required.
The Unified API considers the first successful order as valid, and any subsequent successful orders will not be processed.
For example, if the fepOrderId of the first successful payment is "fepOrderId_01" and the fepOrderId of the second successful payment is "fepOrderId_02", only "fepOrderId_01" will be eligible for further processing in FEP.
The payment limit per transaction is as follows:
| Payment Method | Upper Limit of Payment Amount |
|---|---|
| PayPay balance | 1,000,000 Yen |
*The details are subject to the specifications of each payment provider. For the latest updates, please refer to the following site. Note that the URL may change.
《PayPay》 https://paypay.ne.jp/help/c0043/
The Payment Request Expiration Date for the transaction is defined as "from the time of the payment request to the same time after the specified number of expiration days".
At the time of the payment request, the order is in a state where only the payment request has been made.
Please complete the capture process after obtaining the payment request and before the expiration date.
The method for setting the Payment Request Expiration Date on the Merchant Side is shown below.
Settings can be changed from various settings change pages of the MAP.
(1) Specify the number of days until the payment request expiration date.
Set the number of days (1–30) in the "Number of Days Until Payment Request Expiration Date" field.
The default expiration date limit set by the payment provider is 30 days.
However, if the limit has been shortened in coordination with the payment provider, setting a value that exceeds this limit will result in an error during the application process.
Example: If the maximum number of days for the merchant is set to 20 days, setting it to 30 days in the MAP will result in an error during the payment request.
(2) Use the expiration days you applied directly to PayPay.
The maximum expiration days that can be set in the MAP is 30 days.
If you want to apply a number of days that exceeds this upper limit, you need to apply to the payment provider and adjust the upper limit.
For more details regarding payment requests, please contact us.
When using the requested value,
make sure to check the "Apply the value you applied for PayPay" checkbox and save the settings.
Change Various Settings> Change Various Payment Settings> PayPay> Payment Request Expiration Days
UA-REQ-006 and vResultCode=1G24 will be returned as the detailed result codes. (The maximum number of times is restricted by the payment provider.)UA-PRV-001 and vResultCode=1G13 will be returned as the detailed result codes.
There is a time limit to complete the payment which starts when the consumer is being redirected from the merchant site to PayPay site, and lasts until the consumer makes the payment.
If the time limit is exceeded, the payment request process by the consumer (payment in the case of Single Payment) cannot be completed.
In such cases, please inform the customer to perform the payment request process again, right from the start.
| Payment Type | Time Limit |
|---|---|
| Simple Payment | 5 minutes |
| On-Demand Payment | 15 minutes |
Contract cancellation for an On-Demand Payment order, is made on a merchant basis.
Due to the specifications of the payment server, the contract cancellation process for each payment request order is processed individually.
As the contract cancellation unit is per merchant, all other orders from the consumer associated with the order for which the contract cancellation was requested, will be cancelled.
For example, a consumer is applying for On-Demand Payment orders A, B, and C at XX merchant.
The following shows the case where the contract cancellation process is performed for [Order A].
The consent status of each order after the contract cancellation process and the presence or absence of deregistration notification are as follows.
| Order | Consent Status of On-Demand Payment | Deregistration Notification |
|---|---|---|
| Order A | Cancellation of Contract | - |
| Order B | Consent | None |
| Order C | Consent | None |
[Order B] and [Order C] for which no contract cancellation request is made on the payment server will remain with consent status.
If you try to perform the On-demand payment for these orders, the result code will return resultCode=UA-PRV-002 and vResultCode=1G19(the process has been canceled because the contract cancellation has already been completed for this order.).
The following shows a case where the consumer unlinks with XX merchant from the PayPay app.
The only operation that consumers can perform with the PayPay app is this "Unlinking with merchants", and contract cancellation operations for individual payment request orders are not possible.
The consent status of each order after unlinking from merchants, and the presence or absence of a deregistration notification are as follows.
| Order | Consent status of On-Demand Payment | Deregistration Notification |
|---|---|---|
| Order A | Deregistration | Yes |
| Order B | Deregistration | Yes |
| Order C | Deregistration | Yes |
When the PayPay app is operated to delink from the merchant, the payment server will send a deregistration notification.
Notifications will be sent for each order. Please receive the deregistration notification and update the order information on the merchant site.
For PayPay (Online Payment), the timing and contents of the push notification from PayPay to the PayPay app are as follows:
About the Items displayed in Push Notifications
| No | Item Name | Description |
| 1 | Amount | Payment amount/Refund amount. |
| 2 | Order ID | The number issued by PayPay.
This number is used by consumers in case of contacting PayPay. We will link this number in the following items. [Single Payment] In the result notification of the payment request and the order result acquisition, it will be linked as 'providerOrderId (payment-specific order ID).' [On-Demand Payment] On-demand payment response. In the result notification of the On-demand payment and the order result acquisition, it will be linked as 'providerOrderId (payment-specific order ID).' |
| 3 | Store Name | Site name that provides products / services. It is the same value as 'service name' mentioned in the entry sheet at the time of contract. |
| 4 | Payment Request Validity | Payment request expiration date of an order. For details, refer to 'About the Expiration Date of a Payment Request (Single Payment)'.
Notification will be made only for 'Payment Request only' type orders. |
| Notification Timing | Single Payment | On-Demand Payment | Notification Item | Description |
| At the time of payment request completion | 〇 | - | Amount / Order ID / Store name / Payment request expiration date | Notification of purchase details.
For 'Payment Request only' type orders, notification of payment request contents. |
| At the time of cancellation completion | 〇 | - | Amount / Order ID / Store name | Payment request cancellation notification, when a cancellation process is performed for a 'Payment Request only' type of order. |
| At the time of capture completion | 〇 | - | Amount / Order ID / Store name | Capture settlement notification, when a capture process is performed for a 'Payment Request only' type of order. |
| Upon completion of an On-demand payment | - | 〇 | Amount / Order ID / Store name | Notification of purchase details. |
| When an On-demand payment balance is insufficient | - | 〇 | - | Insufficient balance notification.
Notification is sent when there is insufficient balance during an On-demand payment, irrespective of whether the consumer payment request is implemented or not. |
| At the time of refund completion | 〇 | 〇 | Amount / Order ID | Refund notification in case of cancellation process in an order after the Capture. |
To proceed with the integration, compliance with the regulations set by Rakuten Payments, Inc. is required.
For more details on the regulations related to optional features, including the examination of Rakuten Group's name, service name, logo, buttons, and other elements,
please contact Rakuten Payments, Inc.
Rakuten Payments, Inc. will contact the merchant to inform them about various chargeback-related procedures.
Since chargeback information is not linked to the FEP server, if a transaction subject to chargeback is canceled on the Rakuten system, the order status on the FEP server and payment server will remain as Capture-done, preventing the execution of subsequent commands.
If the service is not provided after the payment, the cancellation should be executed as soon as possible. After the payment request, Rakuten Points/Rakuten Cash will not be refunded once the cancelable period has passed.
If points with limited validity were used, please ensure that the Capture or Cancel is completed within the respective deadlines to avoid potential issues.
If a payment request exceeds the default time limit and neither Capture nor Cancel can be processed, the Rakuten Points/Rakuten Cash should be refunded directly to the consumer.
Please check the following items before using the payment request change command.
Please take note of the following precautions when processing payments with Rakuten Points:
Orders made by consumers using debit cards may be debited from the consumer's bank account each time a payment request change, partial capture, or partial cancellation is performed. After that, refund processing is usually performed automatically, but please note that the processing timing and method differ depending on the card company.
Timings of the emails sent to consumers from Rakuten Pay (Online Payment) are shown below.
| Transmission Timing | Email Contents |
|---|---|
| At the time of payment completion (Single payment) | Order confirmation email |
| At the time of payment request completion (On-Demand Payment) | Payment request confirmation mail |
| At the time of order cancellation | Cancellation acceptance email |
| At the time of payment completion (Single payment) (partial capture, partial cancellation, authorization change (amount change)) |
Amount change acceptance email |
The smart phone application implementation that uses WebView etc. is not supported.
* While there are cases where WebView has been used in practice, merchants must thoroughly test its functionality on their end to ensure there are no issues. Furthermore, please make sure to perform the test in a live environment.
Furthermore, it is difficult to verify in the Sandbox environment whether control is properly transferred from the merchant's app to the payment provider and back to the merchant's app.
Similarly, it is challenging to confirm behaviors where page redirects within a browser or WebView are expected but instead trigger the provider's app (or vice versa).
However, these behaviors may change due to modifications on the provider's side, typically without prior notice.
Each telecommunications carrier 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 combined payment.)
In case of this guide, the 'carrier' refers to the following providers:
The character encoding of the message that is sent to the payment server is UTF-8, but Shift-JIS is used on the carrier side interface.
Therefore, machine-dependent characters like some of the Shift-JIS (including MS932) characters cannot be used.
If unusable characters are set, then characters displayed on the consumer's screen may get garbled or the payment processing on the carrier side may fail, hence the payment server carries out the following verification to ensure that permissible double byte character strings are used.
| Characters that cannot be used | Workaround |
| "―" Double byte dash | Please consider substituting from the following usable characters. "‐" double byte hyphen "ー" double byte long vowel |
| "-" Double byte minus | |
| "~" Double byte tilde | |
| Other machine-dependent characters | Please consider substituting usable characters. |
In auPAY (au Easy Payment) and auPAY (Online payment), when there is a change in the contract status of the consumer at the time of a capture request (*), there may be a failure in settlement of capture, even if the authorization is still valid.
In this case, the Payment Server will return the Result Code values such that resultCode= UA-CST-001 and vResultCode=WG13.
For this order, authorization itself is cancelled at the KDDI side and since capture cannot be established for the said order, study the cancellation of orders and billing of alternate means after communication with the consumer.
To prevent issues resulting from this problem, consider shipping items and service provision after capture is successful.
Such specifications do not exist in d Payment. Capture is successful for the order for which authorization is complete, if it is within the authorization expiration date.
*Though contract status of the consumer has unpaid charges and circuit cancellation of contract, detailed information is not disclosed from KDDI.
When using the On-Demand Payment for auPAY (au Easy Payment) and web-based auPAY (Online payment), please set the information for the payment request item name according to the payment provider specifications.
| Format and Limitations | Double byte, maximum 24 characters |
| auPAY (au Easy Payment) | |
| Item name (service name) + billing timing | Example: Delivery of 5,000 yen worth of seasonal fruits ■Billed on the 1st of every 3 months *Make sure to include ■ (double byte space). |
| auPAY (Online payment) Web method | |
| Item name (service name) + Item code required when responding to customer inquiries | Example: XX service fee ■Item code: **** *Whether or not ■ (double byte space) is optional. |
Usage limit amount can be confirmed at the KDDI site.
https://kantan.auone.jp/service/communicationfee/#Section02
Usage limit amount can be confirmed at the KDDI site.
https://aupay.wallet.auone.jp/?link=faq
KDDI Corporation and Okinawa Cellular Telephone Company have established the Guidelines about provision of contents, to ensure the smooth operation of auPAY (au Easy Payment), so please confirm the following points in advance.
*When the following points are not observed, auPAY (au Easy Payment) may no longer be used.
Display contents at the merchant site
The amount that can be paid by the user varies depending on the payment account and the identity verification registration status of the Mercari application.
Please check the guide of the Merpay application for details.
Within "20 minutes" after receiving the payment request response, the consumer must be redirected to Merpay's payment page to complete the payment process.
If the time limit is exceeded, the consumer will not be able to complete the payment process and should be advised to start the payment request process from the beginning.
The personal information can be obtained from Merpay.
The only personal information that can be obtained is the one that has been approved in the examination at the time of payment request.
In addition, for merchants to receive the personal information, users must agree to provide personal information in the Mercari application.
If the user does not agree to provide personal information, the Mercari application executes the cancellation process and redirects the user to the cancelUrl specified in the request item at the time of payment request.
* Personal information will be notified only by the result notification message of the payment request.
Please note that you will not be able to get the personal information in case of failure to receive the result notification.
(For the result notification message, refer to "Webhook" under APIs in the Development Guide IF Specification.)
It is a list to be entered in the category ID.
Category ID is the information required to use the payment method, Merpay Smart Payment. Hence please set it appropriately.
The FSA guidelines require that when using Merpay Smart Payment, it should be clearly indicated under what item category the product is.(e.g., clothing, cosmetics, food, etc.).
Please note that Merpay Smart Payment is a payment method that can be selected by the consumer and cannot be made unavailable.
| Category name | Category ID | |
| Main Category | Sub Category | |
| Fashion | Clothing | 1010 |
| Accessories/Watches | 1011 | |
| Bags, accessories, brand miscellaneous goods | 1012 | |
| Home appliances | Domestic electrical appliances | 1110 |
| Smartphones and mobile phones | 1111 | |
| PC/tablet | 1112 | |
| TV / Video equipment | 1113 | |
| Peripheral equipment | 1114 | |
| Beauty | Cosmetics | 1210 |
| Medical products / Health foods | 1211 | |
| Entertainment | Video game | 1310 |
| Hobby | 1311 | |
| Musical instruments / Music equipment | 1312 | |
| Entertainment products | 1313 | |
| Gourmet | Food | 1410 |
| Liquor | 1411 | |
| Home / Living | Sofa / Bed | 1510 |
| Furniture | 1511 | |
| Daily necessities | 1512 | |
| Sporting Goods / Outdoors | 1513 | |
| Baby products | 1514 | |
| Books | 1515 | |
| Cars | Auto parts | 1610 |
| Other | Complimentary ticket / discount ticket / facility use ticket | 1710 |
| Cash voucher | 1711 | |
| Digital contents | 1712 | |
| Donation / tax payment | 1713 | |
| Other | 1714 | |
| Version | Release date | Update details |
| 1.0.0 RC | 2024/08 |
|
| 1.1.0 RC | 2025/06 |
|
| 1.1.1 RC | 2025/09 |
|