- introduction
  - Notice
  - Overview
    - Introduction
    - Payment Method
    - List of APIs
    - Payment Sequence
    - Payment Flow
    - Payment Life Cycle
- API Reference
  - About API
    - HTTP Request Details
    - About Authentication of Payment Request
    - About Idempotency
    - About the Item Freely Specified by the Merchant
    - About Various IDs Related to the Order
    - About Date and Time
    - About Verification When the Redirection is Received
    - About transaction Result
  - APIs
    - post Payment Request
    - post On-Demand Payment Request
    - get Redirect
    - post Payment Request Change
    - post Capture
    - post Cancel
    - post On-Demand Payment
    - post Contract Cancellation
    - post Webhook
    - post Get Transaction Result
  - Testing
    - PayPay simulation details
    - Rakuten Pay simulation details
    - Docomo simulation details
    - au simulation details
    - Merpay simulation details
    - Test scenario
- APPENDIX
  - Revision History

API docs by Redocly

# VeriTrans4G Unified API (1.1.2 RC)

Download OpenAPI specification:Download

# Notice

[Important] Change of Connection Domain
The current domain (old domain) will no longer be available after the end of July 2025.
Please switch to the new domain starting from August 2025.
* For merchants currently using the existing (old) domain, please migrate to the new domain within August.
* For details on the new and old domains, refer to "HTTP Request Details".

# Overview

## Introduction

VeriTrans4G Unified API offers a straightforward interface for processing online payments on e-commerce sites.
This guide is designed for developers who want to implement online payments using various APIs.
The following payment types are supported for online payments, and more will be added in the future.

1. PayPay
2. Rakuten Pay
3. Docomo (d Payment)
4. au (auPAY (au Easy Payment), auPAY (Online payment) Web method, auPAY (Online payment) Application method)
5. Merpay

## Payment Method

The VeriTrans4G Unified API provides two payment methods: Single Payment and On-Demand Payment.
The differences between these two methods are explained below.

Payment Method | Description
Single Payment | A method in which a payment request is executed for each purchase of goods.
On-Demand Payment | A method in which the merchant and consumer agree to continuous use through an On-Demand Payment request. Payments are then charged on a single-payment basis by means of On-Demand Payment as per the availability of goods and other items. Orders accepted through an On-Demand Payment request are referred to as "Original Orders".

## List of APIs

The following APIs are available in the VeriTrans4G Unified API.

API | Payment Method | Supported Payment Types
Name | Command Name | Request Destination | Single | On-Demand Payment Request | On-Demand Payment | PayPay *1 | Rakuten Pay | Docomo | au | Merpay
Payment Request | pay | Merchant⇒Unified API | 〇 | × | × | 〇 | 〇 | 〇 | 〇 | 〇
On-Demand Payment Request | subscribe | Merchant⇒Unified API | × | 〇 | × | 〇 | 〇 | 〇 | 〇 ※3 | 〇
Change Payment Request | updateOrder | Merchant⇒Unified API | 〇 | × | 〇 | × | 〇 | × | 〇 ※2 | ×
Capture | capture | Merchant⇒Unified API | 〇 | × | 〇 | 〇 | 〇 | 〇 | 〇 | 〇
Cancel | cancel | Merchant⇒Unified API | 〇 | × | 〇 | 〇 | 〇 | 〇 | 〇 | 〇
On-Demand Payment | charge | Merchant⇒Unified API | × | × | 〇 | 〇 | 〇 | 〇 | 〇 ※4 | 〇
Cancellation of Contract | terminate | Merchant⇒Unified API | × | 〇 | × | 〇 | × | 〇 | 〇 | 〇
Redirect | redirect | Unified API⇒(Consumer Browser⇒)Merchant | 〇 | 〇 | × | 〇 | 〇 | 〇 | 〇 | 〇
Webhook | push | Unified API⇒Merchant | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | 〇
Get Transaction Result | getTransactionResult | Merchant⇒Unified API | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | 〇

1. Only direct connection with PayPay is provided.
2. Available only for Single Payment.
3. Only auPAY (au Easy Payment) and auPAY (Online payment) web methods are provided.
4. auPAY (au Easy Payment) supports only Authorization with Capture.

"Optional Request Parameters" and "Response Parameters" may be added to each API without prior notice.
Additionally, please note that if no value is set for a response parameter, the parameter itself will not be returned,
Be careful when checking response parameters.

## Payment Sequence

Single Payment

1. The merchant site sends a Payment Request command to the VeriTrans4G Unified API server (hereinafter, referred to as FEP server), which returns a Redirect URL.
2. The merchant site then sends a Redirect instruction to the consumer's browser using the received Redirect URL.
3. During this redirect process, the FEP server, GW server, payment provider, and the consumer's browser perform authentication and payment processing.
4. Once the transaction is processed, the FEP server sends the transaction result to the merchant site via a Webhook command, and also instructs the consumer's browser to redirect back to the merchant site.
5. Upon receiving the redirect command, the merchant site sends a 'Get Transaction Result' command to the FEP server to retrieve the transaction result details and displays the payment request result in the consumer’s browser.
   (Note: The transaction results returned by the redirect command should be considered as overview information, and detailed information should be obtained either through the Webhook command or the 'Get Transaction Result' command.)
6. If the On-Demand Payment Request command is used with 'Payment Request with Capture' type (authCaptureType) set to payment request only, it is possible to send a Modify Payment Request to the FEP server to change the payment amount or other details of the transaction before completing the capture.
7. If the 'Payment Request with Capture' Type (authCaptureType) is set to 'Payment Request only' in the Payment Request command, a separate Capture command is sent to the FEP server to confirm the Capture.
8. To cancel a transaction that is in Authorization or Capture status, send a Cancel command to the FEP server.

On-Demand Payment
(On-Demand Payment Request)

1. The merchant site sends an On-Demand Payment Request command to the VeriTrans4G Unified API server (hereinafter referred to as the FEP server), which responds with a Redirect URL.
2. The merchant site then sends a Redirect instruction to the consumer's browser using the received Redirect URL.
3. During this redirect process, the FEP server, GW server, payment provider, and the consumer's browser perform authentication and payment processing.
4. Once the transaction is processed, the FEP server sends the transaction result to the merchant site via a Webhook command, and also instructs the consumer's browser to redirect back to the merchant site.
5. Upon receiving the redirect command, the merchant site sends a 'Get Transaction Result' command to the FEP server to retrieve the transaction result details and displays the payment request result in the consumer's browser.
   (Note: The transaction results returned by the redirect command should be considered as overview information, and detailed information should be obtained either through the Webhook command or the 'Get Transaction Result' command.)
6. To cancel a contract for an On-Demand order, send the contract cancellation command to the FEP server. This will prevent any subsequent On-Demand payments from being processed.
7. Depending on the Payment Type, when the On-Demand Payment contract is cancelled by the payment provider, the contract's deregistration will be notified to you by the provider.
   The FEP server will then send a Webhook command to the merchant site upon receiving the corresponding deregistration notification.

On-Demand Payment
(On-Demand Payment)

1. Agree to an On-Demand Payment request.
2. Orders accepted through an On-Demand Payment request are referred to as "Original Orders," and On-Demand payments are processed and billed.
3. If the On-Demand Payment Request command is used with 'Payment Request with Capture' type (authCaptureType) set to payment request only, it is possible to send a Modify Payment Request to the FEP server to change the payment amount or other details of the transaction before completing the capture.
4. If the 'Payment Request with Capture' Type (authCaptureType) is set to 'Payment Request only' in the On-Demand Payment Request command, a separate Capture command is sent to the FEP server to confirm the Capture.
5. To cancel a transaction that is in Authorization or Capture status, send a Cancel command to the FEP server.

## Payment Flow

Payment Request

On-Demand Payment Request

Change Payment Request

Capture

Cancel

On-Demand Payment

Cancellation of Contract

Get Transaction Result

## Payment Life Cycle

The lifecycle of Single Payment and On-Demand Payment provided by the VeriTrans4G Unified API is described below.
Additionally, it is possible to retry with the same paymentId not only in the case of a payment failure but also in the event of a charge failure.

Single Payment
Until the payment request is completed

Lifecycle from Authorization to Authorization with Capture
Single Payment
After the payment request is completed

Lifecycle after Authorization and Authorization with Capture
On-Demand Payment (Original Order)

On-Demand Payment (On-Demand Payment)

# About API

## HTTP Request Details

URL
Until the end of July 2025
Live environment : https://api.unified.veritrans.co.jp/fep/command
Sandbox environment : https://api.sandbox.unified.veritrans.co.jp/fep/command
August 2025 onward
Live environment : https://api.unified.veritrans.jp/fep/command
Sandbox environment : https://api.sandbox.unified.veritrans.jp/fep/command
* Please refer to the "Testing" sheet for details of each environment.

All communications with the FEP server should be made over HTTPS.
Port number
443
Protocol
SSL/TLS　　　　　TLS1.2 or higher
The connection must support TLS 1.2 or higher.
Request Header

Field Name | Settings | Format and Limitations | Description
Content-Type | Mandatory | As per the description in the right column | application/json
Authorization | Only one of them is required to be specified. | As per the description in the right column | Bearer {token} About {token}, refer to "About Authentication of Payment Request".
X-VT-Content-hmac | As per the description in the right column | h=HmacSHA512;s={merchant CCID};v={hmacString} About {merchant CCID} and {hmacString}, refer to "About Authentication of Payment Request".
X-VT-Idempotency-Key | Optional | Single byte alphanumeric characters and symbols, 100 bytes or less | Arbitrary values for Idempotency checks *For symbols, a hyphen (-) and an underscore (_) can be used. For details, refer to "About Idempotency".

    Content-Type: application/json;
    Authorization: Bearer 222fd022-dc1d-4736-eab4-c5d9c507a284
    X-VT-Content-hmac: h=HmacSHA512;s=MerchantCcId;v=915dd44f78777da61c26e683ae63cdf3aee72a212596ffc7fa4c0833dd224374
    X-VT-Idempotency-Key: 29eb1743-b37c-d7c4-badb-7bc4056d9a98

## About Authentication of Payment Request

The VeriTrans4G Unified API uses either Bearer authentication or HMAC authentication to authenticate each API request.
Merchants should choose the authentication method they wish to use and set the corresponding parameters in the request header.
If both authentication methods are set, Bearer authentication will be used.
For more information on each authentication method, refer to the section below.

### About Bearer Authentication

The {token} is obtained (generated) by MAP. Specify the token, within its expiration date, in the request header.

- You can check these settings by clicking the "Unified API" icon on the MAP page and selecting "Bearer Authentication Settings".
- Please note that the "Unified API" icon will not be displayed if you log in with a Merchant ID that does not have a Unified API contract.

### About HMAC Authentication

For {merchant CCID} in X-VTContent-hmac, please ensure that the merchant CCID is specified.
Concatenate the strings in the following order without delimiters, and set the generated "HmacSHA512" hash value in {hmacString}.
(Similarly, for Webhooks, please perform verification using the specified request header.)
1. Merchant CCID
2. Request parameter string (String after JSON to String conversion)
3. Merchant Authentication Key

    Merchant CCID＝sampleCcId

    Request parameter string＝{"order":{"payType": "paypay", "paymentId":
      "paymentId_1234567890", "amount": "10000"},"item": [{"id": "item001", "name":
      "testItem001"},{"id": "item002", "name": "testItem002"}],"merchant":{ "storeName":
      "store001"},"control":{"requestMode": "test,successUrl":
      "https://example.com/", "cancelUrl": "https://example.com/", "errorUrl":
      "https://example.com/", "pushUrl": "https://example.com/"}}

    Merchant Authentication Key＝sampleKey

    Concatenation string
    str＝sampleCcId{"order":{"payType": "paypay", "paymentId":
      "paymentId_1234567890", "amount": "10000"},"item": [{"id": "item001", "name":
      "testItem001"},{"id": "item002", "name": "testItem002"}],"merchant":{ "storeName":
      "store001"},"control":{"requestMode": "test,successUrl":
      "https://example.com/", "cancelUrl": "https://example.com/", "errorUrl":
      "https://example.com/", "pushUrl": "https://example.com/"}}sampleKey

    *Generate a hash value from the above concatenated string with HmacSHA512.
      However, please note that "sampleCcid" and "sampleKey" above should be generated after reading the actual values.

The Merchant CCID and Merchant Authentication Key can be found in the API Configuration Information.
The Merchant Authentication Key is confidential and must not be visible to consumers or other third parties.
When contacting us, please do not share it in plain text within the body of the email.

## About Idempotency

By setting the Idempotency-Key during requests, checks can be performed to ensure that identical requests (*1) have not been made previously.
If the request is determined to be the same as a past request, the result from the previous request is returned without actual processing.
This feature is intended to allow merchants to reacquire responses they failed to receive.
For example, if a merchant fails to receive a response to a Capture request,
they can execute the request again with the same parameters, including the Idempotency-Key.
If the Idempotency-Key is the same, the original response is sent.
If the initial request did not reach the FEP server, it is treated as a new request and processed accordingly.
The Idempotency-Key can be set freely as long as it follows the specified format, but using UUIDv4 is recommended.
Idempotency is determined by the following items in each API:
・(Header)X-VT-Idempotency-Key
・(Body)paymentId(fepOrderId can also be used)
*1: Precaution items
・Even if the Idempotency-Key matches a previous request, if the requested API or paymentId differs, it will be treated as a separate request.
・Even if the Idempotency-Key matches a previous request, the format of the request item will be checked. Therefore, do not change the request content in principle.
・The validity period for an Idempotency-Key is 24 hours. If a request is made after this period with the same value, it will be processed as a new request.

## About the Item Freely Specified by the Merchant

For the following items, the merchant can freely set the key information linked to the order.
Furthermore, since the settings are retained on a per-API request basis, past settings cannot be updated or deleted.

- merchantRequestKey1
- merchantRequestKey2
- metadata1
- metadata2

These items are not encrypted when saved on the FEP server.
Therefore, ensure that personal information or credit card details are not set in these fields.

## About Various IDs Related to the Order

### paymentId

It is an ID used to uniquely identify an order in the VeriTrans4G Unified API.
Merchants must assign a unique, randomly generated number to each payment request to ensure it does not overlap with any other paymentId. It cannot be duplicated across different payment types.
Until a transaction is successful, the same ID can be reused for additional requests.
For re-requests, refer to the "Payment Life Cycle".
However, please be aware that if you perform another transaction with the same paymentId before the original transaction result is confirmed, multiple payments might be completed using that same paymentId.
In such cases, a UA-000-002 response code will be returned to one of the transactions. If UA-000-002 occurs (e.g., in MAP), please verify the customer's payment status.
A paymentId used in the Sandbox environment cannot be reused in the Live environment.
The paymentId can include single-byte alphanumeric characters, as well as the hyphen (-) and underscore (_) symbols.

### fepOrderId

The VeriTrans4G Unified API assigns a unique ID (fepOrderId), which is sent to the payment server along with the paymentId specified during the payment request.
This corresponding ID is returned after the payment request via redirect or Webhook and can be used as an alternative to the paymentId for making API requests (other than the payment request) or inquiries.
The numbering system is as follows:
paymentId + _ + random string (26–35 bytes)
Example: If paymentId = id123456789, then fepOrderId = id123456789_01AHK4HS7GFKHGKE7SGFJKTHIH
*Please note: When searching for orders in MAP, the paymentId cannot be used. Only the fepOrderId is valid for conducting searches.

### originalPaymentId

The ID (paymentId) of the original order (the order associated with the On-Demand Payment Request) is linked to the payment at the time of an On-Demand Payment.
Specify the same ID that was set during the On-Demand Payment Request.

### originalFepOrderId

The ID (fepOrderId) of the original order (associated with the On-Demand Payment Request) is linked to the On-Demand Payment.
Specify the fepOrderId returned for the order at the time of the Payment Request for On-Demand Payment.

### fepReferenceId

ID newly assigned by the FEP server for each request.
It can also be used with the Get Transaction Result API.

## About Date and Time

The date and time used by the VeriTrans4G Unified API are set to "JST (Japan Standard Time) (GMT+9)" unless otherwise specified.

## About Verification When the Redirection is Received

To detect message tampering, ensure that the AuthInfo verification is performed without fail.
Additionally, since the sequence of parameter concatenation is not fixed, it must be handled dynamically by referring to the authParams.
Furthermore, even if the merchant's process confirms no issues with the verification result, it is essential to verify that the paymentId parameter matches the one set during the payment request.
While the vAuthInfo verification alone can detect partial message manipulation, it cannot identify cases where the entire redirect information from a past successful order is replaced for fraudulent purposes. In such scenarios, the fraudulent data may go undetected.

## About transaction Result

### Result Code

The result code (resultCode) included in the API response is as follows:
Please note that, depending on the error content, only the HTTP status code may be returned.

HTTP Status code | Result code (resultCode) | Description | Status (status) | Action code (actionCode)
200 | UA-000-001 | Success | success | success
200 | UA-000-002 | Success (Confirmation Required) | confirm_payment
200 | UA-U00-001 | Awaiting consumer's payment | user_paying
200 | UA-P00-001 | Provider processing in progress | provider_processing
400 | UA-REQ-001 | Invalid message | failure | confirm_request
400 | UA-REQ-002 | Fraudulent parameter | confirm_request
409 | UA-REQ-003 | Order duplication | confirm_request
401 | UA-REQ-004 | No execution permission | confirm_merchant_info
406 | UA-REQ-005 | In process | retry_request
400 | UA-REQ-006 | Request time limit exceeded (capture deadline, cancellation deadline, etc.) | alternate_payment
400 | UA-REQ-007 | API cannot be executed (internal status invalid) | confirm_payment_status
401 | UA-REQ-008 | Authentication error | confirm_token
404 | UA-REQ-900 | Invalid request content (no applicable merchant or order found) | confirm_request
502 | UA-PRV-001 | Provider error | retry_request
502 | UA-PRV-002 | API cannot be executed (external status is invalid) | confirm_payment_status
502 | UA-PRV-003 | API cannot be executed (merchant registration and contract issues) | confirm_merchant_info
502 | UA-PRV-004 | Provider error (incorrect amount) | confirm_request
503 | UA-PRV-999 | Under Maintenance | maintenance
502 | UA-CST-001 | Consumer-related error | confirm_consumer
502 | UA-CST-002 | Consumer cancellation | retry_payment
502 | UA-CST-003 | Consumer authentication error | retry_payment
429 | UA-LMT-001 | Exceeded number of concurrent connections | retry_request
403 | UA-LMT-002 | Incorrect request source IP address | confirm_merchant_info
500 | UA-PND-001 | Payment status unknown (pending) | confirm_pending_status
500 | UA-SYS-001 | System error | error | inquiry_support
500 | UA-SYS-002 | Application error | inquiry_support
500 | UA-SYS-003 | Internal communication error | retry_request
500 | UA-SYS-004 | External communication error | retry_request
404 | - | Page not found | - | -

The returned result codes may be added without prior notice.

### Status

The Status (status) in the API response is as follows:

Status (status) | Description
success | Success
failure | Order failure (Invalid request, consumer eligibility check, payment provider judgment, etc.)
error | System error (Due to issues with the Unified API or the payment provider's server, etc.)

### Action code

The action code set in the API response is a simplified representation of the merchant's recommended action when the transaction status is anything other than "success".
The action codes to be returned and the details of the merchant's action are as follows:

Action code (actionCode) | Merchant's action
--- | ---
inquiry_support | Contact Technical Support
maintenance | Please check the maintenance period and try again.
confirm_payment | There is a possibility of a double order or an invalid transaction status. Please verify the transaction status in MAP.
confirm_payment_status | Ensure that API calls are not made for transactions that do not match the transaction status.
confirm_request | Check the parameter values by referring to the error message.
confirm_merchant_info | Verify the merchant's registration status based on the error message.
alternate_payment | After verifying the transaction status, please resend the request. Alternatively, please make a payment using another payment method.
retry_request | Please wait for a while and then attempt the payment again. If the error persists, contact Technical Support.
retry_payment | Please retry the payment request.
confirm_consumer | This error may be caused by the consumer. Check the consumer's status.
confirm_token | Verify your authentication token.
user_paying | The payment is currently being processed. Please check the order status after some time.
provider_processing | Awaiting the processing by the payment provider. Please check the order status after some time.
confirm_pending_status | The payment status can be either 'Success' or 'Failure'. After a certain period, please check the order status. If there is no change, contact Technical Support.

### Message

The message in the API response is provided with the result code description in English. Please note that switching between languages is not supported.

# APIs

Input value limits may vary depending on the payment type. A value within the specified limits for the selected payment type should be entered.
If a value is set for an item that is not applicable to the specified payType, the value for that item will be ignored and not used.
However, please be note that violating the item's validation rules will result in an error.
Example: If a value is set for order.description with payType=rakuten during the payment request:

- When the set value does not violate validation:
  The value is ignored, no error occurs for the item, and the process continues normally.
- When the set value violates validation:
  A validation error related to the item is returned.

## Payment Request

PayPay Rakuten Pay Docomo au Merpay
Payment requests (authorization) are performed. Depending on the values set in the request message, it is also possible to perform a payment request with capture.
The "Payment Flow" section describes the process up to the completion of the payment request. The APIs used in such cases are described in [ ].

##### Request Body schema: application/json

Merchant⇒Unified API

required | object (order)
payType required | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "paypay" "rakuten" "docomo" "au" "merpay" PayPay Rakuten Pay Docomo au Merpay Specifies the payment type. `paypay`: PayPay `rakuten`: Rakuten Pay `docomo`: d Payment `au`: auPAY (au Easy Payment), auPAY (Online payment) Web method, auPAY (Online payment) Application method `merpay`: Merpay
paymentId required | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specifies a newly assigned ID. Only the symbols-(hyphen),_(underscore) can be used.
amount required | string <= 12 characters Single byte numbers, symbols PayPay Rakuten Pay Docomo au Merpay Specifies the payment request amount. *Please note that the limit amount is different for each payment type. *Please note that the payment provider may have upper limits for the payment amounts due to restrictions such as merchant contracts and consumer contracts. Hence, an error may occur even when the amount is within the input value limit for each payment. For au, refer to the 'Usage Limits' section under 'About auPAY (au Easy Payment)', in the supplementary information attached. *The minimum amount for Rakuten Pay is 100 yen. If payments less than 100 Yen are likely, please consult Rakuten Inc. in advance. However, even in such a case, amounts less than 2 Yen cannot be handled. * Input value limits for each payment method are as follows: PayPay:Numerical value 7 digits or less Rakuten Pay:Numerical value 7 digits or less Docomo:Numerical value 8 digits or less au:Numerical value 7 digits or less Merpay:The value between 1 and 1000000 can be specified
authCaptureType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "auth" "auth_with_capture" PayPay Rakuten Pay Docomo au Merpay Specifies the Payment Request with Capture type. `auth`: Payment Request Only (Default Value) `auth_with_capture`: Payment Request with Capture *When not specified, it will be auth.
description | string <= 255 characters PayPay The specified details are communicated to the payment provider and are displayed on the provider's interface. If specified for an unsupported payment type, it will be ignored. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type.
commodityType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "digital_content" "product_sales" "service" Docomo au Specify the item type. `digital_content`: Digital Content `product_sales`: Sale of Goods `service`: Service *If not specified, the value set during merchant registration will be used.
| object (transaction)
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| Array of objects (item)
Array
id | string <= 255 characters PayPay Rakuten Pay Docomo au Specifies the ID/control number of an item or service managed by the merchant. *Please note that the number of characters that can be set is different for each payment type. * Input value limits for each payment method are as follows: PayPay: Single byte alphanumeric characters and symbols (*) 255 bytes or less * For PayPay, only '`*`(asterisk), `-`(hyphen), `_`(underscore), `@`(at sign), `` (single byte space), `.`(period)' symbols can be used. Rakuten Pay: Single byte alphanumeric characters 64 bytes or less Docomo: Single byte alphanumeric characters 15 bytes or less au:Single byte alphanumeric characters 15 bytes or less
name | string <= 4000 characters PayPay Rakuten Pay Docomo au Specifies the item name. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. * For Rakuten Pay, this corresponds to the 'description' field of Rakuten. Please set the purchase product information as a fraud order countermeasure in the format specified by Rakuten. For details, refer to the regulations defined by Rakuten Payment Inc. * For Docomo and au, settings for device-dependent characters cannot be used. For details, refer to the attached supplementary information 'About Device-Dependent Characters'. * Input value limits for each payment method are as follows: PayPay: String 255 bytes or less Rakuten Pay: Double byte or single byte characters 300 characters or less Docomo: Double byte characters 20 characters or less au: Double byte characters 24 characters or less
categoryId | string <= 4 characters Single byte alphanumeric characters Merpay Specify the Item Category ID. * For Merpay, specifying this is required.For details, refer to the attached supplementary information 'Item Category ID List'.
| object (merchant)
storeId | string <= 255 characters Single byte alphanumeric characters, symbols PayPay au Specify the Store ID. Only the symbols -(hyphen), _(underscore) can be used. * au:auPAY (Online payment) can be specified when the application method is used. If not specified, the value set during merchant registration application will be used. * Input value limits for each payment method are as follows: PayPay:Single byte alphanumeric characters, symbols 255 characters or less au:Single byte numbers 8 characters or less
storeName | string <= 255 characters PayPay Specify the Store name. *If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type.
terminalId | string <= 255 characters Single byte alphanumeric characters, symbols PayPay au Specify the terminal management number. Only the symbols -(hyphen), _(underscore) can be used. * au:auPAY (Online payment) can be specified when the application method is used. If not specified, the value set during merchant registration application will be used. * Input value limits for each payment method are as follows: PayPay:Single byte alphanumeric characters, symbols 255 characters or less au:Single byte alphanumeric characters 128 bytes or less
| object (customer)
| object (buyer)
buyerInfoType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "use" "not_use" Merpay Specify the buyer information type. For details, refer to the attached supplementary information 'Request for Personal Information (Shipping Address Information & Buyer Information)'. `use`: Buyer information required `not_use`: Buyer information not required (default value)
userAgent | string <= 2048 characters PayPay Merpay Specify the user agent. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. * If not specified, the user agent obtained by the FEP server upon redirection from the consumer will be used. * For Merpay, this field is currently effective only on Chrome. Supported browsers may be changed or added depending on Merpay's specifications. For details, refer to attached supplementary information '[Smartphone Browser] Issues Caused by Browser Differences at the Start and Completion of Payment Processing'. * Input value limits for each payment method are as follows: PayPay:Single byte alphanumeric characters, symbols 256 characters or less Merpay:Single byte alphanumeric characters and symbols 1000 characters or less
| object (shipping)
deliveryAddressType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "use" "not_use" Merpay Specify the shipping address information type. For details, refer to the attached supplementary information 'Request for Personal Information (Shipping Address Information & Buyer Information)'. `use`: Shipping address information required `not_use`: Shipping address information not required (default value)
required | object (control)
requestMode | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "live" "sandbox" PayPay Rakuten Pay Docomo au Merpay Specifies the request mode. When not specified, it will be a live mode request. `live`: Live mode request (default value) `sandbox`: sandbox request * Make sure to set this according to the environment you are connecting to. If 'sandbox' is set for the live environment or 'live' is set for the sandbox environment, a check error will occur.
successUrl required | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the URL to redirect back to the merchant website page after completing the payment. * http cannot be specified for live mode requests (only https is acceptable)
cancelUrl required | string <= 1024 characters URL format PayPay Docomo au Merpay Specifies the URL to redirect back to the merchant website page when payment is cancelled. * http cannot be specified for live mode requests (only https is acceptable)
errorUrl required | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the URL to redirect back to the merchant website page when an error occurs during the payment. * http cannot be specified for live mode requests (only https is acceptable) * For Rakuten Pay, there is a possibility that the transaction may go into pending status (resultCode: UA-PND-001). At that time, the target order may be successful, so please be careful about the display contents and notification to consumers.
pushUrl | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.
| object (paymentInstrument)
| object (au) au
paymentAuthenticationType | string <= 20 characters Single byte alphanumeric characters, symbols Specifies the authentication method to determine the use of app-payment. When using the auPAY (Online payment) Application method, specify the application authentication method. `id_method`: ID authentication method (default value) `app_method`: application authentication method
loginType | string <= 20 characters Single byte alphanumeric characters, symbols Specify the login method. If a merchant uses its own ID for member management and authentication, please use "ID linkage". Please use "auID login" if you wish to log in to merchant services using your auID without performing your own member management and authentication. `au_id`: auID login `linked_id`: ID linkage (default value) * Cannot be specified for the application authentication method. If specified, it is treated as unset.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/pay

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/pay

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/pay

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/pay

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "payType": "paypay",
  - "paymentId": "paymentId_1234567890",
  - "amount": "10000",
  - "authCaptureType": "auth",
  - "description": "testOrder",
  - "commodityType": "product_sales"
  },
- "transaction":
  {
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "item":
  [
  - {
    - "id": "item001",
    - "name": "testItem001",
    - "categoryId": "1112"
    }
  ],
- "merchant":
  {
  - "storeId": "storeId001",
  - "storeName": "storeName001",
  - "terminalId": "terminalId001"
  },
- "customer":
  {
  - "buyer":
    {
    - "buyerInfoType": "not_use",
    - "userAgent": "example"
    },
  - "shipping":
    {
    - "deliveryAddressType": "not_use"
    }
  },
- "control":
  {
  - "requestMode": "sandbox",
  - "successUrl": "https://example.com/",
  - "cancelUrl": "https://example.com/",
  - "errorUrl": "https://example.com/",
  - "pushUrl": "https://example.com/"
  },
- "paymentInstrument":
  {
  - "au":
    {
    - "paymentAuthenticationType": "id_method",
    - "loginType": "linked_id"
    }
  }

}`

### Response samples

- 200
- 400
- 500

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "redirectUrl": "https://example.com/"
  }

}`

## On-Demand Payment Request

An On-Demand Payment Request is performed.
The "Payment Flow" section describes the process up to the completion of the On-Demand Payment request. The APIs used in such cases are described in [ ].

##### Request Body schema: application/json

Merchant⇒Unified API

required | object (order)
payType required | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "paypay" "rakuten" "docomo" "au" "merpay" PayPay Rakuten Pay Docomo au Merpay Specifies the payment type. `paypay`: PayPay `rakuten`: Rakuten Pay `docomo`: d Payment `au`: auPAY (au Easy Payment), auPAY (Online payment) Web method `merpay`: Merpay
paymentId required | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specifies a newly assigned ID. Only the symbols -(hyphen), _(underscore) can be used.
orderName | string <= 60 characters Merpay Specify the order name. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. * Input value limits for each payment method are as follows: Merpay: Double byte or single byte characters 20 characters or less *For Merpay, specifying this is required
description | string <= 255 characters PayPay Merpay The specified details are communicated to the payment provider and are displayed on the provider's interface. If specified for an unsupported payment type, it will be ignored. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. * Input value limits for each payment method are as follows: PayPay: String 255 bytes or less *Only for direct connection Merpay: Double byte or single byte characters 120 characters or less *For Merpay, specifying this is required
commodityType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "digital_content" "product_sales" "service" Docomo au Specify the item type. `digital_content`: Digital content `product_sales`: Sale of goods `service`: Service * If not specified, the value set during merchant registration will be used.
| object (transaction)
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| Array of objects (item)
Array
id | string <= 255 characters PayPay Rakuten Pay Docomo au Specifies the ID/control number of an item or service managed by the merchant. *Please note that the number of characters that can be set is different for each payment type. * Input value limits for each payment method are as follows: PayPay: Single byte alphanumeric characters and symbols (*) 255 bytes or less * For PayPay, only '`*`(asterisk), `-`(hyphen), `_`(underscore), `@`(at sign), `` (single byte space), `.`(period)' symbols can be used. Rakuten Pay: Single byte alphanumeric characters 64 bytes or less Docomo: Single byte alphanumeric characters 15 bytes or less au: Single byte alphanumeric characters 15 bytes or less
name | string <= 4000 characters PayPay Rakuten Pay Docomo au Specifies the item name. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. * For Rakuten Pay, this corresponds to the 'name' field of Rakuten. Please be aware that values cannot be modified later, even if the service/product name is changed. * For Docomo and au, settings for device-dependent characters cannot be used.For details, refer to the attached supplementary information 'About Device-Dependent Characters'. * For au, format restrictions apply. For details, refer to the attached supplementary information 'Format Specifications for the au On-Demand Payment Request Field: name'. * Input value limits for each payment method are as follows: PayPay: String 255 bytes or less Rakuten Pay: Double byte or single byte characters 200 characters or less Docomo: Double byte characters 20 characters or less au: Double byte characters 24 characters or less
categoryId | string <= 4 characters Single byte alphanumeric characters, symbols Merpay Specify the Item Category ID. * For Merpay, specifying this is required.For details, refer to the attached supplementary information 'Item Category ID List'.
| object (merchant)
storeId | string <= 255 characters Single byte alphanumeric characters, symbols PayPay Specify the Store ID. Only the symbols -(hyphen), _(underscore) can be used.
storeName | string <= 255 characters PayPay Specify the Store name. *If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type.
terminalId | string <= 255 characters Single byte alphanumeric characters, symbols PayPay Specify the terminal management number. Only the symbols -(hyphen), _(underscore) can be used.
| object (customer)
| object (buyer)
buyerInfoType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "use" "not_use" Merpay Specify the buyer information type. For details, refer to the attached supplementary information 'Request for Personal Information (Shipping Address Information & Buyer Information)'. `use`: Buyer information required `not_use`: Buyer information not required (default value)
userAgent | string <= 2048 characters PayPay Merpay Specify the user agent. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. * If not specified, the user agent obtained by the FEP server upon redirection from the consumer will be used. * For Merpay, this field is currently effective only on Chrome.Supported browsers may be changed or added depending on Merpay's specifications.For details, refer to attached supplementary information '[Smartphone Browser] Issues Caused by Browser Differences at the Start and Completion of Payment Processing'. * Input value limits for each payment method are as follows: PayPay: Single byte alphanumeric characters and symbols 256 characters or less *Only for direct connection Merpay: Single byte alphanumeric characters and symbols 1000 characters or less
| object (shipping)
deliveryAddressType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "use" "not_use" Merpay Specify the shipping address information type. For details, refer to the attached supplementary information 'Request for Personal Information (Shipping Address Information & Buyer Information)'. `use`: Shipping address information required `not_use`: Shipping address information not required (default value)
required | object (control)
requestMode | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "live" "sandbox" PayPay Rakuten Pay Docomo au Merpay Specifies the request mode. When not specified, it will be a live mode request. `live`: Live mode request (default value) `sandbox`: sandbox request * Make sure to set this according to the environment you are connecting to. If 'sandbox' is set for the live environment or 'live' is set for the sandbox environment, a check error will occur.
successUrl required | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the URL to redirect back to the merchant website page after completing the payment. * http cannot be specified for live mode requests (only https is acceptable)
cancelUrl required | string <= 1024 characters URL format PayPay Docomo au Merpay Specifies the URL to redirect back to the merchant website page when payment is cancelled. * http cannot be specified for live mode requests (only https is acceptable)
errorUrl required | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the URL to redirect back to the merchant website page when an error occurs during the payment. * http cannot be specified for live mode requests (only https is acceptable) * For Rakuten Pay, there is a possibility that the transaction may go into pending status (resultCode: UA-PND-001). At that time, the target order may be successful, so please be careful about the display contents and notification to consumers.
pushUrl | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.
deregistrationPushUrl | string <= 1024 characters URL format PayPay Docomo au Merpay Specify the URL to which the Webhook deregistration notification will be sent. If not set, it will be sent to pushURL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.
| object (paymentInstrument)
| object (au) au
loginType | string <= 20 characters Single byte alphanumeric characters, symbols Specify the login method. If a merchant uses its own ID for member management and authentication, please use "ID linkage". Please use "auID login" if you wish to log in to merchant services using your auID without performing your own member management and authentication. `au_id`: auID login `linked_id`: ID linkage (default value)

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/subscribe

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/subscribe

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/subscribe

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/subscribe

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "payType": "paypay",
  - "paymentId": "paymentId_1234567890",
  - "orderName": "testOrderName",
  - "description": "testOrder",
  - "commodityType": "product_sales"
  },
- "transaction":
  {
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "item":
  [
  - {
    - "id": "item001",
    - "name": "testItem001",
    - "categoryId": "1714"
    }
  ],
- "merchant":
  {
  - "storeId": "storeId001",
  - "storeName": "storeName001",
  - "terminalId": "terminalId001"
  },
- "customer":
  {
  - "buyer":
    {
    - "buyerInfoType": "not_use",
    - "userAgent": "example"
    },
  - "shipping":
    {
    - "deliveryAddressType": "not_use"
    }
  },
- "control":
  {
  - "requestMode": "sandbox",
  - "successUrl": "https://example.com/",
  - "cancelUrl": "https://example.com/",
  - "errorUrl": "https://example.com/",
  - "pushUrl": "https://example.com/",
  - "deregistrationPushUrl": "https://example.com/"
  },
- "paymentInstrument":
  {
  - "au":
    {
    - "loginType": "linked_id"
    }
  }

}`

### Response samples

- 200
- 400
- 500

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "redirectUrl": "https://example.com/"
  }

}`

## Redirect

PayPay Rakuten Pay Docomo au Merpay

It will be a Query Parameter while redirecting from the consumer browser to the merchant completion page.
Merchants cannot directly request this API.
Redirect will only link the order result and the information to identify the order.
Detailed information can be found in the webhook upon success. It can also be obtained via the Get Transaction Result API.
For details on timing, refer to the "Payment Flow" under the Payment Request tab or On-Demand Payment Request tab.
The same request might be sent multiple times due to consumer operations or browser-specific behaviors.
Ensure your implementation can handle duplicate requests, even if a request has already been processed.
In addition, when receiving a redirect, verify each message to detect potential tampering.
For details, refer to the section titled "About Verification When the Redirect is Received".

Please ensure that all communication with the merchant uses HTTPS.
Unified API⇒（consumer browser⇒）Merchant

##### query Parameters

status | string <= 10 characters Single byte alphanumeric characters Example: status=success PayPay Rakuten Pay Docomo au Merpay Status of Order Result. For details, refer to Status of "About Transaction Result".
actionCode | string <= 64 characters Single byte alphanumeric characters, symbols Example: actionCode=success PayPay Rakuten Pay Docomo au Merpay Action code(s) that guide the merchants' actions. The symbols used are the hyphen (-) and the underscore (_).
resultCode | string <= 10 characters Single byte alphanumeric characters, symbols Example: resultCode=UA-000-001 PayPay Rakuten Pay Docomo au Merpay A result code indicating the specific reason for the order result. The symbols used are the hyphen (-) and the underscore (_).
command | string <= 20 characters Single byte alphanumeric characters, symbols Example: command=pay PayPay Rakuten Pay Docomo au Merpay Redirect induced command. The symbols used are the hyphen (-) and the underscore (_).
paymentId | string <= 64 characters Single byte alphanumeric characters, symbols Example: paymentId=paymentId_1234567890 PayPay Rakuten Pay Docomo au Merpay paymentId linked to the target order.
fepOrderId | string <= 100 characters Single byte alphanumeric characters, symbols Example: fepOrderId=paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH PayPay Rakuten Pay Docomo au Merpay fepOrderId linked to the target order. The symbols used are the hyphen (-) and the underscore (_).
fepReferenceId | string <= 100 characters Single byte alphanumeric characters, symbols Example: fepReferenceId=X01AHK4HS7GFKHGKE7SGFJKTHIH PayPay Rakuten Pay Docomo au Merpay fepReferenceId linked to the target order. The symbols used are the hyphen (-) and the underscore (_).
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols Example: merchantRequestKey1=freeKey1 PayPay Rakuten Pay Docomo au Merpay Contents set at the time of payment request. *If not set at the time of request, it will not be returned.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols Example: merchantRequestKey2=freeKey2 PayPay Rakuten Pay Docomo au Merpay Contents set at the time of payment request. *If not set at the time of request, it will not be returned.
vAuthInfo | string <= 4000 characters PayPay Rakuten Pay Docomo au Merpay Hash value calculated by concatenating the following strings in the given order without delimiters and using "SHA512". 1.Merchant CCID 2.Concatenated string with parameter values (concatenate as per the sequence indicated by authParams) 3.Merchant Authentication Key While concatenating parameter values, only parameter values are concatenated without including the parameter name and delimiter. For character encoding when converting a concatenated string into binary, UTF-8 is used.
authParams | string <= 4000 characters PayPay Rakuten Pay Docomo au Merpay This value indicates the sequence of the concatenation of parameters of the string that is used to calculate the hash value of vAuthInfo. A comma-delimited string of the parameter name is Base64 encoded. On decoding, the strings are reinstated. Example: `status,actionCode,resultCode,command,paymentId,fepOrderId,fepReferenceId,fepReferenceId,paymentId,fepOrderId,actionCode,resultCode,command,status` (It is necessary to process dynamically whenever a request is received, as the sequence is not fixed.)

### Responses

These are the successUrl, cancelUrl, and errorUrl specified in the "pay" and "subscribe".

https://yourdomain/redirect

## Payment Request Change

Rakuten Pay au
This allows you to change the payment amount or extend the authorization for a successful payment request or On-Demand Payment order.
Payment Request change process cannot be carried out on orders for which 'Authorize with Capture' was specified during the payment request or on-demand payment request, or on orders that have already been captured after the payment request.
* For au, this applies only to successful payment request (Single Payment) orders. Please note that On-Demand Payment orders are not eligible.

##### Request Body schema: application/json

Merchant⇒Unified API

required | paymentId specification (object) or fepOrderId specification (object) (order)
One of
paymentId required | string <= 64 characters Single byte alphanumeric characters, symbols Rakuten Pay au Specify the paymentId that was set during the payment request or On-Demand Payment. *Cannot be specified at the same time as fepOrderId.
amount | string <= 12 characters Single byte numbers, symbols Rakuten Pay au Specify the payment amount. *Please note that the limit amount is different for each payment type. *Please note that the payment provider may have upper limits for the payment amounts due to restrictions such as merchant contracts and consumer contracts. Hence, an error may occur even when the amount is within the input value limit for each payment. *The minimum amount for Rakuten Pay is 100 yen.If payments less than 100 Yen are likely, please consult Rakuten Inc. in advance.However, even in such a case, amounts less than 2 Yen cannot be handled. * To change the amount when using auPAY (au Easy Payment), an application to KDDI is required. * Input value limits for each payment method are as follows: Rakuten Pay: Numerical value 7 digits or less au: Numerical value 7 digits or less
authExtensionType | string <= 20 characters Single byte alphanumeric characters, symbols Rakuten Pay Specify the authorization extension type. `extend`: Execute `not_extend`: Do not execute
| object (transaction)
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols Rakuten Pay au Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols Rakuten Pay au Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters Rakuten Pay au This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters Rakuten Pay au This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| object (control)
pushUrl | string <= 1024 characters URL format Rakuten Pay au Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/updateOrder

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/updateOrder

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/updateOrder

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/updateOrder

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "amount": "10000",
  - "authExtensionType": "not_extend"
  },
- "transaction":
  {
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "pushUrl": "https://example.com/"
  }

}`

### Response samples

- 200
- 400
- 500
- 502
- 503

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "amount": "100",
  - "usedPoint": "0",
  - "cancelExpirationDatetime": "20230526123456",
  - "captureExpirationDatetime": "20230526123456",
  - "updateExpirationDatetime": "20230526123456",
  - "extendAuthExpirationDatetime": "20230526123456"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "transactionDatetime": "20230525123456",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "provider":
  {
  - "payment":
    {
    - "providerOrderId": "XXX00000000001",
    - "gatewayOrderId": "00000000000000000001"
    }
  }

}`

## Capture

PayPay Rakuten Pay Docomo au Merpay
Capture settlement is carried out for orders where a payment request is made.
This can only be done once and must be within the amount specified in the payment request.

##### Request Body schema: application/json

Merchant⇒Unified API

required | paymentId specification (object) or fepOrderId specification (object) (order)
One of
paymentId required | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specify the paymentId that was set during the payment request or On-Demand Payment. *Cannot be specified at the same time as fepOrderId.
amount | string <= 12 characters Single byte numbers, symbols PayPay Rakuten Pay Merpay Specifies the Capture amount. Amount exceeding the payment request amount cannot be specified. *If not specified, the full amount is captured. * Input value limits for each payment method are as follows: PayPay:Numerical value 7 digits or less Rakuten Pay:Numerical value 7 digits or less Merpay:Numerical value 7 digits or less
description | string <= 255 characters PayPay Specifies the order description that appears on the user's details. The description will be displayed on the user's details only when a partial capture that is less than the payment request amount is carried out. In case of a full amount capture, the description will not be displayed even if it is specified. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type.
| object (transaction)
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| object (control)
pushUrl | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/capture

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/capture

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/capture

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/capture

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "amount": "10000",
  - "description": "testItem"
  },
- "transaction":
  {
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "pushUrl": "https://example.com/"
  }

}`

### Response samples

- 200
- 400
- 500
- 502
- 503

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success",
  - "vResultCode": "1001000000000000"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "amount": "10000",
  - "usedPoint": "100"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "transactionDatetime": "20230525123456",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "provider":
  {
  - "payment":
    {
    - "providerOrderId": "XXX00000000001",
    - "gatewayOrderId": "00000000000000000001"
    }
  }

}`

## Cancel

PayPay Rakuten Pay Docomo au Merpay
Cancels the transaction.
Partial refunds can be executed for orders after capture, specifying an amount less than the payment amount (balance).
Partial refunds can be performed repeatedly until the payment amount (remaining balance) is fully refunded;
however, this may not be possible depending on the payment type or transaction status.
For more details, please refer to the "About Partial Refund" section in the supplementary information attached.

##### Request Body schema: application/json

Merchant⇒Unified API

required | paymentId specification (object) or fepOrderId specification (object) (order)
One of
paymentId required | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specify the paymentId that was set during the payment request or On-Demand Payment. *Cannot be specified at the same time as fepOrderId.
amount | string <= 12 characters Single byte numeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specifies the amount to be cancelled. Amount exceeding the current payment amount (balance) cannot be specified. *If not specified, the full amount is cancelled. Only the full amount can be specified for orders where Capture has not yet been made (Authorization only status). *To make a partial refund with auPAY (au Easy Payment) or auPAY (Online payment), an application to KDDI is required. *d Payment can be specified only for Single Payment. * Input value limits for each payment method are as follows: PayPay:Numerical value 7 digits or less Rakuten Pay:Numerical value 7 digits or less Docomo:Numerical value 8 digits or less au:Numerical value 7 digits or less Merpay:Numerical value 7 digits or less
| object (transaction)
reason | string <= 255 characters PayPay Specifies the order description that appears on the user's details. Specifies the reason for cancellation. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type.
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| object (control)
pushUrl | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.
| object (protocol)
forceMode | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "none" "refund" PayPay Rakuten Pay Docomo au Merpay This item allows refunds to be executed regardless of the transaction status in the FEP server. Used to forcibly issue a refund after a Capture or partial refund for a transaction created with the Unified API without going through the Unified API. `none`: Non-forced (default value) `refund`: Refund *When not specified, it will be none. *Do not use this item under normal circumstances as it is intended for recovery purposes. *If “refund” is specified, the transaction will no longer be managed within the Unified API.Therefore, please do not specify this under normal circumstances.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/cancel

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/cancel

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/cancel

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/cancel

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "amount": "10000"
  },
- "transaction":
  {
  - "reason": "testCancel",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "pushUrl": "https://example.com/",
  - "protocol":
    {
    - "forceMode": "none"
    }
  }

}`

### Response samples

- 200
- 400
- 500
- 502
- 503

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success",
  - "vResultCode": "1001000000000000"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "amount": "10000",
  - "usedPoint": "100"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "transactionDatetime": "20230525123456",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "provider":
  {
  - "payment":
    {
    - "inquiryCode": "inquiryCode12345",
    - "providerOrderId": "XXX00000000001",
    - "gatewayOrderId": "00000000000000000001"
    }
  }

}`

## On-Demand Payment

PayPay Rakuten Pay Docomo au Merpay
Performs On-Demand Payment by considering the order for which user consent of an On-Demand is obtained, as the original order.

##### Request Body schema: application/json

Merchant⇒Unified API

required | originalPaymentId specification (object) or originalFepOrderId specification (object) (order)
One of
paymentId required | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specifies a newly assigned ID. Only the symbols -(hyphen), _(underscore) can be used.
originalPaymentId required | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Specifies the paymentId specified at the time of the On-Demand Payment Request. *Cannot be specified at the same time as originalFepOrderId.
authCaptureType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "auth" "auth_with_capture" PayPay Rakuten Pay Docomo au Merpay Specifies the Payment Request with Capture type. `auth`: Payment Request Only (Default Value) `auth_with_capture`: Payment Request with Capture *When not specified, it will be auth. *For PayPay, specifying auth_with_capture is required. *In the case of au, there are restrictions depending on the merchant's contract status (master registration). auPAY (au Easy Payment): Only Authorization with Capture can be specified auPAY (Online payment) Web method: Both Authorization only or Authorization with Capture can be specified
amount required | string <= 12 characters Single byte numbers, symbols PayPay Rakuten Pay Docomo au Merpay Specifies the payment amount. *Please note that the limit amount is different for each payment type. *Please note that, the upper limit of payment amount exists on the payment provider side due to restrictions in the merchant contract or consumer contract, so errors may occur even when the amount is within the allowed input limits for each payment. *The minimum amount for Rakuten Pay is 100 yen.If payments less than 100 Yen are likely, please consult Rakuten Inc. in advance.However, even in such a case, amounts less than 2 Yen cannot be handled. * Input value limits for each payment method are as follows: PayPay:Numerical value 7 digits or less Rakuten Pay:Numerical value 7 digits or less Docomo:Numerical value 8 digits or less au:Numerical value 7 digits or less Merpay:1 ~ 1000000
description | string <= 255 characters PayPay Specifies the order description that will appear on the consumer's payment page and details page. *Please note that the number of characters that can be set is different for each payment type.If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. *If not specified, the value entered at the time of payment request will be used. If it is not specified at the time of the payment request, it will not be set.
| object (transaction)
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| Array of objects (item)
Array
id | string <= 255 characters PayPay Rakuten Pay Specifies the id/control number of an item or service managed by the merchant. *If not specified, the value entered at the time of payment request will be used. *Please note that the number of characters that can be set is different for each payment type. * Input value limits for each payment method are as follows: PayPay: Single byte alphanumeric characters and symbols (*) 255 bytes or less * For PayPay, only '`*`(asterisk), `-`(hyphen), `_`(underscore), `@`(at sign), `` (single byte space), `.`(period)' symbols can be used. Rakuten Pay: Single byte alphanumeric characters 64 bytes or less
name | string <= 900 characters PayPay Rakuten Pay Specifies item name. *If not specified, the value entered at the time of payment request will be used. *Please note that the number of characters that can be set is different for each payment type. If the specified value exceeds the character limit, the excess characters will be truncated from the end to fit within the limit for each payment type. *In case of Rakuten Pay, it will be displayed on the Rakuten's Merchant Administration Portal. Corresponding to Rakuten's 'description' field, set the purchase product information implemented as a fraud order countermeasure in the format specified by Rakuten. For details, refer to the regulations stipulated by Rakuten Payments, Inc. Number of characters that can be set for each payment provider PayPay： String 255 bytes or less Rakuten Pay: Double byte, Single byte 300 characters or less
categoryId | string <= 4 characters Single byte alphanumeric characters Merpay Specify the Item category ID. For details, refer to the attached supplementary information 'Item Category ID'. *If not specified, the value entered at the time of payment request will be used.
| object (merchant)
storeId | string <= 255 characters Single byte alphanumeric characters, symbols PayPay Specify the Store ID. Only the symbols -(hyphen), _(underscore) can be used. *If not specified, the value entered during the On-Demand Payment Request Process will be used.
terminalId | string <= 255 characters Single byte alphanumeric characters, symbols PayPay Specify the terminal management number. Only the symbols -(hyphen), _(underscore) can be used. *If not specified, the value entered during the On-Demand Payment Request Process will be used.
| object (control)
pushUrl | string <= 1024 characters URL format PayPay Rakuten Pay Docomo au Merpay Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.
| object (protocol)
recoveryType | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "recovery" "not_recovery" PayPay Specifies whether to send a Payment Request to the consumer app if the payment process fails due to the consumer's insufficient balance. `recovery`:Payment request is sent `not_recovery`:The payment request is not sent and the capture process fails (default value)
recoveryExpiredDatetime | string <date> <= 14 characters Single byte numbers <yyyyMMddHHmmss> PayPay Specifies the payment expiration date when the payment process fails due to the consumer's insufficient balance, and the Payment Request is sent to the consumer app. It can be specified in the range of 10 minutes to 48 hours after the request date and time. This parameter can be specified when recoveryType=recovery. If not set with recoveryType=recovery, set the time 6 hours after the request date and time.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/charge

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/charge

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/charge

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/charge

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "originalPaymentId": "orgPaymentId_1234567890",
  - "authCaptureType": "auth_with_capture",
  - "amount": "10000",
  - "description": "testOrder"
  },
- "transaction":
  {
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "item":
  [
  - {
    - "id": "item001",
    - "name": "testItem001",
    - "categoryId": "1014"
    }
  ],
- "merchant":
  {
  - "storeId": "storeId001",
  - "terminalId": "terminalId001"
  },
- "control":
  {
  - "pushUrl": "https://example.com/",
  - "protocol":
    {
    - "recoveryType": "recover",
    - "recoveryExpiredDatetime": "20230601125959"
    }
  }

}`

### Response samples

- 200
- 400
- 500
- 502
- 503

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success",
  - "vResultCode": "1001000000000000"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "originalPaymentId": "orgPaymentId_1234567890",
  - "originalFepOrderId": "orgPaymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "amount": "10000",
  - "usedPoint": "100",
  - "cancelExpirationDatetime": "20230526123456",
  - "captureExpirationDatetime": "20230526123456",
  - "updateExpirationDatetime": "20230526123456",
  - "extendAuthExpirationDatetime": "20230526123456"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "transactionDatetime": "20230526123456",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "provider":
  {
  - "payment":
    {
    - "providerOrderId": "XXX00000000001",
    - "gatewayOrderId": "00000000000000000001",
    - "inquiryCode": "inquiryCode12345"
    }
  },
- "customer":
  {
  - "buyer":
    {
    - "customerId": "b613865a-6f72-af74-772d-02279b929876"
    }
  }

}`

## Contract Cancellation

PayPay Docomo au Merpay
Requests contract cancellation of On-Demand Payment. Only the forced contract cancellations can be implemented by merchants (between two parties).

##### Request Body schema: application/json

Merchant⇒Unified API

| paymentId specification (object) or fepOrderId specification (object) (Order)
One of
paymentId | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Docomo au Merpay Specifies the paymentId specified at the time of the On-Demand Payment Request. *Cannot be specified at the same time as fepOrderId.
| object (transaction)
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Docomo au Merpay Please freely specify the Key information associated with the order at the merchant. Only the symbols -(hyphen), _(underscore) can be used.
metadata1 | string <= 2000 characters PayPay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
metadata2 | string <= 2000 characters PayPay Docomo au Merpay This item can be freely specified by the merchant. *This item cannot be checked with reduction data or MAP.
| object (control)
pushUrl | string <= 1024 characters URL format PayPay Docomo au Merpay Specifies the Webhook push URL. *http cannot be specified (only https is acceptable). Also, private IP addresses cannot be specified. Only the port number '443' is permitted.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/terminate

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/terminate

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/terminate

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/terminate

### Request samples

- Payload

Content type
application/json
`
{

- "order":
  {
  - "paymentId": "paymentId_1234567890"
  },
- "transaction":
  {
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "pushUrl": "https://example.com/"
  }

}`

### Response samples

- 200
- 400
- 500
- 502
- 503

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success",
  - "vResultCode": "1001000000000000"
  },
- "order":
  {
  - "paymentId": "paymentId_1234567890",
  - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "transactionDatetime": "20230526123456",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "provider":
  {
  - "payment":
    {
    - "providerOrderId": "XXX00000000001"
    }
  }

}`

## Webhook

PayPay Rakuten Pay Docomo au Merpay
The FEP server notifies the merchant of the payment result.
For request headers, it sets the same items as other APIs in VeriTrans4G Unified API.
When the merchant receives the Webhook, please verify {hmacString}.
For Webhook (push) notifications to merchants, private IP addresses cannot be specified, and an SSL certificate check will be performed. (Self-signed certificates will result in an error).
Only the port number "443" is permitted.
Please ensure that all communication with the merchant uses HTTPS.

### Request Header

Field Name | Settings | Format and Limitations | Description
Content-Type | Mandatory | As per the description in the right column | application/json
X-VT-webhook-id | Mandatory | Single byte alphanumeric characters and symbols | Identification ID of the notification newly assigned by VeriTrans4G Unified API. The symbols used are the hyphen (-) and the underscore (_).
X-VT-Content-hmac | Mandatory | As per the description in the right column | h=HmacSHA512;s={merchant CCID};v={hmacString} For details about {merchant CCID} and {hmacString}, refer to "About Authentication of Payment Request".

    Content-Type: application/json
    X-VT-webhook-id: 01HG79DYJS6MJBN8BRS0HAQ38X
    X-VT-Content-hmac: h=HmacSHA512;s=MerchantCcId;v=915dd44f78777da61c26e683ae63cdf3aee72a212596ffc7fa4c0833dd224374

### About Responses

If the merchant successfully receives the notification from the FEP server, it must return an HTTP 200 status code.
If any status code other than 200 is returned, it will be considered a receiving failure, and the notification will be retried for a certain period.
Additionally, even if the merchant successfully returns a 200 response, the FEP server may retry the notification if it fails to receive the response for any reason.
Please be aware that push notifications may be sent again for orders that have already received a 200 response from the merchant.
Therefore, when receiving a push notification, check the X-VT-webhook-id header item. If it matches data you have already received,
please skip processing and respond with a 200 status.

### Notification Conditions

A notification is sent when the status of an order, for which a pushUrl was specified at the time of request, meets the following conditions.
Please ensure that pushUrl is not specified for APIs that do not require notifications.
Furthermore, about notification condition of payment request, due to reasons such as consumer leaving in the middle of the process, the status can be determined only for successful orders. Hence, the notification can be sent only in cases of successful orders.

API | command※1 | PayPay | Rakuten Pay | Docomo | au | Merpay
Payment Request *2 | pay | Order Successful | Order Successful | Order Successful | Order Successful | Order Successful
Change Payment Request | updateOrder | - | All Status | - | All Status | -
Capture | capture | All Status | All Status | All Status | All Status | All Status
Cancel | cancel | All Status | All Status | All Status | All Status | All Status
On-Demand Payment | charge | All Status *3 | All Status | All Status | All Status | All Status
Cancellation of Contract | terminate | All Status | - | All Status | All Status | All Status
Deregistration Notification *4 | deregistraction | At the time of notification from the payment provider | - | At the time of notification from the payment provider | At the time of notification from the payment provider | At the time of notification from the payment provider

※１ The command Parameter of Transaction Block in Notification Contents
※２ The payment request is executed only after the consumer completes both the payment and the payment request with the payment provider.
※３ If a notification is received with resultCode=UA-U00-001, and the order is subsequently finalized through consumer action, an additional Webhook will be sent with resultCode=UA-000-001.
※４ When the On-Demand Payment contract is cancelled by the payment provider, the payment provider will notify you about the cancellation of the contract.
FEP server will send the result notification to the merchant, when the relevant Deregistration notification is received.

##### Request Body schema: application/json

Unified API⇒Merchant

| object (result)
status | string <= 10 characters Single byte alphanumeric characters PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Status of Order Result. For details, refer to Status of 'About transaction Result'.
actionCode | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Action code(s) that guide the merchants' actions. The symbols used are the - (hyphen) and the _(underscore).
resultCode | string <= 10 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification A result code indicating the specific reason for the order result. The symbols used are the - (hyphen) and the _(underscore).
message | string <= 1024 characters PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Order result message.
vResultCode | string <= 16 characters Single byte alphanumeric characters PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Code that indicates the detailed process result of the payment server.
| object (order)
payType | string <= 20 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Payment type For the settings details, refer to the payType in the payment request.
paymentId | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification paymentId linked to the target order.
fepOrderId | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification fepOrderId linked to the target order.
originalPaymentId | string <= 64 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment originalPaymentId linked to the target order.
originalFepOrderId | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment originalFepOrderId linked to the target order.
amount | string <= 12 characters Single byte numbers, symbols PayPay Rakuten Pay Docomo au Merpay Payment request Payment request change Capture Cancel On-demand payment Amount to be processed (amount set at the time of request, balance amount when not set) *If not set at the time of cancellation request by forceMode=`refund`, the amount will not be returned.
usedPoint | string <= 12 characters Single byte numbers, symbols Rakuten Pay Payment request Payment request change Capture Cancel On-demand payment Amount equivalent to Rakuten points used (reference value)
cancelExpirationDatetime | string <= 14 characters Single byte numbers <yyyyMMddHHmmss> Rakuten Pay Payment request Payment request change On-demand payment Deadline for accepting cancellation.
captureExpirationDatetime | string <= 14 characters Single byte numbers <yyyyMMddHHmmss> Rakuten Pay Payment request Payment request change On-demand payment Deadline for accepting Capture.
updateExpirationDatetime | string <= 14 characters Single byte numbers <yyyyMMddHHmmss> Rakuten Pay Payment request Payment request change On-demand payment Deadline for accepting changes in amount.
extendAuthExpirationDatetime | string <= 14 characters Single byte numbers <yyyyMMddHHmmss> Rakuten Pay Payment request Payment request change On-demand payment Deadline for accepting payment request extension.
| object (transaction)
fepReferenceId | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification ID used by the Get transaction result API, newly assigned for each request by the FEP server. The symbols used are the - (hyphen) and the _(underscore).
command | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "pay" "subscribe" "update_order" "capture" "cancel" "charge" "terminate" "deregistration" PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification API name of the target order (see below). `Payment request`: pay `On-demand payment request`: subscribe `Payment request change`: update_order `Capture`: capture `Cancel`: cancel `On-demand payment`: charge `Cancellation of contract`: terminate `Deregistration notification`: deregistration
transactionDatetime | string <= 14 characters Single byte numbers <yyyyMMddHHmmss> PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Processing date and time.
merchantRequestKey1 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Contents set at the time of request. *If not set at the time of request, it will not be returned.
merchantRequestKey2 | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Contents set at the time of request. *If not set at the time of request, it will not be returned.
metadata1 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Contents set at the time of request. *If not set at the time of request, it will not be returned.
metadata2 | string <= 2000 characters PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Contents set at the time of request. *If not set at the time of request, it will not be returned.
| object (control)
requestMode | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "live" "sandbox" PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Request Mode. `live`: Live mode request (default value) `sandbox`: sandbox request
| object (provider)
| object (result)
providerErrorInfo | Array of strings[ items <= 128 characters ] Rakuten Pay Payment request Capture Cancel Payment provider API error information. Sets up an array of error information linked from the payment provider. The return value pattern for each payment is described below. Rakuten Pay:String 128 characters or less
| object (payment)
providerOrderId | string <= 64 characters PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification ID issued by the payment provider for each order.
gatewayOrderId | string <= 64 characters PayPay Rakuten Pay Payment request Payment request change Capture Cancel On-demand payment ID issued by the payment server for each order.
inquiryCode | string <= 20 characters Single byte alphanumeric characters Merpay Payment request Cancel On-demand payment Deregistration notification A number for user to check the balance history in the Merpay App.
preapprovalId | string <= 50 characters Single byte alphanumeric characters Merpay On-demand payment request Deregistration notification ID to identify transactions that have been given usage consent for On-Demand Payment Request by Merpay.
| object (customer)
| object (buyer)
nickname | string <= 40 characters Merpay Payment request On-demand payment request Buyer's nickname. The value is set when buyerInfoType=`use`.
phoneNumber | string <= 40 characters Merpay Payment request On-demand payment request Buyer's telephone number. The value is set when buyerInfoType=`use`.
email | string <= 100 characters Merpay Payment request On-demand payment request Buyer's email address. The value is set when buyerInfoType=`use`.
customerId | string <= 256 characters Rakuten Pay Payment request On-demand payment request On-demand payment ID that identifies the consumer.
| object (shipping)
familyName | string <= 100 characters Merpay Payment request On-demand payment request Shipping Address Last Name. The value is set when deliveryAddressType=`use`.
firstName | string <= 100 characters Merpay Payment request On-demand payment request Shipping Address Name. The value is set when deliveryAddressType=`use`.
familyNameKana | string <= 100 characters Merpay Payment request On-demand payment request Shipping Address Last Name (Kana). The value is set when deliveryAddressType=`use`.
firstNameKana | string <= 100 characters Merpay Payment request On-demand payment request Shipping Address Name (Kana). The value is set when deliveryAddressType=`use`.
phoneNumber | string <= 40 characters Single byte numbers Merpay Payment request On-demand payment request Shipping Address Telephone number. The value is set when deliveryAddressType=`use`.
zipCode1 | string <= 10 characters Single byte numbers Merpay Payment request On-demand payment request Shipping Address Zip code (before hyphen). The value is set when deliveryAddressType=`use`.
zipCode2 | string <= 10 characters Single byte numbers Merpay Payment request On-demand payment request Shipping Address Zip code (after hyphen). The value is set when deliveryAddressType=`use`.
preference | string <= 100 characters Merpay Payment request On-demand payment request Shipping Address Prefecture. The value is set when deliveryAddressType=`use`.
city | string <= 100 characters Merpay Payment request On-demand payment request Shipping Address City. The value is set when deliveryAddressType=`use`.
address1 | string <= 200 characters Merpay Payment request On-demand payment request Shipping Address 1. The value is set when deliveryAddressType=`use`.
address2 | string <= 200 characters Merpay Payment request On-demand payment request Shipping Address 2. The value is set when deliveryAddressType=`use`.
| object (paymentInstrument)
| object (rakuten) Rakuten Pay
card3ds | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "used" "not_used" Payment request On-demand payment Whether 3D Secure Authentication is used. `used`: Used `not_used`: Not used
cardCvc | string <= 20 characters Single byte alphanumeric characters, symbols Enum: "used" "not_used" Payment request On-demand payment Whether security code authentication is used `used`: Used `not_used`: Not used
cardInstallments | integer <= 2 characters Single byte numbers Payment request On-demand payment Number of installments of credit card
cardBrand | string <= 48 characters Payment request On-demand payment Credit card brand.
cardLast4 | string <= 4 characters Payment request On-demand payment Last 4 digits of the credit card number.

### Responses

This is the pushUrl specified in each API command.

https://yourdomain/push

### Request samples

- Payload

Content type
application/json
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success",
  - "vResultCode": "1001000000000000"
  },
- "order":
  {
  - "payType": "paypay",
  - "paymentId": "paymentId_1234567890",
  - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "originalPaymentId": "orgPaymentId_1234567890",
  - "originalFepOrderId": "orgPaymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "amount": "10000",
  - "usedPoint": "0",
  - "cancelExpirationDatetime": "20230526123456",
  - "captureExpirationDatetime": "20230526123456",
  - "updateExpirationDatetime": "20230526123456",
  - "extendAuthExpirationDatetime": "20230526123456"
  },
- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
  - "command": "pay",
  - "transactionDatetime": "20230526123456",
  - "merchantRequestKey1": "freeKey1",
  - "merchantRequestKey2": "freeKey2",
  - "metadata1": "freeSpace1",
  - "metadata2": "freeSpace2"
  },
- "control":
  {
  - "requestMode": "sandbox"
  },
- "provider":
  {
  - "result":
    {
    - "providerErrorInfo":
      [
      - "payment_error",
      - "invalid_point"
      ]
    },
  - "payment":
    {
    - "providerOrderId": "XXX00000000001",
    - "gatewayOrderId": "00000000000000000001",
    - "inquiryCode": "inquiryCode12345",
    - "preapprovalId": "preapprovalId1234567890"
    }
  },
- "customer":
  {
  - "buyer":
    {
    - "nickname": "nick",
    - "phoneNumber": 9012341234,
    - "email": "customer.buyer.email@example.com",
    - "customerId": "b613865a-6f72-af74-772d-02279b929876"
    },
  - "shipping":
    {
    - "familyName": "Yamada",
    - "firstName": "Taro",
    - "familyNameKana": "ヤマダ",
    - "firstNameKana": "タロウ",
    - "phoneNumber": "0312341234",
    - "zipCode1": "150",
    - "zipCode2": "0022",
    - "preference": "Tokyo",
    - "city": "Shibuya",
    - "address1": "Ebisu Minami 3-chome",
    - "address2": "5-7, Digital Gate Building, 10th Floor"
    }
  },
- "paymentInstrument":
  {
  - "rakuten":
    {
    - "card3ds": "used",
    - "cardCvc": "used",
    - "cardInstallments": 1,
    - "cardBrand": "JCB",
    - "cardLast4": "1234"
    }
  }

}`

## Get Transaction Result

PayPay Rakuten Pay Docomo au Merpay
Returns the transaction result within the VeriTrans4G Unified API for the transaction linked with the specified fepReferenceId.

### About Execution Result

This API returns the transaction information at of the time the transaction linked to the specified fepReferenceId was executed.
The information returned will be of same extent to that of a Webhook.
However, if any of the following conditions apply, the transaction is not yet complete or finalized. In such cases, executing Get Transaction Result will not return transaction details and will result in (resultCode: UA-U00-001).(resultCode:UA-U00-001)。

Trigger | Condition
--- | ---
After payment request execution | The period between submitting the payment request and receiving the redirect from the consumer's browser to the merchant's completion page.
After on-demand payment execution | If the payment result is "UA-U00-001 (user_paying)", the period until the corresponding Webhook is received.

##### Request Body schema: application/json

Merchant⇒Unified API

| object (transaction)
fepReferenceId required | string <= 100 characters Single byte alphanumeric characters, symbols PayPay Rakuten Pay Docomo au Merpay Payment request On-demand payment request Payment request change Capture Cancel On-demand payment Cancellation of contract Deregistration notification Specifies the fepReferenceId that was set in the response to the order for which you want to obtain results.

### Responses

Until the end of July 2025(Live)

https://api.unified.veritrans.co.jp/fep/command/get-txn-result

Until the end of July 2025(Sandbox)

https://api.sandbox.unified.veritrans.co.jp/fep/command/get-txn-result

August 2025 onward(Live)

https://api.unified.veritrans.jp/fep/command/get-txn-result

August 2025 onward(Sandbox)

https://api.sandbox.unified.veritrans.jp/fep/command/get-txn-result

### Request samples

- Payload

Content type
application/json
`
{

- "transaction":
  {
  - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH"
  }

}`

### Response samples

- 200
- 400
- 500

Content type
application/json
Example
OK
`
{

- "result":
  {
  - "status": "success",
  - "actionCode": "success",
  - "resultCode": "UA-000-001",
  - "message": "success"
  },
- "transactionData":
  {
  - "result":
    {
    - "status": "success",
    - "actionCode": "success",
    - "resultCode": "UA-000-001",
    - "message": "success",
    - "vResultCode": "1001000000000000"
    },
  - "order":
    {
    - "payType": "paypay",
    - "paymentId": "paymentId_1234567890",
    - "fepOrderId": "paymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
    - "originalPaymentId": "orgPaymentId_1234567890",
    - "originalFepOrderId": "orgPaymentId_1234567890_01AHK4HS7GFKHGKE7SGFJKTHIH",
    - "amount": "1000",
    - "usedPoint": "0",
    - "cancelExpirationDatetime": "20230526123456",
    - "captureExpirationDatetime": "20230526123456",
    - "updateExpirationDatetime": "20230526123456",
    - "extendAuthExpirationDatetime": "20230526123456"
    },
  - "transaction":
    {
    - "fepReferenceId": "X01AHK4HS7GFKHGKE7SGFJKTHIH",
    - "command": "pay",
    - "transactionDatetime": "20230526123456",
    - "merchantRequestKey1": "freeKey1",
    - "merchantRequestKey2": "freeKey2",
    - "metadata1": "freeSpace1",
    - "metadata2": "freeSpace2"
    },
  - "control":
    {
    - "requestMode": "sandbox"
    },
  - "provider":
    {
    - "result":
      {
      - "providerErrorInfo":
        [
        - "payment_error",
        - "invalid_point"
        ]
      },
    - "payment":
      {
      - "providerOrderId": "XXX00000000001",
      - "gatewayOrderId": "00000000000000000001",
      - "inquiryCode": "inquiryCode12345",
      - "preapprovalId": "preapprovalId1234567890"
      }
    },
  - "customer":
    {
    - "buyer":
      {
      - "customerId": "b613865a-6f72-af74-772d-02279b929876"
      }
    },
  - "paymentInstrument":
    {
    - "rakuten":
      {
      - "card3ds": "used",
      - "cardCvc": "used",
      - "cardInstallments": 1,
      - "cardBrand": "JCB",
      - "cardLast4": "1234"
      }
    }
  }

}`

# Testing

VeriTrans4G Unified API provides both a Sandbox environment and a Live environment.
For the request URLs for each environment, please refer to the "HTTP Request Details" section.
In the Sandbox environment, orders can be tested without connecting to the actual payment provider.
Failed transactions can also be simulated by setting specific values for the amount in each API.
After verifying functionality in the Sandbox environment, please perform testing in the Live environment with an actual connection to the payment provider to confirm the provider's behavior.
In the Sandbox environment, dummy values are used for fields set by payment providers, and the operation is simplified for testing purposes.
Therefore, before the merchant releases the system, please ensure that thorough testing is conducted in the Live environment to confirm actual values and operation.
Use the Merchant ID issued to each merchant when conducting tests.
For usage before signing a contract, please contact us as needed.

The returned result codes (resultCode and vResultCode) may be added in the future without prior notice.

## PayPay simulation details

Payment Request (Single Payment)

The last digit of the payment request amount (amount) can be modified to intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Payment Request
resultCode | vResultCode
0 | UA-000-001(Success) | 1001
1
2
3
4
5
6
7
8 | UA-PRV-001(Failure) | 1GD1
9 | UA-000-001(Success) | 1001

If the consumer's browser is redirected using the redirectUrl received in the payment request response, it will navigate to the following dummy environment.
*Please note that the appearance of the dummy PayPay page may vary depending on PayPay's specifications.

On-Demand Payment Request (On-Demand Payment)

All test requests for On-Demand payment will be processed successfully.
If the consumer's browser is redirected using the redirectUrl received in the payment request response, it will navigate to the following dummy environment.
*Please note that the appearance of the dummy PayPay page may vary depending on PayPay's specifications.

Other APIs

The last digit of the Capture, Cancel, or On-Demand payment request amount (amount) can be modified to intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Capture | Cancel | On-Demand Payment
resultCode | vResult Code | resultCode | vResult Code | resultCode | vResult Code
0 | UA-000-001(Success) | 1001 | UA-000-001(Success) | 1001 | UA-000-001(Success) | 1001
1 | UA-PRV-001(Failure) | 1GD2
2 | UA-PND-001(Failure) | 1E50
3 | UA-PRV-001(Failure) | 1GD5 | UA-000-001(Success) | 1001 | UA-PRV-001(Failure) | 1GD6
4 | UA-PND-001(Failure) | 1E50 | UA-PND-001(Failure) | 1E50
5 | UA-000-001(Success) | 1001 | UA-CST-001(Failure) | 1G02※1
UA-U00-001(Success) | 1G21※2
6 | UA-000-001(Success) | 1001
7
8
9

※1 If recoveryType=not_recovery
※2 If recoveryType=recovery. It is then redirected to 1001 (Success).
・ In the case of a Cancel with an unspecified amount, it will be treated as if the full balance amount is specified.
・ In the case of a Capture with an unspecified amount, it will be treated as if the full payment amount has been specified.

## Rakuten Pay simulation details

Payment Request (Single Payment)

The last digit of the payment request amount (amount) can be modified to intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Payment Request
resultCode | vResultCode
0 | UA-000-001(Success) | F001
1 | UA-PRV-999(Failure) | FG90
2 | UA-PRV-001(Failure) | FG24
3 | UA-000-001(Success) | F001
4
5
6
7
8
9

If the consumer's browser is redirected using the redirectUrl received in the payment request response, it will navigate to the following dummy environment.
The payment result can also be selected on the "Confirm Payment Details" page. The selection you make will change the result of the redirection.
*Please note that the appearance of the dummy Rakuten Pay page may vary depending on Rakuten Pay specifications.

Payment Result Selection | Redirect
resultCode | vResultCode
Success | UA-000-001(Success) | F001
Interruption | UA-PND-001(Failure) | FED1
Failure(Point Fraud) | - | FG11※
Failure(Payment Failure) | UA-PRV-001(Failure) | FG24
Failure(Under Maintenance) | UA-PRV-999(Failure) | FG90

*It will redirect to the "Payment Details Confirmation" page of the dummy Rakuten Pay.

On-Demand Payment Request (On-Demand Payment)

The value of (name) under the request item[] of the On-Demand payment request can be used to intentionally cause an error.

name | Payment Request
resultCode | vResultCode
fail | UA-PRV-999(Failure) | FG90
Other than above | UA-000-001(Success) | F001

If the consumer's browser is redirected using the redirectUrl received in the payment request response, it will navigate to the following dummy environment.
*Please note that the appearance of the dummy Rakuten Pay page may vary depending on Rakuten Pay specifications.
The payment request result can also be selected on the "Confirm Payment Request Details" page. The selection you make will change the result of the redirection.

Payment Request Result Selection | Redirect
resultCode | vResultCode
Success | UA-000-001(Success) | F001
Interruption | UA-PND-001(Failure) | FED1
Failed (Consent Expired) | UA-REQ-006(Failure) | FG26

Other APIs

By adjusting the last digit of the requested amount for Capture, Cancel, Payment Request Change, and On-Demand payment, you can intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Capture | Cancel | Change Payment Request | On-Demand Payment
Full Amount Capture | Partial Capture | Authorization Extension | Amount change | Authorization Extension + Amount Change
resultCode | vResult Code | resultCode | vResult Code | resultCode | vResult Code | resultCode | vResult Code | resultCode | vResult Code | resultCode | vResult Code | resultCode | vResult Code
0 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001
1 | UA-PRV-999(Failure) | FG90 | UA-PND-001(Failure) | FED1 | UA-PRV-999(Failure) | FG90 | UA-PRV-999(Failure) | FG90
2 | UA-PND-001(Failure) | FED1 | UA-PND-001(Failure) | FED1 | UA-PRV-999(Failure) | FG90 | UA-000-001(Success) | F001 | UA-PND-001(Failure) | FED2 | UA-PND-001(Failure) | FED2
3 | UA-PRV-001(Failure) | FG30 | UA-PND-001(Failure) | FED2 | UA-000-001(Success) | F001
4 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-000-001(Success) | F001 | UA-PND-001(Failure) | FED1
5 | UA-PND-001(Failure) | FED1 | UA-PND-001(Failure) | FED2 | UA-PND-001(Failure) | FED2 | UA-PRV-001(Failure) | FG30
6 | UA-PRV-001(Failure) | FG30 | UA-PRV-001(Failure) | FG30 | UA-PRV-001(Failure) | FG30 | UA-PRV-999(Failure) | FG90
7 | UA-000-001(Success) | F001 | UA-REQ-006(Failure) | FG26 | UA-000-001(Success) | F001 | UA-PND-001(Failure) | FED2 | UA-PND-001(Failure) | FED2 | UA-PRV-001(Failure) | FG24
8 | UA-REQ-006(Failure) | FG26 | UA-PRV-001(Failure) | FG29 | UA-PND-001(Failure) | FED1 | UA-REQ-006(Failure) | FG26 | UA-PRV-001(Failure) | FG29
9 | UA-PRV-001(Failure) | FG30 | UA-000-001(Success) | F001 | UA-PRV-001(Failure) | FG30 | UA-PND-001(Failure) | FED1

・ In the case of a Cancel with an unspecified amount, it will be treated as if the full balance amount is specified.
・ In the case of a Capture with an unspecified amount, it will be treated as if the full payment amount has been specified.

## Docomo simulation details

Payment Request (Single Payment)

If the consumer's browser is redirected using the redirectUrl received in the Single Payment request result, it will be automatically redirected to the following dummy environment.
*Please note that the appearance of the dummy d Payment page may vary depending on d Payment's specifications.
Selecting "Cancel Purchase" on the Payment Method Selection page or Payment Details confirmation page will change the redirect result.

name | Payment Request
resultCode | vResultCode
Purchase Cancellation | UA-CST-002(Failure) | WGU1
Other than above | UA-000-001(Success) | W001

On-Demand Payment Request (On-Demand Payment)

When a redirect instruction is given using the redirectUrl returned as the result of the On-Demand payment request, it will automatically transition to the following dummy environment.
*Please note that the appearance of the dummy d Payment page may vary depending on d Payment's specifications.
Selecting "Cancel Purchase" on the Payment Method Selection page or Payment Details confirmation page will change the redirect result.

name | Payment Request
resultCode | vResultCode
Purchase Cancellation | UA-CST-002(Failure) | WGU1
Other than above | UA-000-001(Success) | W001

Other APIs

The last digit of the Capture, Cancel, or On-Demand payment request amount (amount) can be modified to intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Capture | Cancel | Change Payment Request
resultCode | vResultCode | resultCode | vResultCode | resultCode | vResultCode
0 | UA-000-001(Success) | W001 | UA-000-001(Success) | W001 | UA-000-001(Success) | W001
1
2 | UA-PRV-001(Failure) | WG02
3 | UA-PRV-001(Failure) | WG02 | UA-000-001(Success) | W001
4 | UA-000-001(Success) | W001 | UA-PRV-001(Failure) | WA02
5 | UA-CST-001(Failure) | WG12
6 | UA-SYS-002(Failure) | WG05
7 | UA-PRV-001(Failure) | WG02
8 | UA-CST-001(Failure) | WG04
9 | UA-000-001(Success) | W001

・ In the case of a Cancel with an unspecified amount, it will be treated as if the full balance amount is specified.
・  In the case of a Capture with an unspecified amount, it will be treated as if the full payment amount has been specified.

## au simulation details

Payment Request (Single Payment)

The last digit of the payment request amount (amount) can be modified to intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | resultCode | vResultCode
0 | UA-000-001(Success) | W001
1
2
3
4
5 | UA-PRV-001(Failure) | WG02
6 | UA-CST-001(Failure) | WG04
7 | UA-PRV-001(Failure) | WG02
8 | UA-CST-001(Failure) | WG04
9 | UA-000-001(Success) | W001

When redirect instructions are given using the redirectUrl returned as a result of the payment request, the user is automatically redirected to the following dummy environment depending on the payment authentication type (paymentAuthenticationType).
※The image of auPAY (au Easy Payment) and auPay (Online payment) dummy pages may change depending on au specifications.
※The dummy page image of auPAY (au Easy Payment) and auPAY (Online payment) web method is the same.

### For ID authentication method (auPAY (au Easy Payment) and auPAY (Online payment) web method))

Selecting "Cancel" on the Payment Method Selection or Payment Details will change the result of the Redirect.

name | Payment Request
resultCode | vResultCode
Cancel | UA-CST-002(Failure) | WGU1
Other than above | UA-000-001(Success) | W001

### For application authentication method (auPAY (Online payment) Application method)

Selecting a combination of checkboxes and buttons on the Payment page will change the Redirect result.

Checkbox | Button | resultCode | vResultCode
Normal | Payment Success | UA-000-001(Success) | W001
Payment Failure | UA-PRV-001(Failure) | -
Cancel | UA-CST-002(Failure) | -
Redirect failure from auPAY app※ | Payment Success | UA-000-001(Success) | W001
Payment failure | UA-U00-001(In process) | -
Cancel

※Because Redirect fails, the value in the table is the response to the Get transaction result process.
In addition, when Redirect fails, the user will be redirected to the following page.

On-Demand Payment Request (On-Demand Payment)

When a redirect instruction is given using the redirectUrl returned as the result of the On-Demand payment request, it will automatically transition to the following dummy environment.
*The image of auPAY (au Easy Payment) and auPAY (Online payment) dummy pages may change depending on au specifications.
Selecting "Cancel" on the Payment Method Selection or Payment Details will change the result of the Redirect.

name | Payment Request
resultCode | vResultCode
Cancel | UA-CST-002(Failure) | WGU1
Other than above | UA-000-001(Success) | W001

Other APIs

By adjusting the last digit of the requested amount for Capture, Cancel, Payment Request Change, and On-Demand payment, you can intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Capture | Cancel | Change Payment Request | On-Demand Payment
resultCode | vResultCode | resultCode | vResultCode | resultCode | vResultCode | resultCode | vResultCode
0 | UA-000-001(Success) | W001 | UA-000-001(Success) | W001 | UA-000-001(Success) | W001 | UA-000-001(Success) | W001
1 | UA-CST-001(Failure) | WG04
2 | UA-PRV-001(Failure) | WG02 | UA-CST-001(Failure) | WG35
3 | UA-000-001(Success) | W001 | UA-PRV-001(Failure) | WG02 | UA-000-001(Success) | W001
4 | UA-000-001(Success) | W001
5 | - | - | UA-PRV-001(Failure) | WG02
6 | UA-CST-001(Failure) | WG04
7 | UA-PRV-001(Failure) | WG02
8 | UA-CST-001(Failure) | WG04
9 | UA-000-001(Success) | W001 | UA-000-001(Success) | W001

## Merpay simulation details

Payment Request (Single Payment)

The last digit of the payment request amount (amount) can be modified to intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | resultCode | vResultCode
0 | UA-000-001(Success) | K001
1 | UA-PRV-001(Failure) | KG10
2 | UA-000-001(Success) | K001
3
4
5
6
7 | UA-PRV-999(Failure) | KG11
8 | UA-000-001(Success) | K001
9

If the consumer's browser is redirected using the redirectUrl received in the payment request response, it will navigate to the following dummy environment.
*The image of the dummy Merpay page may change depending on Merpay's specifications.
Selecting a combination of checkboxes and buttons on the Payment page will change the Redirect result.

Access Permission Page | Payment | resultCode | vResultCode
Button | Checkbox
Allow | Pay | Success | UA-000-001 | K001
Deemed success (result notification from Mercari is not received) | K003
Deemed success (error in payment confirmation process) | K003
Failure (Error in redirect * Result notification is successful) | K001
Cancel | - (Other than failure) | UA-CST-001 | KGU1
Failure (Error in redirect * Result notification is successful) | UA-000-001 | K001
Cancel | - | UA-CST-001 | KGU1

On-Demand Payment Request (On-Demand Payment)

When a redirect instruction is given using the redirectUrl returned as the result of the On-Demand payment request, it will automatically transition to the following dummy environment.
*The image of the dummy Merpay page may change depending on Merpay's specifications.
Selecting a combination of checkboxes and buttons on the Payment page will change the Redirect result.
The combination and return values are the same as for Single Payment.

Other APIs

By adjusting the last digit of the requested amount for Capture, Cancel, Payment Request Change, and On-Demand payment, you can intentionally trigger an error.
The table below shows the last digit of the amount and its corresponding response, including the resultCode and vResultCode.

Last Digit of Amount | Capture | Cancel | On-Demand Payment
Before capture | After capture
resultCode | vResultCode | resultCode | vResultCode | resultCode | vResultCode | resultCode | vResultCode
0 | UA-000-001(Success) | K001 | UA-000-001(Success) | K001 | UA-000-001(Success) | K001 | UA-000-001(Success) | K001
1 | - | - | UA-PRV-001(Failure) | KG10 | UA-PRV-001(Failure) | KG10
2 | UA-000-001(Success) | K001 | UA-PND-001(Failure) | KED1 | UA-000-001(Success) | K001
3 | UA-000-001(Success) | K001 | UA-PRV-002(Failure) | KG19
4 | UA-CST-001(Failure) | KG15
5 | UA-PRV-001(Failure) | KG10 | UA-PRV-001(Failure) | KG10 | UA-000-001(Success) | K001
6 | UA-PND-001(Failure) | KED1 | UA-PND-001(Failure) | KED1
7 | UA-000-001(Success) | K001 | - | - | UA-PRV-999(Failure) | KG11 | UA-PRV-999(Failure) | KG11
8 | UA-PRV-999(Failure) | KG11 | UA-PRV-999(Failure) | KG11 | UA-000-001(Success) | K001 | UA-000-001(Success) | K001
9 | UA-000-001(Success) | K001 | UA-000-001(Success) | K001

## Test scenario

Below is an example of how to simulate each error case.
The APIs and settings related to simulation are described in blue.

Single Payment

Payment request failure

Payment failure

Consumer payment failure

Payment Request change failure

Capture failure

'Cancel Before Capture' failure

Refund failure (Authorization only)

Refund failure (Authorization with Capture)

Refund failure after partial refund

On-Demand Payment (Original Order)

On-Demand Payment Request failure

Consent failure

Consumer Consent Failure

Contract Cancellation Failure

On-Demand Payment (On-Demand Payment)

On-Demand Payment Request failure

Capture failure

Payment Request change failure

'Cancel Before Capture' failure

Refund failure (Authorization only)

Refund failure (Authorization with Capture)

Refund failure after partial refund

# 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. Overview Introduction List of APIs APIs Payment Request Added au to request items merchant.storeId and merchant.terminalId. Added paymentAuthenticationType to paymentInstrument.au and added a note to loginType Testing au Simulation Details From the following command in "APIs", changed the maximum number of digits in order.amount in the request item for au/docomo, from "12" to "7" for au and "8" for docomo Payment Request Cancel On-Demand payment Payment Request Change Others: Minor wording and formatting corrections
1.1.1 RC | 2025/09 | Deleted the response item customer.buyer.customerId from the following command in "APIs" because it is no longer returned for "PayPay". On-Demand Payment Cancellation of contract Get transaction result Webhook Changed the maximum number of characters in the following response item provider.payment.providerOrderId in "APIs" to "64". Cancel Capture Cancellation of Contract Payment Request Change Changed the company name from "Rakuten Group, Inc." to "Rakuten Payments, Inc.". Changed the au Easy Payment service name to auPAY (au Easy Payment). Updated other minor format adjustments.
1.1.0 RC | 2025/06 | With the addition of Docomo, au, and Merpay, added the following related description. Overview Introduction List of APIs Payment Life Cycle Payment Sequence APIs Payment Request On-Demand Payment Request Redirect Change Payment Request Capture Cancel On-Demand Payment Cancellation of Contract Webhook Get Transaction Result Testing Docomo Simulation Details au Simulation Details Merpay Simulation Details Test Scenario With the addition of the Payment Request change API, added the following related description Overview List of APIs Payment Sequence Payment Flow Payment Life Cycle APIs Change Payment Request Webhook Get Transaction Result Testing Rakuten Pay Simulation Details au Simulation Details Test Scenario Added description about the port number to the following "HTTP Request Details" in "About API" Introductory summary of "Webhook" in "APIs" pushUrl request item for the below "APIs" Payment Request On-Demand Payment Request Change Payment Request Capture Cancel On-Demand Payment Cancellation of Contract Updated the merchant support description for "alternate_payment" in the "Action Code" table under "Transaction Result" Added a note about the "Merchant ID used for testing" to the beginning of "Testing" Changed the link destination in the description of result.status response field under "APIs" from "About Transaction Result" to its sub-section "Status" APIs Payment Request On-Demand Payment Request Change Payment Request Capture Cancel On-Demand Payment Cancellation of Contract Get Transaction Result Updated the description of the reason request field in "Cancel" under "APIs" Added the MAP configuration page to "About Bearer Authentication" Added description about the new domain to "Notices" Added the description of old domain and new domain below HTTP Request Details APIs Payment Request On-Demand Payment Request Change Payment Request Capture Cancel On-Demand Payment Cancellation of Contract Get Transaction Result With the addition of the new Result Code (UA-000-002), added the following related description About API About Various IDs Related to the Order Added description of UA-000-002 in the Description statement of paymentId About transaction Result Result code (HTTPS status code: 200, resultCode: UA-000-002) Action code (actionCode : confirm_payment) Changed the maximum character length of the result.actionCode response field under "APIs" to "64" APIs Payment Request On-Demand Payment Request Redirect Change Payment Request Capture Cancel On-Demand Payment Cancellation of Contract Webhook Get Transaction Result Changed the maximum character length of the provider.payment.gatewayOrderId response field under "APIs" to "64", and added the "PayPay" tag for On-Demand Payment only APIs Cancel Capture On-Demand Payment Updated other minor format adjustments
1.0.1 RC | 2024/12 | Added a note about the PayPay connection method to the API list Deleted the description about the behavior when not set from the following fields APIs Payment Request successUrl cancelUrl errorUrl On-Demand Payment Request successUrl cancelUrl errorUrl Updated input value limit in the Payment Request / On-Demand Payment Request / On-Demand Payment request id fields for PayPay Added the description about responses to the following items APIs Redirect Webhook Updated other minor format adjustments
1.0.0 RC | 2024/08 | With the addition of On-Demand Payment, added the following related description: Overview Payment Method List of APIs Payment Sequence Payment Flow Payment Life Cycle About API About Various IDs Related to the Order APIs On-Demand Payment Request On-Demand Payment Webhook Cancellation of Contract Get Transaction Result Testing PayPay Simulation Details Rakuten Pay Simulation Details Test Scenario Updated the URL domain in the HTTP Request Details Changed the data type of amount in both request and response items from integer to string *This applies to all APIs that include amount in their request and response items Removed balance from the response items *This applies to all APIs that had balance in their response items Changed the following in the Payment Request item Added storeId and terminalId Changed the number of allowed digits for userAgent Changed the specification type of successUrl, cancelUrl, and errorUrl from Optional to Required Separated the supplementary information into a separate volume
1.0.0 β | 2023/12 | Newly created