NAV
POP Additional Card APIs(v1.2)

Getting Started

Overview

This guide provides information on using the capture, cancel, reauthorize and authorize (with PayNowID) APIs.

Interface details(*) for “card” can be found here.
* Document name (Japanese only): “MPI” under “インターフェース仕様書”

capture : Capture authorized transactions.
cancel : Cancel authorized transactions and refund settled transactions.
reauthorize : Make a payment request using credit card information from previous transactions.
authorize (with PayNowID) : Uses the credit card information associated with the PayNowID (card ID) registered in VeriTrans4G to make the payment.
※ To use authorize (with PayNowID) separate contract is required for One Click Continuous Billing(PayNowID).

transaction flow

API Reference

Endpoints

Capture : https://pay3.veritrans.co.jp/pop/v1/card-capture

Cancel : https://pay3.veritrans.co.jp/pop/v1/card-cancel

Reauthorize : https://pay3.veritrans.co.jp/pop/v1/card-reauthorize

Authorize (with PayNowID) : https://pay3.veritrans.co.jp/pop/v1/card-authorize

Request Specification

HTTP Method

POST

POP_SERVER_KEY = "Test-POP-Server-Key";

AUTH_STRING = Base64("Test-POP-Server-Key:");

AUTH_STRING = "VGVzdC1QT1AtU2VydmVyLUtleTo=";

Request Headers

The following two headers are provided in the HTTP request:

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 + :)

Capture

A capture request is used to capture an already authorized request.

Capture Request

{
    "order_id": "ORDER-0001",
    "amount": 10000,
    "dummy": true
}

The following parameters can be specified for the request.

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.
amount
number (8) (required)
Order amount.
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)

Capture Response

Success Response

{
    "order_id": "ORDER-0001",
    "status": "success",
    "result_code": "R001",
    "message": "Payment Captured Successfully",
    "m_status": "success",
    "v_result_code": "A001000000000000",
    "merr_msg": "処理が成功しました。"
}

Failure Response

{
    "order_id": "ORDER-0001",
    "status": "failure",
    "result_code": "RM01",
    "message": "Gateway error",
    "m_status": "failure",
    "v_result_code": "AC38000000000000",
    "merr_msg": "パラメータで指定した金額は超過しています。"
}

When POP receives Request, it returns the following parameters as a response.

Parameter Description
order_id
string(100) (optional)
Unique Order ID, set by merchant in the request.
status
string(7) (required)
Status of the request.
Values: success or failure
result_code
string(4) (required)
4 character result code that indicates success or the specific reason for failure. Result Codes
message
string(256) (required)
Message elaborating the status and result.
m_status
string(32) (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): “決済結果コード一覧”
merr_msg
string(300) (optional)
Error message from the Payment Gateway elaborating the status and result.
In case there is an error before request is sent to the Payment Gateway, then this parameter value is not returned.

Cancel

A cancel request is sent to cancel an existing order.

Cancel Request

{
    "order_id": "ORDER-0001",
    "amount": 10000,
    "dummy": true
}

The following parameters form the cancel request to the POP Server.

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.
amount
number (8) (optional)
Amount to cancel or refund. If not set, the full amount will apply.
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)

Cancel Response

Success Response

{
    "order_id": "ORDER-0001",
    "status": "success",
    "result_code": "R002",
    "message": "Payment Cancelled Successfully",
    "m_status": "success",
    "v_result_code": "A001000000000000",
    "merr_msg": "処理が成功しました。"
}

Failure Response

{
    "order_id": "ORDER-0001",
    "status": "failure",
    "result_code": "RM01",
    "message": "Gateway error",
    "m_status": "failure",
    "v_result_code": "AC38000000000000",
    "merr_msg": "パラメータで指定した金額は超過しています。"
}

When POP receives Request, it returns the following parameters as a response.

Parameter Description
order_id
string(100) (optional)
Unique Order ID, set by merchant in the request.
status
string(7) (required)
Status of the request.
Values: success or failure
result_code
string(4) (required)
4 character result code that indicates success or the specific reason for failure. Result Codes
message
string(256) (required)
Message elaborating the status and result.
m_status
string(32) (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): “決済結果コード一覧”
merr_msg
string(300) (optional)
Error message from the Payment Gateway elaborating the status and result.
In case there is an error before request is sent to the Payment Gateway, then this parameter value is not returned.

Reauthorize

A reauthorize request is used to reauthorize an already authorized request.

Reauthorize Request

{
    "order_id": "ORDER-0002",
    "original_order_id": "ORDER-0001",
    "amount": 10000,
    "capture": true,
    "dummy": true
}

The following parameters form the reauthorize request to the POP Server.

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.
original_order_id
string(100) (required)
Previous Order ID. Provide the Order ID from a past transaction. Settlement will be carried out using the card information used in the past transaction. Only single byte alphanumeric characters, ‘-’ (hyphen) and ‘_’ (underscore) can be used. Any other characters are not allowed.
amount
number (8) (required)
Total amount including shipping costs. Specify a value between 1 and 99,999,999 or less.
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)
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)

Reauthorize Response

Success Response

{
    "order_id": "ORDER-0001",
    "status": "success",
    "result_code": "R003",
    "message": "Payment Re-Authorize Successfully",
    "m_status": "success",
    "v_result_code": "A001000000000000",
    "merr_msg": "処理が成功しました。",
    "acquirer_code": "01",
    "auth_code": "000000",
    "masked_card_number": "411111*11",
    "transaction_datetime": "20190214171158"
}

Failure Response

{
    "order_id": "ORDER-0001",
    "status": "failure",
    "result_code": "RM01",
    "message": "Gateway error",
    "m_status": "failure",
    "v_result_code": "AG48000000000000",
    "merr_msg": "無効カードです。",
    "masked_card_number": "411111*11",
    "transaction_datetime": "20190214135533",
    "center_error_code": "G61"
}

When POP receives Request, it returns the following parameters as a response.

Parameter Description
order_id
string(100) (optional)
Unique Order ID, set by merchant in the request.
status
string(7) (required)
Status of the request.
Values: success or failure
result_code
string(4) (required)
4 character result code that indicates success or the specific reason for failure. Result Codes
message
string(256) (required)
Message elaborating the status and result.
m_status
string(32) (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): “決済結果コード一覧”
merr_msg
string(300) (optional)
Error message from the Payment Gateway elaborating the status and result.
In case there is an error before request is sent to the Payment Gateway, then this parameter value is not returned.
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 ‘*’)
transaction_datetime
string(14) (optional)
Transaction Date and time, returned by Payment Gateway.
(Follows YYYYMMDDhhmmss format)
center_error_code
string(3) (optional)
Center Error Code returned by Payment Gateway.

Authorize (with PayNowID)

An authorize (with PayNowID) uses the credit card information associated with the PayNowID (card ID) registered in VeriTrans4G to make the payment.
※ A separate contract is required for One Click Continuous Billing(PayNowID).

Authorize (with PayNowID) Request

{
    "order_id": "ORDER-0001",
    "amount": 10000,
    "capture": true,
    "paynow_account_id": "TEST-ACCOUNT-101",
    "paynow_card_id": "232QDFCPFBR93UBEAITN7EQHL",
    "paynow_default_card": true,
    "dummy": true
}

The following parameters form the authorize (with PayNowID) request to the POP Server.

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.
amount
number (8) (required)
Total amount including shipping costs. Specify a value between 1 and 99,999,999 or less.
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)
paynow_account_id
string(100) (required)
A unique registered account ID for each consumer. The account ID must be associated with one or more credit card information.
paynow_card_id
string(100) (optional)
This is used to specify the credit card information associated with the account ID used for payment. If not specified, use the credit card information set for the standard card.
paynow_default_card
boolean (optional)
Set true if you want the credit card information linked to paynow_card_id to be a standard card. Set false if you do not want to change the standard card. If paynow_card_id is not specified, leave it unset.
Values: true or false (Default: true)
dummy
boolean (optional)
This flag is set to decide if the request is dummy.
Values: true or false (Default: false)

Authorize (with PayNowID) Response

Success Response

{
    "order_id": "ORDER-0001",
    "status": "success",
    "result_code": "R004",
    "message": "Payment Authorized Successfully",
    "m_status": "success",
    "v_result_code": "A001X00100000000",
    "merr_msg": "処理が成功しました。",
    "acquirer_code": "05",
    "auth_code": "000000",
    "masked_card_number": "411111*11",
    "card_expire": "12/34",
    "transaction_datetime": "20230331171241",
    "paynow_status": "success",
    "paynow_account_id": "pop-payNowAccountId",
    "paynow_card_id": "9TTH6VLQ3RJH9JR38ISKFRPDG",
    "paynow_message": "処理が成功しました。",
    "paynow_default_card": true
}

Failure Response

{

    "order_id": "ORDER-0001",
    "result_code": "RM01",
    "message": "Gateway error",
    "status": "failure",
    "v_result_code": "AC22XH0900000000",
    "m_status": "failure",
    "merr_msg": "カード番号パラメータが設定していません。",
    "paynow_status": "failure",
    "paynow_message": "未登録のカードです。"
}

When POP receives Request, it returns the following parameters as a response.

Parameter Description
order_id
string(100) (optional)
Order ID specified at the time of request.
status
string(7) (required)
Status of the request.
Values: success or failure
result_code
string(4) (required)
4 character result code that indicates success or the specific reason for failure. Result Codes
message
string(256) (required)
Message elaborating the status and result.
m_status
string(32) (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): “決済結果コード一覧”
merr_msg
string(300) (optional)
Error message from the Payment Gateway elaborating the status and result.
In case there is an error before request is sent to the Payment Gateway, then this parameter value is not returned.
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 ‘*’)
card_expire
string(5) (optional)
Expiry date of the card being used(MM/YY).
transaction_datetime
string(14) (optional)
Transaction Date and time, returned by Payment Gateway.
(Follows YYYYMMDDhhmmss format)
center_error_code
string(3) (optional)
Center Error Code returned by Payment Gateway.
paynow_status
string(10) (optional)
The status of PayNowID operation done during the transaction.
paynow_account_id
string(100) (optional)
Specified PayNowID.
paynow_card_id
string(100) (optional)
Card ID used for payment.
paynow_message
string(100) (optional)
The message of PayNowID operation done during the transaction.
paynow_default_card
boolean (optional)
It is the flag indicating whether the card information used is a standard card.

Going Live

Please use POP_SERVER_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 endpoints.

Result Codes

The result_code returned from POP in each API represents the processing result.

Here is a list of result_code values and their descriptions:

Common

Result Code Description
RA01 Application Error - if any unknown error has occurred on VeriTrans side
RD01 Database Error - if there is a severe error in VeriTrans Database
RM01 Gateway Error - if there is some error while connecting to Payment Gateway.
RM03 MDK Error - if an error is returned by Payment Gateway.
RC01 Invalid “Order ID”
RC17 Merchant authentication failed. Please check POP_SERVER_KEY
RC26 Invalid value for “Dummy”
RC30 Unsupported “Media Type”
RC32 GET method is not supported
RC3A Invalid “Amount”
RC43 Invalid JSON string - JSON string in the POST request is invalid
RC44 “Dummy” should be “true” for test merchant

Capture

The following result codes are returned only for capture.

Result Code Description
R001 Payment Captured Successfully

Cancel

The following result codes are returned only for cancel.

Result Code Description
R002 Payment Cancelled Successfully

Reauthorize

The following result codes are returned only for reauthorize.

Result Code Description
R003 Payment Reauthorized Successfully
RC27 Invalid value for “Capture”
RC3B Invalid “Security Code”
RC3C Invalid “Original orderId”
RC40 Invalid value for “JPO”
RC41 Invalid value for “JPO Count”

Authorize (with PayNowID)

The following result codes are returned only for authorize (with PayNowID).

Result Code Description
R004 Payment Authorized Successfully
RC27 Invalid value for “Capture”
RC2A Invalid “PayNow Account ID”
RC2F Invalid value for “PayNow Default Card”
RC2K Invalid value for “PayNow Card ID”

FAQ

FAQ(*) can be found here.
*Section name(Japanese only): “POP(4G)” under “接続方式”

Changelog

v1.2

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

July 05, 2023

Added description of Authorize (with PayNowID) API.

v1.0

June 28, 2019

Created new document.