- introduction
  - Overview
    - Introduction
- supplement
  - Common Items for All Payment
    - Precaution Items for Payment Using Smartphones
    - About Data Retention Period
    - About API Request Submission Time Frames
    - About Double order
    - About Capture
  - PayPay
    - About the Payment Amount
    - About the Validity of Payment Request (Single Payment)
    - About Cancel
    - Time limit for the Consumer to Make Payments or Payment Requests
    - About Contract Cancellation Unit of an On-Demand Payment
    - Push Notification to PayPay App
  - Rakuten Pay
    - About the Regulations
    - About Chargeback
    - About Sales of Goods
    - Precaution Items at the Time of Payment Request
    - Precaution Items When Using Payment Request Change
    - About Payments where Rakuten Points have been Used
    - Using Debit Cards
    - About Mail Sent from Rakuten to the Consumer
    - Precaution Items for Implementing Smartphone Applications Using WebView etc
  - Docomo/au Common
    - About Machine-dependent Characters
  - au
    - About au's Payment Method
    - About the Issue of au's Authorization being Cancelled by KDDI
    - About the Formatting Settings of the au On-Demand Request Item Name
    - About auPAY (au Easy Payment)
    - Precaution Items for auPAY (Online Payment) Application Method
  - Merpay
    - About the Payment Amount
    - Time Limit for the Consumer to Make Payments or for Payment Requests
    - Precaution Items for Launching the Mercari Application in Smartphone Payments
    - Request for Personal Information (Shipping Address Information / Buyer Information)
    - Item Category ID List
- APPENDIX
  - Revision History

API docs by Redocly

# VeriTrans4G Unified API (1.1.2 RC)

Download OpenAPI specification:Download

# Overview

## Introduction

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.

# Common Items for All Payment

## Precaution Items for Payment Using Smartphones

### ■About Payment Using a Smartphone Browser

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.

- A different browser from the one that initiated the payment may be launched.
- Even when the payment is initiated in a standard browser, the process is completed 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.

### ■About Payment Using a Merchant App in a Smartphone

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.

#### ■Redirection Flow Diagram

#### ■Example of the landing page creation

Here is a sample HTML page for a case where you want to redirect to a merchant application with the following settings:

- URL scheme at the time of launch: unifiedApisample
- URL host at the time of launch: www.example.com
- URL path at the time of launch: result

    <!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>

※Before the release of the system, please ensure that thorough testing is conducted in the Live environment to confirm the actual operation.

## About Data Retention Period

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.

## About API Request Submission Time Frames

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

1. For details, please refer to "About the Validity of Payment Request (Single Payment)".
2. If the request period for carrying out the On-demand payment is exceeded, the "resultCode" in the result response will return `UA-REQ-006` when the On-demand payment is executed, and the payment process will result in an error.
   However, for On-Demand payments, the status will remain as "Consent," and the linkage with the merchant will not be removed from the PayPay app.
   As mentioned above, payment processing will not succeed after the expiration date.
   Nevertheless, we recommend that merchants explicitly perform the contract cancellation operation and terminate acceptance, to avoid inquiries from consumers due to status discrepancies.
3. Data will be deleted when the data retention period is exceeded.
4. If it is continuously used for On-demand payments, it will not be removed from the payment server even after 400 days from acquisition.
   However, if re-authorization is not performed for a certain period, carrier (Docomo/ au) will terminate the usage consent, and it becomes non-usable.

## About Double order

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.

## About Capture

### Partial shipping (Capture) of the goods sold

For a payment, a Capture can only be executed once per authorization.
If a Capture is divided into two or more parts due to partial shipping of the goods sold, such as for convenience of shipping of the goods etc., either obtain the authorization again at the time of the second or subsequent Capture, or execute the Capture after shipping completely.

# PayPay

## About the Payment Amount

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/

## About the Validity of Payment Request (Single Payment)

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

## About Cancel

### About Partial Refund

For partial refunds, the refund amount can be specified as long as it does not exceed the original payment amount.
However, due to restrictions on the payment provider's side, only one partial refund is allowed by default.
It is possible to enable the multiple partial refund feature in the payment provider's settings. Please contact us if you wish to activate this feature.
When using multiple partial refunds, please note the following points:

- If the maximum number of refunds is reached, resultCode=`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.)
- When issuing multiple partial refunds, the request interval must be at least one minute.
  Requests with a request interval of less than one minute will result in an error, and resultCode=`UA-PRV-001` and vResultCode=`1G13` will be returned as the detailed result codes.

## Time limit for the Consumer to Make Payments or Payment Requests

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

## About Contract Cancellation Unit of an On-Demand Payment

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.

## Push Notification to PayPay App

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.

Push Notification Timing and Notification Contents
※As notification content is dependent upon PayPay specifications, it is subject to change.

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.

# Rakuten Pay

## About the Regulations

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.

## About Chargeback

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.

## About Sales of Goods

### About Inventory Control

To avoid the risk of running 'out-of-stock', it is recommended to check inventory at the time of the payment request.
In addition, when the payment request results in a failure, if the results are not returned for a certain amount of time, we would request that the inventory be released.

### About Capture

For the sale of goods, capturing payment before shipping the items is strictly prohibited.
Always perform the capture after shipping the item, or slightly before or after if necessary. However, whenever possible, the capture should be executed immediately after shipping the item to the consumer.

## Precaution Items at the Time of Payment Request

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.

## Precaution Items When Using Payment Request Change

Please check the following items before using the payment request change command.

- If 3D Secure authentication was performed at the time of the payment request, 3D Secure will be invalidated in a Single payment if a payment request change (authorization extension/amount change) is performed. For On-demand payments, while 3D Secure can be called at the time of usage consent, 3D Secure will be excluded in the event of an On-demand payment.
  Please note that if 3D Secure authentication is invalidated or excluded, in the unlikely event of unauthorized use, the merchant may be responsible for chargebacks.
- Authorization extension is assumed to be used for reserved products exceeding 30 days from the order date.
  Please note that Rakuten Pay does not allow any other uses other than the abo

## About Payments where Rakuten Points have been Used

Please take note of the following precautions when processing payments with Rakuten Points:

- The number of points used may change if the payment amount is modified.
  In the event of a payment amount adjustment (e.g., partial Capture or partial Cancel), the reduction will prioritize the credit card usage amount. However, if the remaining amount is less than the points/cash initially allocated (hereinafter referred to as "points"), the point usage amount will be adjusted accordingly.
  For example, If a payment request is approved for an order totaling 1,000 yen, with 900 yen covered by points, and a partial Capture of 800 yen is confirmed, the point usage amount will be adjusted to 800 yen since the full amount is covered by points.
- The timing of point refunds to consumers when the point usage amount changes is as follows:
  If the order amount falls below the allocated point amount due to a cancellation process or a change in amount (partial Capture, partial Cancel), the points will be refunded to the consumer once each process is successfully completed.
  However, if points with limited validity were used and the cancellation date falls after their expiration date, the points will be invalidated and will not be refunded.
  Additionally, if a merchant does not complete the Capture or Cancel process within the designated request period (*1), the consumer's Rakuten Points will not be refunded and will remain as used.
  If a merchant does not process Capture or Cancel while Authorization is still available, and the request period expires, Rakuten will automatically cancel the order (no cancellation email will be sent to the consumer). However, merchants are encouraged to process Capture or Cancel on their own as appropriate.
  Since Rakuten points have already been debited at the time of authorization, please process subsequent orders. Since Rakuten points have already been debited at the time of authorization, leaving it without subsequent processing may lead to problems later.
  *1: For details regarding the available period for requesting Capture and Cancel, refer to About API Request Submission Time Frames.
- Please consider the following points when processing a payment request with Authorization only.
  If the service is not provided after the payment request has been processed, the cancellation process should be executed as soon as possible.
  Points will not be refunded if the cancellation deadline has passed after the payment request has been processed (Authorization only).
  If points with limited validity were used, please ensure that the Capture or Cancel process is completed within the respective deadlines to avoid potential issues.
  If a payment request (Authorization only) exceeds the default time limit and neither Capture nor Cancel can be processed, the points should be refunded directly to the consumer.

## Using Debit Cards

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.

## About Mail Sent from Rakuten to the Consumer

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

## Precaution Items for Implementing Smartphone Applications Using WebView etc

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.

# Docomo/au Common

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:

- Docomo
- au

## About Machine-dependent Characters

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.

- When a character is converted from UTF-8 to Shift-JIS and is converted back to UTF-8 once again, it should be the same as the original character.

Please note that if the following characters are included by this judgment, the relevant characters will be converted to before processing.

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.

# au

## About au's Payment Method

au has the following payment methods.

- auPAY（au Easy Payment）
- auPAY (Online payment) Web method
- auPAY (Online payment) Application method

The web method used (auPAY (au Easy Payment) or auPAY (Online payment)) depends on the contract between the merchant and KDDI. Therefore, it cannot be controlled by an API request.
When using the auPAY (Online payment) Application method, specify the application authentication method in paymentAuthenticationType (payment authentication method).
(For paymentAuthenticationType, please refer to "paymentInstrument.au" under APIs "Payment Request" in the Development Guide IF specification document.)

## About the Issue of au's Authorization being Cancelled by KDDI

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.

## About the Formatting Settings of the au On-Demand Request Item Name

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.

## About auPAY (au Easy Payment)

### About Usage Limits

#### ■ID Linkage and au ID Login

Usage limit amount can be confirmed at the KDDI site.
https://kantan.auone.jp/service/communicationfee/#Section02

#### ■ auPAY (Online payment)

Usage limit amount can be confirmed at the KDDI site.
https://aupay.wallet.auone.jp/?link=faq

### Guidelines about Provision of Contents

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

1. Are the contact details (Telephone number, E-Mail etc.) described by the merchant site at the place that user can understand easily?
2. Is the link to the page for service explanation provided by KDDI installed?
   [PC]https://id.auone.jp/payment/pc/guide/index.html
   [Smartphone]https://id.auone.jp/payment/sp/guide/index.html
3. When Recurring payment is integrated, are the contents for member cancellation of contract/Unsubscribe method prepared on the site?
   Also, is the link to Unsubscribing installed?
4. If you have a contract cancellation option from the Android app or a link to a contract cancellation page, have you provided instructions on how to redirect to there?
5. Even if the Android application is deleted, is there a line of flow for Unsubscribing?
*4 and 5 are for the use from the Android application.
6. Before the moment of contract, is the billing information (prices, billing interval, billing day etc.) displayed on the site or application?
   [Example of Single payment]
   Purchase once　...○○Yen

## Precaution Items for auPAY (Online Payment) Application Method

### ■About linking from merchant store apps to au PAY apps

If the consumer environment is a smartphone or tablet, the payment process is performed by launching the au PAY application on the consumer's terminal, and after the process is complete, the consumer is transferred to the merchant's site/application.br> If the au PAY app is not installed on the consumer terminal, a line of flow to the app store will be displayed, leading the consumer to install the au PAY app, and the payment cannot continue.
In such cases, since it is not possible to return to the merchant site/app, the consumer should be informed to make a payment request again from the merchant site/app after the app is installed.

Also, while redirecting to the au PAY payment page from the merchant's app, the app is launched by the deep link when the appropriate payment page is displayed, based on UserAgent judgment and branching on the KDDI system side.
Due to the OS or other requirements of the merchant's app, if the au PAY app launch by the deep link does not work properly, support from the merchant's app is required. Precaution items are listed below.

#### 1.Linking from WebView in the merchant application (Android)

For Android OS, we have confirmed that accessing deep link URLs from WebView does not work.
When calling the au PAY app from WebView in the merchant app, the merchant application needs to hook the WebView URL access event on the merchant application side and execute the URL access from the application.
Specifically, make the deep link「auwallet://aupay/v2/netservice?parameter=*」to the au PAY app executable by hooking it in the WebView process.

#### 2. Linking from WebView in the merchant app (iOS)

In iOS, we have also confirmed a instance where accessing a deep link URL from WebView does not work.
In such cases, when the universal link（https://aupay.auone.jp）to launch the au PAY app on WKWebView on iOS is detected, consider opening the URL in Safari.

### ■Linking au PAY app ⇒ merchant app

au After completing the payment in the au PAY app, if you want to take the consumer line of flow back to the merchant app, do so via a deep link via the landing page.
For details, please refer to「Precaution Items for Payment Using Smartphones」.

# Merpay

## About the Payment Amount

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.

## Time Limit for the Consumer to Make Payments or for Payment Requests

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.

## Precaution Items for Launching the Mercari Application in Smartphone Payments

### [Smartphone browsers] Issues due to differences in browsers at the start and completion of the payment process

When a consumer uses the EC site from a smartphone browser, the payment process is made through the Mercari application. Hence, the browser may be different when the process starts and when it is completed.
Due to the current Merpay specifications, only when the process is started in Chrome it is possible to return to Chrome upon completion if the userAgent is specified at the time of the payment request, but for browsers other than Chrome, you may be reverted to a different browser upon completion.
Please refer to the following Merpay specification document for more information on the issue.

https://netpayment.merpay.com/partner/integration-guideline/#/partner_order_completion?id=決済開始時と完了時でのブラウザの違いによる問題
ID : mp6822263272
PASS : 3R(qc&gFwNMp

Even for such an issue, please implement it so that you can receive the payment result linked from our payment server via the browser and process it normally.

### [Smartphone application (merchant application)] about launching the Mercari application

In order to launch the Mercari application in the payment originating from a smartphone application (hereinafter referred to as the merchant application), please open the redirectUrl using the API provided by each OS (iOS, Android).
The redirectUrl is registered as Universal Links for iOS and App Links for Android.
Please refer to the description in the Merpay specification document for notes on how to implement each OS.

https://netpayment.merpay.com/partner/integration-guideline/#/payment_on_smartphone_app
ID : mp6822263272
PASS : 3R(qc&gFwNMp

## Request for Personal Information (Shipping Address Information / Buyer Information)

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

### Shipping address information

By setting the Shipping address information type (deliveryAddressType), you can receive the shipping address information from Merpay during the payment process. This allows users to order the items seamlessly.

### Buyer information

By setting the buyer information type (buyerInfoType), you can receive buyer information from Merpay during the payment process.

## Item Category ID List

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

# Revision History

Version | Release date | Update details
| 1.1.2 RC | 2025/11 | Added the following related descriptions in accordance with the auPAY (Online payment) application method. au Added "About au's payment method". Added "Precaution items for auPAY (Online payment) application method"./li> Others: Minor wording and formatting corrections
1.1.1 RC | 2025/09 | Added and modified the following items: Common Items for All Payments Added 'Precaution Items for Payment Using Smart Phones'. PayPay Added 'Time Limit for the Consumer to Make Payments or Payment Requests'. Added 'About Contract Cancellation Unit of the On-Demand Payment'. Added 'Push Notification to PayPay App'. Corrected the upper limit of payment amount for balance payments, in 'About the Payment Amount'. Rakuten Pay Added 'Precaution Items at the Time of Payment Request'. Added 'Precaution Items When Using Payment Request Change'. Added 'Using Debit Cards'. Added 'About Mail Sent from Rakuten to the Consumer'. Changed the company name from 'Rakuten Group, Inc.' to 'Rakuten Payments, Inc.'. au Changed the au Easy Payment service name to auPAY (au Easy Payment).
1.1.0 RC | 2025/06 | With the addition of Docomo, au, and Merpay, added the following related description. Common Items for All Payment About API Request Submission Time Frames Docomo/au Common au Merpay Corrected the description of detailed result code to include both resultCode and vResultCode.
1.0.0 RC | 2024/08 | Supplementary information has been separated from the interface specification document into this document. The added items are listed below. Common Items for All Payment About Data Retention Period About Double order About Capture About Cancel Rakuten Pay About Payments where Rakuten Points have been Used