Getting Started
Overview
For the Card Registration feature, a small (2 yen) transaction is made to confirm the validity of the credit card and register it.
The card information is linked to the order ID specified when using this function.
In addition, by specifying the PayNowID account ID when using this function, the card information is linked to the specified account ID.
The card information linked to the order ID and account ID can be used for settlement by using the MDK or MAP(Merchant Administration Portal).
- Customer performs the register operation.
- Merchant server sends an API request to the POP server to get the
payment_key
.- POP Server responds with the
payment_key
.- Merchant server constructs the html page and sends it back to the customer’s browser.
- Merchant’s JavaScript code calls
pop.pay(payment_key, options)
. Customer then fills up the card details and clicks the register button. POP JS sends the card details to the POP Server.- POP Server processes the details and responds with the registration 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 registration status.
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.
Endpoint
Payment Key
https://pay3.veritrans.co.jp/pop/v1/register-card
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.
POP_SERVER_KEY
can be obtained from MAP’s 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"
}
Request with all parameters
{
"order_id": "ORDER-0001",
"dummy": 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",
"card": {
"mpi": false,
"paynow_account_id": "TEST-ACCOUNT-101"
},
"email": {
"customer_name": "スミス ジョン",
"customer_email_address": "smith.john@example.com"
}
}
The request body will have the 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. |
dummy boolean (optional) |
This flag is set to decide if the request is dummy. A dummy request will not go through the actual registration 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 card registration is completed successfully. If this is not provided then POP will use “Success URL” value set in “System Settings” tab of POP Settings. |
failure_url string(256) (optional) |
POP will redirect the customer to this URL if the card registration fails. If this is not provided then POP will use “Failure URL” value set in “System Settings” tab of POP Settings. |
incomplete_url string(256) (optional) |
POP will redirect the customer to this URL if the registration 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. |
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. This URL is used in Push Notification. Notification is sent for both the statuses viz. success and failure |
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 Options |
This is a parameter that can be used to set parameters for card registration. |
email object (optional) Customer email |
JSON object to provide the name and email address of the customer doing the registration. |
Card Options
{
"card": {
"mpi": false,
"paynow_account_id": "TEST-ACCOUNT-101"
}
}
{
"card" : {
"mpi" : true,
"3ds_version" : "2",
"paynow_account_id" : "TEST-ACCOUNT-101",
"cardholderEmail" : "smith.john@example.com",
"cardholderHomePhoneNumber" : "0312345678",
"cardholderHomePhoneNumberCountry" : "81",
"cardholderMobilePhoneNumber" : "08012345678",
"cardholderMobilePhoneNumberCountry" : "81",
"cardholderWorkPhoneNumber" : "08012345678",
"cardholderWorkPhoneNumberCountry" : "81"
}
}
Parameter | Description |
---|---|
mpi boolean (optional) |
3-D Secure Authentication flag. If this is not provided then POP will use “Enable 3-D Secure” value set in “System Settings” tab of POP Settings. Values: true or false |
paynow_account_id string(100) (optional) |
A unique member ID for each customer. When the credit card transaction succeeds, the PayNowID account is newly created and linked with the card information entered. If you already have a PayNowID account, the card information entered will be linked to the account in addition. In either case, the newly associated card becomes the default card. ※ Contract for PayNowID is required separately. |
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 3-D Secure (user 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 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 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 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. |
Customer email
{
"email": {
"customer_name": "スミス ジョン",
"customer_email_address": "smith.john@example.com"
}
}
The following options are specific for 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. |
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) |
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. |
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
Similar to the normal payment flow, pop.pay
function is called from browser, with payment_key
obtained from POP Server as a parameter.
A screen dedicated to the card registration function is displayed on top of the merchant EC application.
Registration Result
The registration result is delivered similar to transaction status of normal card payments, except in case of e-mail notifications, which are different for Card Registration.
For details, refer the “Transaction Status” and “Notifications” sections of the VeriTrans4G POP Development Guide here.
Registration Link
In addition to the normal POP Client, POP also provides a feature for generating a link URL for launching the registration 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 registration screen of the POP Client. In this feature redirection and POP JS cannot be used. The registration link feature can be used from MAP(Merchant Administration Portal).
Endpoint
Registration Link
https://pay3.veritrans.co.jp/pop/v1/account-registration-link
Request
HTTP Method
POST
Request Headers
Refer to section Request Headers for details of the headers to be set in the request.
Request parameters
Except the following parameters, all other Request Parameters from Merchant Server Integration can be set.
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 codes returned by POP when the request fails, see Result Codes.
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/account-registration-link-pay?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) |
Registration 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.
Result Codes
Merchant Server Integration Result Codes
These are the possible result codes that will be received in the response described in the Merchant Server Integration or in the Registration Link - Response.
Result Code | Description |
---|---|
R000 |
Successful Card Registration |
RA01 |
Application Error - if any unknown error has occurred on VeriTrans side |
RD01 |
Database Error - if there is a severe error in VeriTrans Database |
RC01 |
Invalid “Order ID” |
RC07 |
Invalid value for “Success URL” |
RC08 |
Invalid value for “Failure URL” |
RC09 |
Invalid value for “Incomplete URL” |
RC10 |
Invalid value for “Push URL” |
RC17 |
Authentication failed - Merchant authentication has failed |
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” |
RC28 |
Invalid value for “Card - MPI” |
RC30 |
“Media Type” is not supported |
RC31 |
Required parameter(s) not present |
RC32 |
GET method is not supported |
RC43 |
Invalid JSON string |
RC44 |
“Dummy” should be “true” for test merchant |
RC2A |
Invalid “PayNow Account ID” |
RC2P |
There is no contract for PayNowID |
RC2Q |
Unable to validate account details. Please contact VeriTrans for details of the error |
RC2R |
Accounts created by dummy transactions cannot be used for production transactions. In addition, accounts created by actual transactions cannot be used for dummy transactions |
RC5A |
Invalid value for “Customer Email Address” |
RC5B |
Invalid value for “Customer Name” |
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” |
Changelog
v1.4
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 so that
paynow_account_id
can be specified when 3D Secure (identity authentication) is enabled.
Updated result codes
- Added
RC5M
、RC5N
、RC5O
、RC5P
、RC5Q
、RC5R
、RC5S
. - Deleted
RC2O
.
v1.3
March 13, 2024
Updated the connection domain to pay3.veritrans.co.jp
.
- “Payment Key” in Endpoint section of “Merchant Server Integration”.
- “Registration Link” in Endpoint section of “Registration Link”.
- “pay_link_url” in Response sample code section of “Registration Link”.
Updated the domain destination link of MAP(Merchant Administration Portal) to admin3.veritrans.co.jp
.
v1.2
October 25, 2021
Added description of 3ds_version
parameter in Card Options in “Request” section of “Merchant Server Integration”.
Added result codes for 3ds_version
.
v1.1
January 20, 2020
Added description for Registration Link and Registration Result.
Changed supporting TLS versions.
v1.0
August 22, 2018
Created new document.