NAV
POP Card Registration API(v1.4)

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

  1. Customer performs the register operation.
  2. Merchant server sends an API request to the POP server to get the payment_key.
  3. POP Server responds with the payment_key.
  4. Merchant server constructs the html page and sends it back to the customer’s browser.
  5. 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.
  6. 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.
  7. POP Server notifies the merchant server about the registration status.

registration flow

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.

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

https://pay3.veritrans.co.jp/pop/v1/account-registration-link

HTTP Method

POST

Request Headers

Refer to section Request Headers for details of the headers to be set in the request.

Except the following parameters, all other Request Parameters from Merchant Server Integration can be set.

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.

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

Updated result codes

v1.3

March 13, 2024

Updated the connection domain to pay3.veritrans.co.jp.

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.