Getting Started
Overview
- User performs the checkout operation
- Merchant server makes an API request to the POP server to get the
payment_key
- POP Server responds to the API call with the
payment_key
- Merchant server constructs the html page and sends it back to the browser
- User verifies the details and clicks the pay button. Merchant’s JavaScript code calls
pop.pay(payment_key, options)
. User then fills up the payment details and clicks the confirm button. POP JS sends the payment details to the POP Server- POP Server processes the details and responds with the payment status. POP JS then either calls the corresponding callback provided by the merchant’s JavaScript code or the URL provided in the request.
- POP Server notifies the merchant server about the payment status
Preparation
You need to register with VeriTrans and get your ID and password to access the MAP(Merchant Administration Portal).
VeriTrans will issue the POP_SERVER_KEY
and POP_CLIENT_KEY
that can be retrieved from API Settings in the MAP.
These keys are essential for integrating your application with VeriTrans.
Merchant Server Integration
The goal of Merchant Server Integration is to get the payment_key
from the POP Server.
Only when the payment_key
is received will the Merchant Server be able to proceed to the next step - Client Integration.
Steps to integrate POP Server
The merchant server integrates with the POP Server in order to realise step #2 in the Overview.
When the customer performs the checkout operation the Merchant Server makes an API call to the POP Server with a request having the required details.
The POP Server responds with the payment_key
in the response.
This given payment_key
is used in Client Integration.
Endpoint
Payment Key
https://pay3.veritrans.co.jp/pop/v1/payment-key
Request
This Request is sent by the Merchant Server to the POP Server. The purpose of the request is to retrieve the Payment Key from the POP Server.
HTTP Method
POST
Request Headers
POP_SERVER_KEY = "Test-POP-Server-Key";
AUTH_STRING = Base64("Test-POP-Server-Key:");
AUTH_STRING = "VGVzdC1QT1AtU2VydmVyLUtleTo=";
To create a valid HTTP POP request, the following two headers are set in the request.
Content-Type: application/json; charset=utf-8
Authorization: Basic AUTH_STRING
POP validates the HTTP request by using Basic Authentication method. The username is your POP_SERVER_KEY
while the password is empty.
You can see your POP_SERVER_KEY
on API Settings.
Authorization
header value is represented by AUTH_STRING
.
AUTH_STRING
is the base-64 encoded string of your username & password.
AUTH_STRING
= Base64(POP_SERVER_KEY
+ :
)
Request Parameters
Request with minimum parameters
{
"order_id" : "ORDER-0001",
"gross_amount" : 10000
}
Request with all parameters
{
"order_id" : "ORDER-0001",
"gross_amount" : 10050,
"shipping_amount" : 50,
"dummy" : true,
"capture" : true,
"payment_key_expiry_duration" : 1440,
"success_url" : "https://example.com/success",
"failure_url" : "https://example.com/failure",
"incomplete_url" : "https://example.com/incomplete",
"push_url" : "https://example.com/push",
"enabled_payment_types" : [
"card",
"cvs",
"bank"
],
"card" : {
"mpi" : false,
"paynow_account_id" : "TEST-ACCOUNT-101",
"save_card" : "always",
"skip_card_selection" : false
},
"cvs" : [
{
"payment_sub_type" : "sej",
"payment_expiry_duration" : 60
},
{
"payment_sub_type" : "econ",
"payment_expiry_date" : "20200401"
},
{
"payment_sub_type" : "other",
"payment_expiry_date" : "20200401",
"payment_expiry_hhmm" : "2359"
}
],
"bank" : {
"payment_type" : [
{
"payment_sub_type" : "atm",
"payment_expiry_duration" : 60
}
],
"contents" : "テスト請求",
"contents_kana" : "テストセイキュウ"
},
"email" : {
"customer_name" : "スミス ジョン",
"customer_email_address" : "smith.john@example.com"
},
"items" : [
{
"id" : "ITEM-0001",
"name" : "ITEM NAME *",
"price" : 10000,
"quantity" : 1
}
],
"custom_message" : {
"show_items_additional_message" : true,
"items_additional_message" : "[*] サンプルメッセージ"
}
}
The request body will have these following parameters.
Parameter | Description |
---|---|
order_id string(100) (required) |
Unique Order Id to be provided by merchant. Accepts alphanumeric characters and ‘-’ (hyphen) and ‘_’ (underscore) only. Any other characters are not allowed. |
gross_amount number(10) (required) |
Order total including the Shipping charges. This amount should be always greater than zero. |
shipping_amount number(8) (optional) |
Shipping charges levied by Merchant |
dummy boolean (optional) |
This flag is set to decide if the request is dummy. A dummy request will not go through the actual payment process. A dummy request should be used to test your integration with the VeriTrans. Values: true or false (Default: false ) |
success_url string(256) (optional) |
POP will redirect the customer to this URL after the transaction is successful. If this is not provided then POP will use “Success URL” value set in “System Settings” tab of POP Settings in the MAP. |
failure_url string(256) (optional) |
POP will redirect the customer to this URL if the transaction fails. If this is not provided then POP will use “Failure URL” value set in “System Settings” tab of POP Settings in the MAP. |
incomplete_url string(256) (optional) |
POP will redirect the customer to this URL if the transaction remains incomplete due to some issues like network connectivity problems or customer clicked back button or payment_key expired, etc. If this is not provided then POP will use “Incomplete URL” value set in “System Settings” tab of POP Settings in the MAP. |
push_url string(256) (optional) |
POP pushes asynchronous notification to this URL. If this is not provided then POP will use “Push URL” value set in “System Settings” tab of POP Settings in the MAP. This URL is used in Push Notification. Notification is sent for both the statuses viz. success and failure |
enabled_payment_types array (optional) |
This is an array of values that indicate the payment types supported for the Merchant. If this is not provided then POP will use “Enabled Payment Types” value set in “System Settings” tab of POP Settings in the MAP. Values: card - For Card paymentscvs - For Convenience Store paymentsbank - For Bank payments. |
capture boolean (optional) |
This flag is set to decide if the payment authorization and capture should be done simultaneously. Values: true or false (Default: true ) |
payment_key_expiry_duration number(14) (optional) |
Specifies the validity period in minutes after the payment_key is generated until it becomes unusable.Maximum value: 129600 (90 days) Default: 1440 (1 day) |
card object (optional) Card Parameters |
JSON object to provide Card payment type specific parameters |
cvs array (optional) Convenience Store Parameters |
Array of JSON objects to provide Convenience Store payment type specific parameters |
bank array (optional) Bank Parameters |
JSON object to provide Bank payment type specific parameters |
email object (optional) Customer email Parameters |
JSON object to provide the name and email address of the customer making the purchase |
items array (optional) Items Details |
Array of items included in the order. If this list is not provided then no items are displayed in the Order Summary and Payment Confirmation screens. |
custom_message object (optional) Custom Message Parameters |
JSON object to provide details of additional message(s) for the item(s) |
Card Parameters
{
"card" : {
"mpi" : false,
"paynow_account_id" : "TEST-ACCOUNT-101",
"save_card" : "always",
"skip_card_selection" : false
}
}
{
"card" : {
"mpi" : true,
"3ds_version" : "2",
"paynow_account_id" : "TEST-ACCOUNT-101",
"save_card" : "always",
"skip_card_selection" : false,
"cardholderEmail" : "smith.john@example.com",
"cardholderHomePhoneNumber" : "0312345678",
"cardholderHomePhoneNumberCountry" : "81",
"cardholderMobilePhoneNumber" : "08012345678",
"cardholderMobilePhoneNumberCountry" : "81",
"cardholderWorkPhoneNumber" : "08012345678",
"cardholderWorkPhoneNumberCountry" : "81"
}
}
The following parameters are specific to the Card payment type.
Parameter | Description |
---|---|
mpi boolean (optional) |
Flag indicating if 3D Secure Authentication should be done for this order. If this is not provided then POP will use “Enable 3D Secure” value set in “System Settings” tab of POP Settings in the MAP. Values: true or false |
string(100) (optional) |
The unique account ID of the customer. If the Payment Gateway does not find an account with this ID and the customer chooses to save a card then it creates a new account. ※ Contract for PayNowID is required separately. |
save_card string(20) (optional) |
This flag decides if the customer is allowed to choose whether card details are saved or not. This parameter can be set only when paynow_account_id is set.Values: always : Any new card will be always saved and customer will not have to choose. optional : Saving a new card is optional for the customer. Default: always |
skip_card_selection boolean (optional) |
This flag skips the saved card selection screen and automatically chooses the default saved card for the customer. This parameter can be set only when paynow_account_id is set.Values: true : Saved cards are not displayed and the default is automatically chosen. false : Saved cards are displayed so that customer can either choose any of the saved cards or use another card. Default: false |
3ds_version string(1) (optional) |
If mpi is specified as true, it is possible to set the 3D secure version. If this parameter is not specified, the value set for “3D Secure Version” in “System Settings” tab of POP settings in the MAP will be used. Values: 1 or 2 |
cardholderEmail string(254) (optional) |
Cardholder email address. Used in the 3D Secure (identity authentication) process.Please also check the explanation of mpi parameter. |
cardholderHomePhoneNumber string(15) (optional) |
Cardholder home phone number. Used in the identity authentication process. Only half-width numbers can be used for this parameter. (hyphens cannot be used) Need to specify if 3D Secure (identity authentication) is enabled. Please also check the explanation of the mpi parameter. |
cardholderHomePhoneNumberCountry string(3) (optional) |
Cardholder home phone number country code.Used in the 3D Secure (identity authentication) process. Only half-width numbers can be used for this parameter.(Specify regional country code regulated by ITU-T E.164) Default: 81 (Japan’s country code)If you set up a phone number, the country code is always required. As default values are set for Japanese phone numbers, so it is not necessary to set them. But for an overseas number, please make sure to set the correct country code. |
cardholderMobilePhoneNumber string(15) (optional) |
Cardholder mobile phone number. Used in the identity authentication process. Only half-width numbers can be used for this parameter. (hyphens cannot be used) Need to specify if 3D Secure (identity authentication) is enabled. Please also check the explanation of the mpi parameter. |
cardholderMobilePhoneNumberCountry string(3) (optional) |
Cardholder mobile phone number country code.Used in the 3D Secure (identity authentication) process. Only half-width numbers can be used for this parameter.(Specify regional country code regulated by ITU-T E.164) Default: 81 (Japan’s country code)If you set up a phone number, the country code is always required. As default values are set for Japanese phone numbers, so it is not necessary to set them. But for an overseas number, please make sure to set the correct country code. |
cardholderWorkPhoneNumber string(15) (optional) |
Cardholder work phone number. Used in the identity authentication process. Only half-width numbers can be used for this parameter. (hyphens cannot be used) Need to specify if 3D Secure (identity authentication) is enabled. Please also check the explanation of the mpi parameter. |
cardholderWorkPhoneNumberCountry string(3) (optional) |
Cardholder work phone number country code.Used in the 3D Secure (identity authentication) process. Only half-width numbers can be used for this parameter.(Specify regional country code regulated by ITU-T E.164) Default: 81 (Japan’s country code)If you set up a phone number, the country code is always required. As default values are set for Japanese phone numbers, so it is not necessary to set them. But for an overseas number, please make sure to set the correct country code. |
Convenience Store Parameters
{
"cvs" : [
{
"payment_sub_type" : "sej",
"payment_expiry_duration" : 60
},
{
"payment_sub_type" : "econ",
"payment_expiry_date" : "20200401"
},
{
"payment_sub_type" : "other",
"payment_expiry_date" : "20200401",
"payment_expiry_hhmm" : "2359"
}
]
}
The following parameters are specific to the Convenience Store payment type.
Parameter | Description |
---|---|
payment_sub_type string (required) |
This is the name of the store (or group of stores) that the customer can choose to make the payment in. If the cvs element is present then at least one payment_sub_type should be provided. If the cvs element is not present then POP will use “Enabled payment sub type” value set in “System Settings” tab of POP Settings in the MAP. Values: sej - 7-Elevenlawson - Any of Lawson, MINISTOP or Seicomartfamima - FamilyMartecon - Any of Lawson, FamilyMart, Seicomart or MINISTOPother - Daily YAMAZAKI |
payment_expiry_duration number (optional) |
This indicates the number of days from getting payment_key , after which payment cannot be made. If this parameter and payment_expiry_date are not specified, the following default values apply:sej : 60 daysecon : 60 dayslawson : 60 daysfamima : 60 daysother : 60 days |
payment_expiry_date string(8) (optional) |
This indicates the date (YYYYMMDD format) after which payment cannot be made. The date cannot be beyond the maximum limits set for payment_expiry_duration . |
payment_expiry_hhmm string(4) (optional) |
This indicates the time (hhmm format) after which payment cannot be made. This can be set only when payment_expiry_date is set.Default:2359 |
Bank Parameters
{
"bank" : {
"payment_type" : [
{
"payment_sub_type" : "atm",
"payment_expiry_duration" : 60
}
],
"contents" : "テスト請求",
"contents_kana" : "テストセイキュウ"
}
}
The following parameters are specific to the Bank payment type.
Parameter | Description |
---|---|
payment_type array (optional) |
Array of JSON objects used to provide the details of the payment type under Bank. |
payment_type.payment_sub_type string(3) (required) |
Used to set the method of bank settlement that can be selected when consumers make payment. If the payment_type parameter is not provided, POP will use the value set for “Enabled Payment Sub Type” in “Bank Information” section on the “Settings” tab of POP settings in MAP. Value: atm - ATM (Pay-easy) |
payment_type.payment_expiry_duration number(2) (optional) |
This indicates the number of days from getting payment_key , after which payment cannot be made. Maximum value: 60 (Default: 60) |
payment_type.payment_expiry_date string(8) (optional) |
Payment expiration date. (YYYYMMDD format) This date cannot exceed the maximum value of duration for payment_expiry_duration . |
contents string(12) (required) |
Text that can be displayed in the ATM screen should be provided here. |
contents_kana string(24) (required) |
Text that can be displayed in the ATM screen should be provided here. Full width Katakana characters are allowed. |
Customer email Parameters
{
"email" : {
"customer_name" : "スミス ジョン",
"customer_email_address" : "smith.john@example.com"
}
}
The following parameters are specific to the Customer email notification.
Parameter | Description |
---|---|
customer_name string(256) (optional) |
The name of the customer or recipient that will appear in the email if it is provided. Full width or half width characters are allowed for this parameter. |
customer_email_address string(256) (optional) |
Customer email notification will be sent to this address. |
Items Details
{
"items" : [
{
"id" : "ITEM-0001",
"name" : "ITEM 1 NAME",
"price" : 10000,
"quantity" : 1
},
{
"id" : "ITEM-0002",
"name" : "ITEM 2 NAME",
"price" : 10000,
"quantity" : 2
}
]
}
Multiple items can be added with the following parameters. The quantity
and price
parameters are used for calculating the gross_amount
value.
Parameter | Description |
---|---|
id string(20) (required) |
Unique item ID in each order |
name string(200) (required) |
Name of the item. Full width or half width characters are allowed for this parameter. |
price number(8) (required) |
Unit price of the item. |
quantity number(9) (required) |
Order quantity 0 is not allowed i.e. quantity must be greater than 0 |
Custom Message Parameters
{
"custom_message" : {
"show_items_additional_message" : true,
"items_additional_message" : "[*] サンプルメッセージ"
}
}
The following parameters can be used to give any additional message about the items in the order.
Parameter | Description |
---|---|
show_items_additional_message boolean (optional) |
Flag to decide whether to display the product custom message on the POP client and in the notification email. If it is not set, POP uses the “Show Items Additional Message” setting in the “System Settings” tab of POP Settings in MAP. Values: true or false |
items_additional_message string(200) (optional) |
If items parameter is not set then the custom message is not displayed on the POP Client and in the notification email. If it is not set, POP uses the “Items Additional Message” setting in the “System Settings” tab of POP Settings in MAP.All half-width and full-width characters except control characters are allowed. |
Response
Response Parameters
Success Response
{
"payment_key" : "28GTzdVOZNeImaHMDeQF1319",
"result_code" : "R000",
"status" : "success",
"message" : "\"Payment Key\" has been generated successfully",
"payment_key_expiry_time" : "20200401000000"
}
Failure Response
{
"result_code" : "RC01",
"status" : "failure",
"message" : "Invalid \"Order ID\""
}
When the POP Server receives a request from the merchant server then it will respond with the following parameters.
Parameter | Description |
---|---|
payment_key string(24) (optional) |
The unique payment_key generated by POP Server for a request.In case there is an error, then this parameter value is not returned. |
result_code string(4) (required) |
Four character result code that indicates success or the specific reason for failure. Result Codes |
status string(7) (required) |
Status of the request. Values: success or failure |
message string(256) (required) |
Message elaborating the status and result. |
payment_key_expiry_time string(14) (optional) |
Date and time when the payment_key will expire. (YYYYMMDDhhmmss format)In case there is an error, then this parameter value is not returned. |
HTTP Status Codes
POP returns following HTTP status codes in the Response.
Status Code | Description |
---|---|
201 Created |
The request for key was successful. |
400 Bad Request |
Request parameters validation failure. Refer to result_code and message of Response Parameters for the failure reason. |
401 Unauthorized |
Authorization of the merchant failed. |
500 Internal Server Error |
Internal error on the POP Server due one or more reasons. |
Client Integration
The goal of Client Integration is to show the POP payment page within the merchant’s site. The POP Client is loaded in the customer’s browser and communicates with the POP Server. Once loaded in the customer’s browser, POP Client will take the customer through the complete payment process.
Steps to integrate POP Client
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
<script type="text/javascript"
src="<pop.js URL>"
data-client-key="<POP_CLIENT_KEY>">
</script>
</head>
<body>
<input type="button"
id="pay-button"
class="btn"
value="Pay">
<script type="text/javascript">
var options = {};
var payButton = document.getElementById('pay-button');
payButton.addEventListener('click', function() {
pop.pay("<payment-key>", options);
});
</script>
</body>
</html>
The POP Client integration starts after the payment_key
is received from the POP Server from the Merchant server integration.
- Include the
pop.js
in the page that will be returned to the browser after thepayment_key
is received from POP Server. - The
POP_CLIENT_KEY
that was received from the MAP(Merchant Administration Portal) should be set as the value ofdata-client-key
attribute of thepop.js
script tag. - The payment process will start when the
pop.pay
function is called with thepayment_key
provided as parameter.
POP JS
POP JS provides four public functions: pay
, accountManagement
, show
and hide
pop.js
Location
https://pay3.veritrans.co.jp/pop/v1/javascripts/pop.js
pay(paymentKey, options)
This function is called to start the POP payment page.
Parameters:
Name | Description |
---|---|
paymentKey string (required) |
This is the payment_key received from POP Server in the Merchant Server Integration |
options.onSuccess function (optional) |
Success callback function. This will override the success_url set in request |
options.onFailure function (optional) |
Failure callback function. This will override the failure_url set in request |
options.onIncomplete function (optional) |
Incomplete callback function. This will override the incomplete_url set in request |
options.skipOrderSummary boolean (optional) |
If this is true then the Order Summary screen will not be displayed. Values: true or false (Default: false ) |
options.autoReturn boolean (optional) |
This flag decides if the payment completion screen in the POP Client is closed automatically. true : The completion screen will be closed automatically after the number of seconds provided in autoReturnDelay . false : The completion screen will not be closed automatically. Values: true or false (Default: false ) |
options.autoReturnDelay number (optional) |
The delay, in seconds, before the completion screen is closed automatically. This value will be applied only when autoReturn = true . (Default: 0 i.e. the completion screen will close immediately) |
options.language string (optional) |
Language of the POP Client. Supported values are en , ja and zh . (Default: ja ) |
onSuccess
, onFailure
and onIncomplete
functions should accept one parameter - Transaction Result
accountManagement(account_mgmt_key, options)
This function displays the POP Client’s Account Management screen.
Name | Description |
---|---|
account_mgmt_key string (required) |
This is the account_mgmt_key received from POP Server in the Manage PayNowID - Merchant Server Integration |
options.language string (optional) |
Language of the POP Client. Supported values are en , ja and zh . (Default: ja ) |
show()
Show POP Client loading page.
This is a helper function to show instant loading feedback while getting payment_key
using AJAX.
On AJAX success, pop.pay()
is called to continue the payment process. Otherwise, pop.hide()
is called to end loading page.
hide()
Hide the active POP Client page.
This is a complementary function of pop.show()
and is used if pop.show()
is used to show instant loading feedback while getting payment_key
using AJAX.
function ajaxGetPaymentKey(transactionData, callback) {
var paymentKey;
// Request merchant server to get the Payment Key & save result to paymentKey variable
if (paymentKey) { // Payment Key received successfully
callback(null, paymentKey);
} else { // Show error message
callback(new Error('Failed to fetch Payment Key'), null);
}
}
// This code is called on the button-click event for the Pay button on the merchant's on-line shop
payButton.onclick(function() {
pop.show();
ajaxGetPaymentKey(transactionData, function(error, paymentKey) {
if (error) {
pop.hide();
} else {
pop.pay(paymentKey);
}
});
});
JS Callback
pop.pay(payment_key, {
onSuccess: function(result){console.log('success');console.log(result);},
onFailure: function(result){console.log('failure');console.log(result);},
onIncomplete: function(result){console.log('incomplete');console.log(result);}
})
pop.js
provides the pop.pay()
function that allows the merchant to provide callback functions that will be called based on the status
in the posted message.
These callback functions are given precedence over the URLs provided in the request.
The result
object returned is the same as Transaction Status Through Redirection.
Transaction Status
The POP Server provides the transaction status to the Merchant via various means.
- Redirection to the URL provided by the Merchant
- Confirmation on MAP(Merchant Administration Portal)
Transaction Status Through Redirection
After the POP Client is closed, the following parameters are posted to the appropriate URL provided by the Merchant (either one of success_url
or failure_url
described in the Request section.).
These parameters are given as a query string in the name1=value1&name2=value2 format in the message body of the POST request on the merchant’s redirection URL.
There are different parameters for different payment types with a few being common to all.
Refer to the Handling Notifications section for details about how to verify the notification.
Common Parameters
Parameter | Description |
---|---|
merchant_id string(22) (required) |
Merchant ID. |
order_id string(100) (required) |
Order ID from the request. |
status string(10) (required) |
The transaction status. Values: success or failure |
result_code string(4) (required) |
Four character that indicates success or the specific reason for failure . Result Codes |
m_status string(10) (optional) |
Transaction status from Payment Gateway. In case there is an error before request is sent to the Payment Gateway, then this parameter value is not returned. Values: success , failure or pending |
v_result_code string(16) (optional) |
Result Code from Payment Gateway. In case there is an error before request is sent to the Payment Gateway, then this parameter value is not returned. List of the Payment Gateway result codes(*) can be found here. * Document name (Japanese only): “結果コード一覧” |
payment_type string(15) (optional) |
This parameter indicates the payment type that was selected by the customer. Values: card , mpi or cvs |
transaction_datetime string(14) (optional) |
Transaction Date and time, returned by Payment Gateway. (Follows YYYYMMDDhhmmss format) |
dummy boolean (required) |
The dummy flag that was set in request or the default that was applied if the parameter was not set. Values: true or false |
signature string(128) (required) |
Signature derived as explained in Handling Notifications. |
Card Parameters
Besides the Common Parameters these parameters are returned for Card payment type.
Parameter | Description |
---|---|
acquirer_code string(2) (optional) |
Acquirer Code returned by Payment Gateway. |
auth_code string(7) (optional) |
Authorization Code returned by Payment Gateway. |
masked_card_number string(20) (optional) |
Masked credit card number used in the transaction, returned by Payment Gateway. The card number is returned in the format 000000*00 (First 6 and last 2 digits are retained, the rest are replaced with a single asterisk ‘*’). |
Convenience Store Parameters
Besides the Common Parameters these parameters are returned for Convenience Store payment type.
Parameter | Description |
---|---|
result_type string (optional) |
This parameter is returned only for Convenience Store payment type and will indicate the type of the result being given in the redirection or Push Notification. Value: applied - This value indicates that the transaction has been initiated and customer’s payment at a convenience store is awaited. |
payment_sub_type string(5) (optional) |
This parameter is returned only for Convenience Store payment type and indicates the store chosen by customer. Values: sej - 7-Elevenlawson - Any of Lawson, MINISTOP or Seicomartfamima - FamilyMartecon - Any of Lawson, FamilyMart, Seicomart or MINISTOPother - Daily YAMAZAKI |
receipt_number string(32) (optional) |
This is the receipt number/ reference number returned by the convenience store and is to be used by the customer for making the payment at the store. |
haraikomi_url string(256) (optional) |
This URL presents a printable receipt to the customer who can print it and take it to the convenience store for completing the payment. The URL is returned in case of sej and other stores. It is not returned for econ . |
Bank Parameters
Besides the Common Parameters these parameters are returned for Bank payment type.
Parameter | Description |
---|---|
result_type string (optional) |
This parameter indicates the type of the result being given in the redirection or Push Notification. Value: applied - This value indicates that the transaction has been initiated and customer’s payment at an ATM is awaited. |
payment_sub_type string(5) (optional) |
This parameter indicates the Bank sub type. Value: atm - ATM (Pay-easy) |
agency_code string(8) (optional) |
This is the Receiving Agency Code. This is required when the consumer is making the payment. |
customer_no string(20) (optional) |
This is the Customer Number. This is required when the consumer is making the payment. |
confirm_no string(6) (optional) |
This is the Confirmation Number. This is required when the consumer is making the payment. |
PayNowID Parameters
If a PayNowID account was used in the transaction then the following additional parameters are returned.
Parameter | Description |
---|---|
paynow_account_id string(100) (optional) |
This parameter is returned if a PayNowID account was used for transaction. The ID of the account used is returned in the parameter. |
paynow_status string(10) (optional) |
The status of PayNowID operation done during the transaction. Values: success or failure |
MAP(Merchant Administration Portal) Transaction Status
The transaction status can be seen in the Transactions section of MAP(Merchant Administration Portal) by using the Order Search function.
Notifications
The POP Server provides the following asynchronous notifications to the Merchant Server.
Push Notification
The POP Server notifies the Merchant Server about the status of a transaction by sending a notification on the push_url
sent in the request.
These parameters are given as JSON in the message body of the POST request on the merchant’s push_url
.
Refer to the Handling Notifications section for details about how to verify the request received on the push_url
.
Push Notification parameters are similar to the parameters in Transaction Status Through Redirection, with a few differences. Here too there are a few common parameters and different parameters for different payment types.
Common Parameters
Refer to Redirection Common Parameters for list of parameters.
Card Parameters
Refer to Redirection Card Parameters for list of parameters.
Card Parameters - Fraud Detection
Please contact VeriTrans for details on the fraud detection feature.
Card Parameters - PayNowID
Refer to Redirection PayNowID Parameters for details about additional parameters in the Push Notification when PayNowID account is used in payment.
And, when card information is registered and used, the following parameter is additionally returned.
Parameter | Description |
---|---|
card_id string(100) (optional) |
Card ID of the card information linked to PayNow Account ID. This is returned only if the “Card ID” checkbox in the “Card Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
Convenience Store Parameters
Since Convenience Store payments have two steps, POP will give two Push notifications to the Merchant.
1. Push Notification on Initiating Payment: The payment is initiated when the customer is given the receipt_number
and haraikomi_url
for making the payment at a convenience store.
2. Push Notification on Completing Payment: The customer completes the payment at a convenience store.
Push Notification on Initiating Payment
Parameter | Description |
---|---|
result_type string (required) |
This parameter is returned only for Convenience Store payment type and will indicate the type of the result being given in Redirection or Push Notification. Value: applied - This value indicates that the transaction has been initiated and customer’s payment at a convenience store is awaited. |
payment_sub_type string(5) (required) |
This parameter is returned only for Convenience Store payment type and indicates the store chosen by customer. Values: sej - 7-Elevenlawson - Any of Lawson, MINISTOP or Seicomartfamima - FamilyMartecon - Any of Lawson, FamilyMart, Seicomart or MINISTOPother - Daily YAMAZAKI |
receipt_number string(32) (optional) |
This is the receipt number/ reference number returned by the convenience store and is to be used by the customer for making the payment at the store. |
haraikomi_url string(256) (optional) |
This URL presents a printable receipt to the customer who can print it and take it to the convenience store for completing the payment. The URL is returned in case of sej and other stores. It is not returned for econ . |
first_name string(20) (optional) |
The name entered by the consumer on the POP client. This is returned only if the “Name” checkbox in the “CVS Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
last_name string(20) (optional) |
Last name entered by the consumer on the POP client. This is returned only if the “Name” checkbox in the “CVS Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
telephoneno string(11) (optional) |
The phone number entered by the consumer on the POP client. This is returned only if the “Phone Number” checkbox in the “CVS Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
Push Notification on Completing Payment
Parameter | Description |
---|---|
result_type string (required) |
This parameter is returned only for Convenience Store payment type and will indicate the type of the result being given in Redirection or Push Notification. Value: paid - This value indicates that the payment has been completed by the customer at a convenience store. |
payment_sub_type string(5) (required) |
This parameter is returned only for Convenience Store payment type and indicates the store chosen by customer. Values: sej - 7-Elevenlawson - Any of Lawson, MINISTOP or Seicomartfamima - FamilyMartecon - Any of Lawson, FamilyMart, Seicomart or MINISTOPother - Daily YAMAZAKI |
receipt_number string(32) (required) |
This is the receipt number/ reference number that was returned in the first notification and was used by the customer for making the payment at the store. |
cvs_type string(10) (required) |
This value indicates the store type in which the payment was made. It is returned if the customer has completed the payment successfully. Values: sej - 7-Elevenecon-lw - Lawsonecon-fm - FamilyMartecon-mini - MINISTOPecon-other - Seicomartother - Other (Daily YAMAZAKI) |
received_amount string(6) (required) |
This is the actual amount paid by customer at the convenience store. |
Bank Parameters
Since Bank payments have two steps, POP will give two Push notifications to the Merchant.
1. Push Notification on Initiating Payment: The payment is initiated when the customer is given the agency_code
, customer_no
and confirm_no
for making the payment at an ATM.
2. Push Notification on Completing Payment: The customer completes the payment at an ATM.
Push Notification on Initiating Payment
Parameter | Description |
---|---|
result_type string (required) |
This parameter indicates the type of the result being given in Redirection or Push Notification. Value: applied - This value indicates that the transaction has been initiated and customer’s payment at an ATM is awaited. |
payment_sub_type string(5) (required) |
This parameter indicates the Bank sub type. Value: atm - ATM (Pay-easy) |
agency_code string(8) (optional) |
This is the Receiving Agency Code. This is required when the consumer is making the payment. |
customer_no string(20) (optional) |
This is the Customer Number. This is required when the consumer is making the payment. |
confirm_no string(6) (optional) |
This is the Confirmation Number. This is required when the consumer is making the payment. |
first_name string(20) (optional) |
First Name entered by the consumer on the POP client. This is returned only if the “Name” checkbox in the “Bank Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
last_name string(20) (optional) |
Last Name entered by the consumer on the POP client. This is returned only if the “Name” checkbox in the “Bank Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
first_name_kana string(20) (optional) |
First Name (Kana) entered by the consumer on the POP client. This is returned only if the “Name” checkbox in the “Bank Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
last_name_kana string(20) (optional) |
Last Name (Kana) entered by the consumer on the POP client. This is returned only if the “Name” checkbox in the “Bank Information - Push Notification Additional Information” section of the “System Settings” tab in POP Settings is checked. |
Push Notification on Completing Payment
Parameter | Description |
---|---|
result_type string (required) |
This parameter indicates the type of the result being given in the Redirection or Push Notification. Value: paid - This value indicates that the transaction has been completed at an ATM. |
payment_sub_type string(5) (required) |
This parameter indicates the Bank sub type which is only ATM at present. Values: atm - ATM (Pay-easy) |
transaction_datetime string(14) (required) |
Transaction Date and time when the payment was made, returned by Payment Gateway. (YYYYMMDDhhmm format) |
received_amount string(10) (required) |
This is the actual amount paid by customer at the ATM. |
agency_code string(8) (required) |
This is the Receiving Agency Code. |
customer_no string(20) (required) |
This is the Customer Number. |
confirm_no string(6) (required) |
This is the Confirmation Number. |
company_code string(5) (required) |
This is the Receiving Company Code. |
Email Notification
The POP Server notifies the Merchant and Customer about the status of a transaction by sending an email.
Merchant email notification
When Merchant email feature is enabled and Merchant’s email address is registered, POP sends email at the following timing for each settlement regardless of the settlement result.
For Card payment - POP will send one email for either success
or failure
result.
For CVS payment and Bank payment - POP will send two emails
1. When payment is initiated with either success
or failure
result.
2. When payment is completed.
Customer email notification
When Customer email feature is enabled and customer_email_address
in the Request is set, POP sends email at the following timing for each settlement only when settlement is successful.
For Card payment - POP will send one email if transaction is successful.
For CVS payment and Bank payment - POP will send two emails.
1. After payment is initiated successfully.
2. After payment is completed successfully.
The customer email address registered in “System Settings” tab of POP Settings in the MAP is set in “from” of the email to customer, but the email is sent from our company domain (veritrans.co.jp). If the sender domain and the sender email address domain are different, and if the recipient of the email is taking measures against spoofed email, then email reception may be rejected.
To prevent email reception from being rejected, please take the following measure.
Add the SPF record to the DNS of the domain specified as the sender’s email address and register the VeriTrans mail server information “cvs.veritrans.co.jp” in the SPF record.
For taking this measure, please consult your domain network administrator.
Handling Notifications
// Step 1 - Read all the parameters and their values
// Step 2 - Sort all the parameters in alphabetical order,
// skip the signature parameter
// Step 3 - Construct an input string using <parameter name>=<value> format
// and appending the POP_SERVER_KEY preceded by ':'.
// Use "true" or "false" string as value for boolean parameter(s).
inputString = ( name1=value1&name2=value2&...&nameN=valueN )
+ ":" + POP_SERVER_KEY;
// Step 4 - Derive the signature using SHA512 hash function
signature = SHA512( inputString );
// Step 5 - Compare the signature received in the notification
// with the signature derived from the received parameters
POP Server adds a signature
as the last parameter in both Transaction Status Through Redirection as well as Push Notifications.
The signature
is derived from the parameters and their values in the notification.
The Merchant Server has to derive a signature using the same logic and compare with the signature
received from POP Server. If both the signatures match then and only then should the Merchant Server process further.
Payment Link
In addition to the normal POP Client, POP also provides a feature for generating a link URL for launching the payment screen. The EC site can send the acquired URL to the consumer using e-mail or SMS message etc., and can lead the consumer to the payment screen that can launch the POP Client. In this feature redirection and POP JS cannot be used. The payment link feature can be used from MAP (Merchant Administration Portal).
Endpoint
Payment Link
https://pay3.veritrans.co.jp/pop/v1/link-pay
Request
HTTP Method
POST
Request Headers
Refer to section Request Headers for details of the headers to be set in the request.
Request parameters
All the parameters in the request, described in the Merchant Server Integration section, are used except the following.
success_url
failure_url
incomplete_url
Response
In response to a valid request, POP returns the following parameters in addition to the response parameters. For the result code returned by POP when the request fails, see Result Code.
Success Response
{
"payment_key" : "28GTzdVOZNeImaHMDeQF1319",
"result_code" : "R000",
"status" : "success",
"message" : "\"Payment Key\" has been generated successfully",
"payment_key_expiry_time" : "20200401000000",
"pay_link_url" : "https://pay3.veritrans.co.jp/pop/v1/payment-link?payment_key=28GTzdVOZNeImaHMDeQF1319&client_key=client101"
}
Failure Response
{
"result_code" : "RC01",
"status" : "failure",
"message" : "Invalid \"Order ID\""
}
Parameter | Description |
---|---|
pay_link_url string(256) (optional) |
Payment Link URL generated by POP Server. In case there is an error, then this parameter value is not returned. |
HTTP Status Codes
Refer to HTTP Status Codes for the status codes set in the response from POP Server.
Managing PayNowID
Individual customers can manage the card information stored in their account using the PayNowID Account Management feature.
This is implemented by using a mechanism that is similar to POP integration for payment transactions. Refer to the following sections Getting Started, Merchant Server Integration and Client Integration.
※ Contract for PayNowID is required separately.
Steps to integrate
- User chooses to open the PayNowID Account Management screen.
- Merchant server makes an API request to the POP Server to get the
account_mgmt_key
. - POP Server responds to the API call with the
account_mgmt_key
. - Merchant server constructs the html page and sends it back to the browser.
- The html file submits and calls
pop.accountManagement(<account_mgmt_key>, options)
. User then manages the PayNowID account from the screen displayed in the browser.
Merchant Server Integration
The merchant server sends a request to the POP Server to get the account_mgmt_key
. The account_mgmt_key
returned by the POP Server is used in the Managing PayNowID - Client Integration.
エンドポイント
Account Management Key
https://pay3.veritrans.co.jp/pop/v1/paynow-acctmgmt-key
Request
HTTP Method
POST
Request Headers
Refer to section Request Headers for details of the headers to be set in the request.
Request Parameters
{
"paynow_account_id" : "TEST-ACCOUNT-101",
"dummy" : true,
"account_mgmt_key_expiry_duration" : 1440
}
The request body will have these following parameters.
Parameter | Description |
---|---|
paynow_account_id string(100) (required) |
This is the unique account ID registered as PayNowID. This account ID is unique to individual customers. If the Payment Gateway does not find an account with this ID and the customer saves a card then it creates a new account. |
dummy boolean (optional) |
This flag is set to use PayNowID Account Management feature for a dummy account. A dummy account should be used to test the integration with the VeriTrans. Values: true or false (Default: false ) |
account_mgmt_key_expiry_duration number(6) (optional) |
Specifies the validity period in minutes after the account_mgmt_key is generated until it becomes unusable.Maximum value: 129600 (Default: 1440) |
Response
The POP Server responds to a valid request with the account_mgmt_key
that is needed for client integration.
Refer to section Result Codes for the various result codes returned by POP Server in case of failure.
Response Parameters
Success Response
{
"account_mgmt_key" : "uxhn7T0eWt22XHycTNr11702",
"result_code" : "R000",
"status" : "success",
"message" : "Success",
"account_mgmt_key_expiry_time" : "20200401000000"
}
Failure Response
{
"result_code" : "RC2B",
"status" : "failure",
"message" : "Invalid value for \"Account Management Key Expiry Duration\""
}
Parameter | Description |
---|---|
account_mgmt_key string(24) (optional) |
The unique account_mgmt_key generated by POP Server for a request.In case there is an error, then this parameter value is not returned. |
result_code string(4) (required) |
4 character result code that indicates success or the specific reason for failure. Result Codes |
status string(7) (required) |
Status of the request. Values: success or failure |
message string(256) (required) |
Message elaborating the status and result. |
account_mgmt_key_expiry_time string(14) (optional) |
Date and time when the account_mgmt_key will expire. (YYYYMMDDhhmmss format)In case there is an error, then this parameter value is not returned. |
HTTP Status Codes
Refer to HTTP Status Codes for the status codes set in the response from POP Server.
Client Integration
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
<script type="text/javascript"
src="<pop.js URL>"
data-client-key="<POP_CLIENT_KEY>">
</script>
</head>
<body>
<input type="button"
id="manage-paynowid-button"
class="btn"
value="Managing PayNowID">
<script type="text/javascript">
var options = {};
var managePayNowIDButton = document.getElementById('manage-paynowid-button');
managePayNowIDButton.addEventListener('click', function() {
pop.accountManagement("<account_mgmt_key>", options);
});
</script>
</body>
</html>
The PayNowID Management integration starts after the account_mgmt_key
is received from the POP Server after the Managing PayNowID - Merchant Server Integration.
- Include the
pop.js
in the page that will be returned to the browser after theaccount_mgmt_key
is received from POP Server. - The
POP_CLIENT_KEY
that was received from the MAP(Merchant Administration Portal) should be set as the value ofdata-client-key
attribute of thepop.js
script tag. - The PayNowID Account Management screen will load when the
pop.accountManagement
function is called with theaccount_mgmt_key
provided as parameter.
Testing POP
The POP_SERVER_KEY
and POP_CLIENT_KEY
, exclusively set for the merchant, can be used to test by setting dummy
value to true
in the request.
POP also provides a common test account for testing purposes.
To use the common test account, please download the “Test Usage Information Notification”.
Test Usage Information Notification(*) can be found here.
* Document name (Japanese only): “テスト利用情報通知書”
The “Test Usage Information Notification” also has the MAP login related information for the common test account.
In addition to the above, please refer to the preparation section.
Testing For Each Payment
Merchant should execute the following tests to check if the integration with POP is successful. If all these test cases pass then the Merchant is ready to go live.
Merchant Server Integration Tests
Test Case | Expected Result |
---|---|
Request Payment Key from POP Server | POP Server returns a valid Payment Key |
Client Integration Tests
Test Case | Expected Result |
---|---|
Load the HTML from Steps to integrate POP Client | POP payment screen is displayed in the browser |
Transaction Status
Test Case | Expected Result |
---|---|
Test redirection to success_url |
After a successful transaction POP should redirect to the success URL provided in the request with proper parameters defined in Transaction Status Through Redirection |
Test redirection to failure_url |
After a failed transaction POP should redirect to the failure URL provided in the request with proper parameters defined in Transaction Status Through Redirection |
Test redirection to incomplete_url |
After POP screen is closed in the middle of a transaction and payment is incomplete, POP should redirect to the incomplete URL provided in the request with proper parameters defined in Transaction Status Through Redirection |
Test if transaction is updated in MAP | After a dummy transaction is completed then it should get displayed in MAP |
Notifications
Test Case | Expected Result |
---|---|
Test the notification sent on push_url |
After a transaction is completed POP should send a notification to the Push URL provided in the request with proper parameters defined in Push Notification |
Test email notifications sent to configured email address | After successful and failed transactions check if emails is sent to the configured email address |
Credit Card
The Credit Card payment integration can be tested for transaction authorization and 3D Secure scenarios.
Card
Explanation to test method of credit card settlement.
Card Number
On setting the following test card number and arbitrary expiration date (except for some) and arbitrary security code, the success response is returned.
Please note that in case a real credit card used it will be an error.
If settlement is carried out using card (other than test card), then v_result_code
is AC09
.
When testing 3D Secure, please use the card number for 3D Secure instead of below mentioned card numbers.
Brand | Card Number |
---|---|
Visa | 4111111111111111 |
MasterCard | 5555555555554444 |
JCB | 3528000000000007 |
AMEX | 378282246310005 |
Diners | 36666666666660 |
Expiration Date
It is possible to set arbitrary expiration date (MM/YY). By entering the following expiration date together with the test card number, the error response is returned.
Expiration Date | vResultCode | Expiration Date | vResultCode |
---|---|---|---|
01/99 | AG33 |
09/99 | AG61 |
02/99 | AG41 |
10/99 | AG49 |
03/99 | AG64 |
11/99 | AG48 |
04/99 | AG39 |
12/99 | AG44 |
05/99 | AG45 |
01/98 | AG47 |
06/99 | AG70 |
02/98 | AG71 |
07/99 | AG46 |
03/98 | AG51 |
08/99 | AG72 |
Security Code
It is possible to set any 3 or 4 digits value.
3D Secure Transaction
In 3D Secure, the method for determining the authentication result (determining whether or not to make a card payment) differs depending on the type of personal authentication. Therefore, we have made it possible to test possible scenarios for each type of personal authentication (authentication success/deemed authentication success/authentication failure due to suspicion of fraud/authentication failure due to system failure, etc.).
We have prepared test card numbers for 3D Secure for each scenario. Depending on the card number, scenario tests such as 3D secure (identity authentication) success, failure, authentication failure, abnormal termination, etc. can be performed. The test card number for 3D Secure is listed in “B. List of codes by scenario” in the 3DS2.0 supplementary material. Please note that if you conduct a transaction with a card number that is not listed in “B. List of codes by scenario”, the v_result_code will be NH02.
Please download the 3DS2.0 supplementary material (B. List of codes by scenario) from here.
Convenience Store
The Convenience Store payment integration can be tested for success and failure scenarios.
Test Case | Expected Result |
---|---|
Test successful transactions using telephone numbers Specify first 2 digits of telephone number as 09 08 07 06 05 |
Transaction success |
Test failure transactions using telephone numbers Specify first 2 digits of telephone number as 00, 01, 02, 03, 04 |
Transaction failure |
Bank
In bank settlement, you can test for successful payment request and failed payment request.
Test Case | Expected Result |
---|---|
Bank settlement (success) The last digit of gross_amount is 0 |
The transaction is successful |
Bank settlement (failure) The last digit of gross_amount is other than 0 |
The transaction fails |
Going Live
Please use POP_SERVER_KEY
and POP_CLIENT_KEY
issued exclusively for Merchant, by VeriTrans.
To do test transaction, in request, set the value of dummy
to true
.
After sufficient testing, confirm that there is no problem in the operation, and just by setting set the value of dummy
to false
, the conversion is complete.
After setting value of dummy
to true
, the merchant can do dummy transactions at any time.
Additionally, it is not necessary to change the endpoint.
Result Codes
Various result codes are returned by the POP Server in the Merchant Server Integration and Client Integration steps.
The Client Integration result codes will be returned during redirection as well as push notification.
In addition you can also refer to the Payment Gateway result codes that are returned in the v_result_code
parameter in Transaction Status Through Redirection as well as push notification.
Common
These result codes are common and can be returned during any step of the integration.
Result Code | Description |
---|---|
R000 |
Successful transaction |
RA01 |
Application Error - if any unknown error has occurred on VeriTrans side |
RD01 |
Database Error - if there is a severe error in VeriTrans Database |
Merchant Server Integration
These are the possible result codes that will be received in the response during the Merchant Server Integration.
Result Code | Description |
---|---|
RC01 |
Invalid “Order ID” |
RC03 |
Invalid “Gross Amount” |
RC04 |
Invalid value for “Shipping Amount” |
RC06 |
Invalid value for “Enabled Payment Types” |
RC07 |
Invalid value for “Success URL” |
RC08 |
Invalid value for “Failure URL” |
RC09 |
Invalid value for “Incomplete URL” |
RC10 |
Invalid value for “Push URL” |
RC12 |
Invalid value for “Payment Key Expiry Duration” |
RC13 |
Invalid value for “Item - ID” |
RC14 |
Invalid value for “Item - Name” |
RC15 |
Invalid value for “Item - Price” |
RC16 |
Invalid value for “Item - Quantity” |
RC17 |
Authentication failed - Merchant authentication has failed |
RC19 |
Invalid value for “CVS - Payment Sub Type” |
RC20 |
Order already exists |
RC21 |
“Payment Type” is not in contract |
RC22 |
MPI cannot be used because there is no contract |
RC26 |
Invalid value for “Dummy” |
RC27 |
Invalid value for “Capture” |
RC28 |
Invalid value for “Card - MPI” |
RC29 |
Duplicate “Enabled Payment Types” |
RC30 |
“Media Type” is not supported |
RC31 |
Required parameter(s) not present |
RC32 |
GET method is not supported |
RC33 |
Invalid “Order Items List” |
RC43 |
Invalid JSON string |
RC44 |
“Dummy” should be “true” for test merchant |
RC46 |
Invalid value for “CVS - Payment Expiry Duration” |
RC50 |
“CVS - Payment Sub Type” is not in contract |
RC51 |
Duplicate “CVS - Payment Sub Type” |
RC5E |
Invalid value for “CVS - Payment Expiry Date” |
RC5F |
“CVS - Payment Expiry Duration” and “CVS - Payment Expiry Date” both can’t be sent together |
RC0Y |
Invalid value for “Enable Fraud Detection” |
RC2A |
Invalid “PayNow Account ID” |
RC2B |
Invalid value for “Account Management Key Expiry Duration” |
RC2D |
Invalid value for “Save Card” |
RC2E |
Invalid value for “Skip Card Selection” |
RC2N |
“PayNow Account ID” is required if “Save Card” or “Skip Card Selection” is present |
RC5A |
Invalid value for “Customer Email Address” |
RC5B |
Invalid value for “Customer Name” |
RC1L |
“Bank - Payment Subtype” is not in contract |
RC1M |
Invalid value for “Bank - Payment Expiry Duration” |
RC1N |
Invalid value for “Bank - Payment Subtype” |
RC1O |
Duplicate “Bank - Payment Subtype” |
RC1R |
Invalid value for “Bank - Contents” |
RC1S |
Invalid value for “Bank - Kana contents” |
RC1V |
Invalid value for “Bank - Payment Expiry Date” |
RC1W |
“Bank - Payment Expiry Duration” and “Bank - Payment Expiry Date” both can’t be sent together |
RC1X |
Invalid value for “CVS - Payment Expiry HHMM” |
RC5G |
Invalid value for “Custom Message - Show Items Additional Message” |
RC5H |
Invalid value for “Custom Message - Items Additional Message” |
RC5J |
Invalid value for “Card - 3D Secure Version” |
RC5M |
Invalid value for “Cardholder Email Address” |
RC5N |
Invalid value for “Cardholder Home Phone Number” |
RC5O |
Invalid value for “Cardholder Mobile Phone Number” |
RC5P |
Invalid value for “Cardholder Work Phone Number” |
RC5Q |
Invalid value for “Cardholder Home Phone Number Country Code” |
RC5R |
Invalid value for “Cardholder Mobile Phone Number Country Code” |
RC5S |
Invalid value for “Cardholder Work Phone Number Country Code” |
Client Integration
These result codes are returned in the Client Integration step.
Result Code | Description |
---|---|
RC17 |
Authentication failed - Due to invalid POP_CLIENT_KEY |
RC18 |
Invalid “Payment Key” |
RC25 |
Invalid “Payment Key” status - this will happen if there is a POP Client request that does not match the current status of the order |
RC34 |
“Payment Key” has expired |
RC5C |
It occurs when not enough time to do 3D Secure Authentication. This will happen when 3D Secure Authentication is enabled and the ‘payment_key’ expiry duration is valid for less than a minute, at the time of sending the payment details by POP JS |
RT01 |
Failed to get credit card token |
RM01 |
Gateway error - Error at the Payment Gateway |
RM03 |
MDK error - Error while sending request from POP to Payment Gateway. |
FAQ
FAQ(*) can be found here.
*Section name(Japanese only): “POP(4G)” under “接続方式”
Changelog
v1.8.1
April 09, 2025
Added card_id
parameter in section of “Card Parameters - PayNowID” section of “Push Notification” section of “Notifications”.
v1.8
May 29, 2024
Added information regarding 3D Secure (identity authentication) in Card Parameters section of “Request” in “Merchant Server Integration”.
- Added a note to the
mpi
parameter description. - Added
cardholderEmail
,cardholderHomePhoneNumber
,cardholderHomePhoneNumberCountry
,cardholderMobilePhoneNumber
,cardholderMobilePhoneNumberCountry
,cardholderWorkPhoneNumber
,cardholderWorkPhoneNumberCountry
parameters.
Updated result codes
- Added
RC5M
,RC5N
,RC5O
,RC5P
,RC5Q
,RC5R
,RC5S
.
v1.7.6
March 13, 2024
Updated length of the auth_code
in “Card Parameters” in “Transaction Status Through Redirection” under section of “Transaction Status”.
Deleted “step2a” from the procedure in “Handling Notifications” section of “Notifications”.
Added warning note in Endpoint
section of “Payment Link”.
Updated the “src” tag of the sample code described in Steps to integrate POP Client
of “Client Integration” and Client Integration
of “Managing PayNowID”.
Added explanation in Card Number
of “Credit Card” under section of “Testing POP”.
Added explanation about scenario in 3D Secure Transaction
of “Credit Card” under section of “Testing POP”.
Updated the connection domain to pay3.veritrans.co.jp
.
- “Payment Key” in Endpoint section of “Merchant Server Integration”.
- “pop.js Location” in POP JS section of “Client Integration”.
- “Payment Link” in Endpoint section of “Payment Link”.
- “pay_link_url” in Response sample code section of “Payment Link”.
- “Account Management Key” in Merchant Server Integration section of “Managing PayNowID”.
Updated the domain destination link of MAP(Merchant Administration Portal) to admin3.veritrans.co.jp
.
v1.7.5
July 05, 2023
Added the description of payment_key_expiry_duration
in “Request” section of “Merchant Server Integration”.
Added following descriptions about convenience store payment in “Request” section of “Merchant Server Integration”.
- Added default value and maximum limit value for
lawson
andfamima
forpayment_expiry_duration
. - Added a
payment_expiry_hhmm
parameter.
v1.7.4
November 24, 2022
Updated the description of incomplete_url
in “Request” section of “Merchant Server Integration”.
Added options lawson
and famima
in Convenience Store payment type.
- Updated the description of Convenience Store Parameters in “Request” section of “Merchant Server Integration”.
- Updated the description of Convenience Store Parameters in “Transaction Status Through Redirection” section of “Transaction Status”
- Updated the description of Push Notification on Initiating Payment, Push Notification on Completing Payment in “PUSH notification” section of “Notifications”
v1.7.3
October 25, 2021
Added description of 3ds_version
parameter in Card Parameters in “Request” section of “Merchant Server Integration”.
Added the description about sending the PUSH retry over notification function on next day to the supplementary information to “Push Notification” section of “Notifications”.
Removed the description related to enable_fraud_detection
parameter due to the termination of Aegis service.
Added result codes for 3ds_version
.
Updated description for RM03
result codes.
The result_type
parameter of “Push Notification on Initiating Payment” section of “Convenience Store Parameters” section of “Push Notification” section of “Notifications”, changed from optional to required.
v1.7.2
December 15, 2020
Added the description about the countermeasure against spoofing of email to “Email notification” section of “Notifications”.
v1.7.1
August 04, 2020
Updated description of payment_expiry_duration
parameter in Convenience Store Parameters and Bank Parameters in “Request” section of “Merchant Server Integration”.
v1.7
January 20, 2020
Added description of Bank settlement.
Added description of Payment Link feature.
Added description of Custom Message parameters.
Added following descriptions about convenience store payment.
- Added
payment_expiry_date
to the request. - Added description to parameters in PUSH Notification section:
first_name
,last_name
andtelephoneno
.
Changed supporting TLS versions.
v1.6
March 27, 2019
Added description of the parameter payment_key_expiry_duration
and account_mgmt_key_expiry_duration
that set the expiration date of payment_key
and account_mgmt_key
respectively.
Added result codes for payment_key_expiry_duration
and account_mgmt_key_expiry_duration
validation.
Added description of PUSH notification retry over notification e-mail function.
Added description about Ad-blocker extension.
Added desription about Payment through link.
v1.5
July 12, 2018
Fraud detection can now be performed when using 3D secure (user authentication).
The description on fraud detection has been updated.
- Updated description of
enable_fraud_detection
in “Request” section of “Merchant Server Integration”. - Updated the description of Card Parameters - Fraud Detection in “Push Notification” section of “Notification”.
v1.4
May 18, 2018
Email to customer implemented in POP API.
Added FAQ section.
Updated link of MAP(Merchant Administration Portal).
Added HTTP status codes for Merchant Server Integration
v1.3
December 21, 2017
POP API released with PayNowID support in Card Payment.
PayNowID Management API released.
v1.2
August 31, 2017
POP API released with Fraud Detection support in Card Payment.
v1.1
July 27, 2017
POP API released with Convenience Store support.
pop.js
Location has been changed.
v1.0
March 31, 2017
Initial release of POP API with Card Payment support.