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).
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:
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
+ :
)
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
.
- “Endpoints” in Endpoints section of “API Reference”.
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.