Introduction to 3G-Direct

3G-Direct is a new payment service which offers credit card payment using a simple Web API in which credit card information does not interface with the merchant's websites.

API Endpoint

  • https://api.veritrans.co.jp/vtdirect

Endpoint for each API

  • /v2/veritrans.min.js
  • /v2/charges
  • /v2/capture
  • /v2/void
  • /v2/search
  • /v2/account
  • /v2/account_card
  • /v2/account_charges
  • /v2/entry_with_charges
  • /v2/mpi_charges
  • /v2/entry_with_mpi_charges
  • /v2/account_mpi_charges
  • /v2/tokens
  • /v2/cvs

Glossary

This glossary contains definitions of certain technical terms which frequently appear in this document.
Merchant
Business or individual using 3G-Direct.
Merchant Site
Site operated by business or individual which uses 3G-Direct for payment.
MAP
Merchant Administration Portal (MAP) is system offered by VeriTrans to Merchants, for transaction management. Merchants can search for transactions on MAP created with 3G-Direct
API
Web API offered by 3G-Direct.
3G-Direct has different end points for each API. Merchants can call API for the function she/he wants to use by putting authentication information in header and request parameters in the body, and then send the GET or POST request by serializing the JSON object.
The merchant's website can easily parse the response as it is in JSON format.
API Library
Program library to send requests to 3G-Direct API.
Instead of using the library provided, merchants can implement and use their own libraries as the specifications for API are very simple.
Client Key
When using Tokens API, it's necessary to include this authentication key for the Requested parameter. Use this key in HTML or Java Script.
Server Key
Authentication key to use for each API except Tokens API. Specified and used as authorization header on HTTP header. As the authentication key is quite important, it should be stored on the merchant's server only. Take care to prevent from leaking to the outside.
veritrans.min.js (veritrans.js)
Java Script program to send credit card information to 3G-Direct and obtain Token Id.
Credit card information is sent directly from the browser to 3G-Direct by loading it on credit card information entry screen of merchants' website.
Please refer to veritrans.min.js for further details.
Token, Token Id
Single use token of alphabet and hyphens that wraps the details of a credit card information when Token IP is called with credit card information.
The token contains 36 random characters. The first six and last four digits of credit card number are used.
Token Id is valid only for 1 minute and contains the required parameters to identify the credit card information. It is used for Charges API etc. Once sent, it will expire and cannot be reused.
Order Id
A unique and mandatory identifier set by merchant website to identify payment made by 3G-Direct.
Order Id is required as parameter for other 3G-Direct APIs like Capture API, etc. as described later, merchants should save in their own database. In many cases, the key value of database of merchants' websites can be used as an Order Id.
Tokens API
API to keep credit card information temporarily on 3G-Direct. Responds with Token Id to identify the registered credit card information.
Charges API
API to perform authorization or authorization and capture by credit card.
The parameters, Token Id issued by 3G-Direct, numbered Order Id and the payment amount are the minimal three required parameters.
As the Token Id has an expiration, once your browser obtains a Token Id from veritrans.min.js, immediately send it to the merchant site and execute payment using Charges API.
Account Id
In order to register a member with 3G-Direct, it is necessary to send a unique value string for the Account ID from the merchant's site as to the API.
In many cases, the member's number on the merchant's site's database will be used as the Account ID.
Card Id
For registered members, Card ID is an ID which is used for payments when additional card information is added. Using both Account Id and Card Id, registered information can be used to process payments.
Installment option
For Installment payment, there are some restrictions in case of Payment aggregator model. Refer following chart.
Type Value Meaning Possible Installment options for
Payment aggregator model
VISA/
MASTER
JCB AMEX DINERS
One time 10
Not Specified
Installment 61Cxx C=Installment option,
xx=No of Installments
×
Revolving 80 ×
Merchant can choose installment option based on their contract.
* Merchant having contract only for One time payment cannot use this option.
* In case of Payment aggregator model, Installment option 02, Bonus payment, Bonus with payment cannot be use. Also, possible values for No of Installments(xx) are 03,05,06,10,12,15,18,20,24.
 

Authentication Process

To use 3G-Direct API, the parameters used in Authentication needs to be specified.

Server Key

For API call from merchants' server like Charges API or Capture API etc. it is necessary to specify server key in the HTTP Header.
In addition to Accept header, Content-Type header, please append the following to the Authorization HTTP header.
Header Value
Accept application/json
Content-Type application/json
Authorization Basic {Base 64 encoded value of Server Key}

Client Key

As Tokens API uses veritrans.min.js and send credit card information from browser to 3G-Direct, it is necessary to include Client Key, instead of Server Key, in parameter.
For more detail, please refer to veritrans.min.js and Tokens API.
 

Error Handling

Merchants' sites need to handle the page transition etc. depending on the response of payment sent from API.
Below is the information for result decision.

Http Status Code

Please confirm first if the Http Status Code is 200.
API library throws exception if Http Status Code is not 200.

code

JSON response always contains code. Please refer to the response code table on the right for details.

status

JSON response always contains status. Please refer to the response code table on the right for details.

message

JSON response always contains message.
Also contains information that which process is successful or the reason why the process was failed, etc.

errors

In case of incorrect parameter error code Q001 will be sent along with reason of failure in errors.
The contents are as same as that of message,but when there are several incorrect parameters, String array containing all the reasons will be sent.

timeout

Normally respond in few seconds, but as the upper limit for payment process is 2 minutes, please set the timeout limit for API as 130 seconds.

Response Patterns

code Description
Q000
When the process is successful
Q001
When the incorrect parameter is sent or when cannot be verified. Or payment is failed.
Q002
In case if Client ley is empty when credit card information is sent to Tokens API by using veritrans.min.js.
Q099
When unexpected error occurs at 3G-Direct.
status Description
success
When the code is Q000.
failure
When the code is Q001.
fatal
When the code is Q099.
transaction_type
(Card)
Description
init
At the time error
a
Authorization
ax
Authorization(Expired)
ac
Authorization & Capture
pa
Capture
va,rad,rae
Authorization -> Cancel
vac,racd,race
Authorization & Capture -> Cancel
vpa,rpad,rpae
Capture -> Cancel
transaction_type
(CVS)
Description
authorize
Request completion(includes failure)
cancel_authorize
Cancelled
fix_capture
Has been credited

failure error samples

Examples of JSON response when failure error occurs.
{
  "data": {
    "order_id": "TEST0005",
    "gross_amount": 1980,
    "card_number": "4111XXXXXXXXXX11",
    "with_capture": false
  },
  "mstatus": "failure",
  "vresult_code": "NH18000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Order already succeeded]",
  "errors": [
    "Order already succeeded"
  ]
}

fatal error example

JSON response when fatal error occurs.
{
  "code": "Q099",
  "status": "fatal",
  "message": "Fatal error, please contact veriTrans"
}

veritrans.min.js

For payment with 3G-Direct, it required to send credit card information to Token API to get Token Id.
Normally, the browser directly calls Tokens API with the information entered on credit card information entry screen on merchants' site by using the method of veritrans.min.js.

Loading

Set script tag for loading veritrans.min.js from 3G-Direct on credit card information entry screen.
<script src="https://api.veritrans.co.jp/vtdirect/v2/veritrans.min.js">

Sending credit card information

Specify the code in Veritrans.tokenGet function to send credit card information.
// Set the Client Key
Veritrans.client_key = "Client Key";

function _error(d) {
  var message = d.message;
  // Set the code for Navigation in case of failure.
}

function _success(d) {
  var token_id = d.data.token_id;
  // Set the code to send the obtained Token Id to merchants' site.
}

function _cardSet() {
  return {
    "card_number": "Card Number", // Set the card number entered.
    "card_exp_month": "Expiration Date(MM)", // Set the expiration date (month) entered
    "card_exp_year": "Expiration Date(YYYY)", //Set the expire date (year) entered
    "card_cvv": "Security Code" // Set the security code entered.
  }
}

// Set the code to send the credit card information when the button is pressed
$("button.submit").bind("click", function () {
  Veritrans.tokenGet(_cardSet, _success, _error);
});

Credit Card Payment (/charges)

API to make a payment by using Token Id
As Token Id has upper limit for expiry of 1 minute, needs to make credit card payment with API as soon as Token Id is sent to merchant site from browser.

Uri

Set the request parameter in JSON body and make a POST request to the following URL POST.
https://api.veritrans.co.jp/vtdirect/v2/charges

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key} Set base 64 encoded Server Key.

Request Body *…Required

* token_id Set Token Id issued by Tokens API
* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* gross_amount Set payment amount between 1~99999999.
with_capture Set the Boolean value if you want to capture at the time of authorization. If it's not set, then only authorization will be performed. When set "true", capture will be performed at the time of authorization.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.
jpo Set the Installment option for the payment. Default value is one time payment.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\ChargesParameter();
$input->order_id = "TEST0003";
$input->token_id = "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111";
$input->gross_amount = 1980;
$charges = new \VtDirect\Client\Charges($setting);
$response = $charges->ChargeWithToken($input);
            

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::ChargesParameter.new
api = VtDirect::Charges.new setting
input.order_id = 'TEST0030'
input.token_id = 'abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111'
input.gross_amount = 1980
response = api.charge_with_token input
            

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
ChargeRequest input = new ChargeRequest();
Charges api = new Charges(clientConfiguration);
input.setGrossAmount(1980);
input.setOrderId("TEST0050");
input.setTokenId("abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111");
ChargeResponse response = api.chargeWithToken(input);
            

Request Example 1

Send the JSON request as below.
{
  "token_id": "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111",
  "order_id": "TEST0001",
  "gross_amount": 1980
}
        

Contents of successful response

{
  "data": {
    "order_id": "TEST0004",
    "gross_amount": 1980,
    "card_number": "4111XXXXXXXXXX11",
    "with_capture": false
  },
  "mstatus": "success",
  "vresult_code": "A001H00100000000",
  "transaction_type": "a",
  "pending": "0",
  "acquirer_code": "05",
  "trad_url": "https://www.example.com/abcde;fghij;klmno",
  "code": "Q000",
  "status": "success",
  "message": "Success do charge transaction"
}
        

Credit Card Error Handling

On Credit Card payment, authorization can be failed due to various reasons.
For Charges API, perform the page transition based on the response result and by referring the contents below.

mstatus

Contains result codes. There are 3 types of mstatus.
mstatus is success only when authorization and authorization with capture is successful.
mstatus Indication
success Success
failure Failure
pending Pending

vresult_code

Contains detailed result code.
Please do the navigation as per your needs.
The results code list, can be downloaded from the "結果コード一覧" on support page.

Contents of failed response

When Token is expired

{
  "code": "Q001",
  "status": "failure",
  "message": "[Token was expired]",
  "errors": [
    "Token was expired"
  ]
}

When OrderID is duplicated

{
  "data": {
    "order_id": "TEST0005",
    "gross_amount": 1980,
    "card_number": "4111XXXXXXXXXX11",
    "with_capture": false
  },
  "mstatus": "failure",
  "vresult_code": "NH18000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Order already succeeded]",
  "errors": [
    "Order already succeeded"
  ]
}

Card Error

{
  "data": {
    "order_id": "TEST0007",
    "gross_amount": 1980,
    "card_number": "4111XXXXXXXXXX11",
    "with_capture": false
  },
  "mstatus": "failure",
  "vresult_code": "AG72000000000000",
  "transaction_type": "init",
  "pending": "",
  "acquirer_code": "05",
  "code": "Q001",
  "status": "failure",
  "message": "[Card Error]",
  "errors": [
    "Card Error"
  ]
}

Manage Account

Register card number, manage members to be able to make payments without entering card details.

Register Account (/account)

Associates members with their respective card numbers.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/account

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* account_id Set the identifier ID (created by the merchant) on the merchant's site. Valid characters are Half-width alphanumeric, hyphen and underscore and atmark and dot, up to 100 characters in length.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\CreateAccountParameter();
$input->account_id = "TestAccount0001";
$api = new VtDirect\Client\Account($setting);
$response = $api->CreateAccount($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::CreateAccountParameter.new
input.account_id = 'TestAccount0001'
api = VtDirect::Account.new setting
response = api.create_account input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountRequest input = new AccountRequest();
input.setAccountId("TestAccount0001");
Account api = new Account(clientConfiguration);
AccountCreateResponse response = api.createAccount(input);

Request Example

{
  "account_id": "TestAccount0001"
}

Details upon successful response

{
  "data": {
    "account_id": "TestAccount0001"
  },
  "mstatus": "success",
  "vresult_code": "X001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Account add request was successful"
}
        

Contents of failed response

When the registered Account Id was specified

{
  "mstatus": "failure",
  "vresult_code": "XH11000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Registered account error]",
  "errors": [
    "Registered account error"
  ]
}

When the deleted Account Id was specified

{
  "mstatus": "failure",
  "vresult_code": "XH12000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Withdrew account error]",
  "errors": [
    "Withdrew account error"
  ]
}

Delete Account (/account)

Deletes a registered member.

Uri

Request DELETE at the following URL.
https://api.veritrans.co.jp/vtdirect/v2/account?account_id={Account Id}

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* account_id Set the member's ID.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\DeleteAccountParameter();
$input->account_id = "TestAccount0001";
$api = new VtDirect\Client\Account($setting);
$response = $api->DeleteAccount($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::DeleteAccountParameter.new
input.account_id = 'TestAccount0001'
api = VtDirect::Account.new setting
response = api.delete_account input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountRequest input = new AccountRequest();
input.setAccountId("TestAccount0001");
Account api = new Account(clientConfiguration);
AccountDeleteResponse response = api.deleteAccount(input);

Request Example

"https://api.veritrans.co.jp/vtdirect/v2/account?account_id=TestAccount0001"

Details upon successful response

{
  "data": {
    "account_id": "TestAccount0001"
  },
  "mstatus": "success",
  "vresult_code": "X001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Account delete request was successful"
}
                

Contents of failed response

When the deleted Account Id was specified

{
  "mstatus": "failure",
  "vresult_code": "XH12000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Withdrew account error]",
  "errors": [
    "Withdrew account error"
  ]
}

Show Account Information (/account)

Gets card details for the card associated with a registered member.

Uri

Request GET at the URL below.
https://api.veritrans.co.jp/vtdirect/v2/account?account_id={Account Id}

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* account_id Set the member's ID.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\GetAccountInfoParameter();
$input->account_id = "TestAccount0001";
$api = new VtDirect\Client\Account($setting);
$response = $api->GetAccountInfo($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::GetAccountInfoParameter.new
input.account_id = 'TestAccount0001'
api = VtDirect::Account.new setting
response = api.get_account_info input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountRequest input = new AccountRequest();
input.setAccountId("TestAccount0001");
Account api = new Account(clientConfiguration);
AccountInfoResponse response = api.getAccountInfo(input);

Request Example

"https://api.veritrans.co.jp/vtdirect/v2/account?account_id=TestAccount0001"

Details upon successful response

{
  "data": {
    "account_id": "TestAccount0001",
    "cards": [
      {
        "card_brand": "VISA",
        "card_number": "411111********11",
        "card_id": "ABCDE123456789ABCDEFGHIJK",
        "card_expire": "08/2015"
      }
    ]
  },
  "mstatus": "success",
  "vresult_code": "X001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Card information query was successful"
}
                

When the card is not registered

{
  "data": {
    "account_id": "TestAccount0001",
    "cards": []
  },
  "mstatus": "success",
  "vresult_code": "X001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Card information query was successful"
}

Contents of failed response

When the registered Account Id was specified

{
  "mstatus": "failure",
  "vresult_code": "XH12000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Withdrew account error]",
  "errors": [
    "Withdrew account error"
  ]
}

Register Card (/account_card)

Associates card details with a registered member.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/account_card

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* token_id Set the TokenID issued by the Tokens API.
* account_id Set the Account ID for the added card.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\Card\AddParameter();
$input->account_id = "TestAccount0002";
$input->token_id = "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111";
$api = new VtDirect\Client\AccountCard($setting);
$response = $api->AddCard($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::Card::AddParameter.new
input.account_id = 'TestAccount0001'
input.token_id = 'abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111'
api = VtDirect::AccountCard.new setting
response = api.add_card input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountCardRequest input = new AccountCardRequest();
input.setAccountId("TestAccount0002");
input.setTokenId("abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111");
AccountCard api = new AccountCard(clientConfiguration);
AccountCardAddResponse response = api.addCard(input);

Request Example

{
    "account_id": "TestAccount0002",
    "token_id": "abcdef12-1234-abcd-ef12-abcdef1234ab-555555-4444"
}

Details upon successful response

{
  "data": {
    "account_id": "TestAccount0002",
    "card_brand": "MASTER",
    "card_number": "555555********44",
    "card_expire": "08/2015",
    "card_id": "ABCDE123456789ABCDEFGHIJK"
  },
  "mstatus": "success",
  "vresult_code": "X001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Request to register the card information to the account was successful"
}
                

Contents of failed response

When the same credit card is already registered.

{
  "data": {
    "account_id": "TestAccount0002"
  },
  "mstatus": "failure",
  "vresult_code": "XH04000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Duplicate registration error]",
  "errors": [
    "Duplicate registration error"
  ]
}
                    

When Token is expired

{
  "code": "Q001",
  "status": "failure",
  "message": "[Token was expired]",
  "errors": [
    "Token was expired"
  ]
}
                    
When credit card authorization fails.
{
  "data": {
    "account_id": "TestAccount0002"
  },
  "mstatus": "failure",
  "vresult_code": "XH41000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Internal card authorization error]",
  "errors": [
    "Internal card authorization error"
  ]
}
                    

Delete Card (/account_card)

Deletes card details associated with a registered member.

Uri

Request DELETE at the URL below.
https://api.veritrans.co.jp/vtdirect/v2/account_card?account_id={Account Id}&card_id={Card Id}

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* account_id Set the corresponding Account ID.
* card_id Set the corresponding Card ID.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\Card\DeleteParameter();
$input->account_id = "TestAccount0002";
$input->card_id = "ABCDE123456789ABCDEFGHIJK";
$api = new VtDirect\Client\AccountCard($setting);
$response = $api->DeleteCard($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::Card::DeleteParameter.new
input.account_id = 'TestAccount0002'
input.card_id = 'ABCDE123456789ABCDEFGHIJK'
api = VtDirect::AccountCard.new setting
response = api.delete_card input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountCardRequest input = new AccountCardRequest();
input.setAccountId("TestAccount0002");
input.setCardId("ABCDE123456789ABCDEFGHIJK");
AccountCard api = new AccountCard(clientConfiguration);
AccountCardDeleteResponse response = api.deleteCard(input);

Request Example

"https://api.veritrans.co.jp/vtdirect/v2/account_card?account_id=TestAccount0002&card_id=ABCDE123456789ABCDEFGHIJK"

Details upon successful response.

{
  "data": {
    "account_id": "TestAccount0002"
  },
  "mstatus": "success",
  "vresult_code": "X001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Request to delete card from account was successful"
}
                

Contents of failed response

When the deleted Card Id was specified

{
  "data": {
    "account_id": "TestAccount0002"
  },
  "mstatus": "failure",
  "vresult_code": "XH05000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Deleted error]",
  "errors": [
    "Deleted error"
  ]
}
                    

未登録のカードIDを指定した場合

{
  "data": {
    "account_id": "TestAccount0002"
  },
  "mstatus": "failure",
  "vresult_code": "XH09000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Unregistered card error]",
  "errors": [
    "Unregistered card error"
  ]
}
                    

Member Payments (/account_charges)

Execute payments using card details associated with a member.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/account_charges

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* account_id Set the Account Id for the registered member.
* card_id Set the Card Id for the registered member.
* gross_amount Set payment amount (1~99999999)
with_capture Set the Boolean value if you want to charge at the time of authorization. When not set, authorization will be executed. When set to true, authorization and capture will execute together.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.
jpo Set the Installment option for the payment. Default value is one time payment.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\AccountChargesParameter();
$input->order_id = "TEST1002";
$input->account_id = "TestAccount0002";
$input->card_id = "ABCDE123456789ABCDEFGHIJK";
$input->gross_amount = 1980;
$api = new VtDirect\Client\AccountCharges($setting);
$response = $api->ChargeWithCardId($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::AccountChargesParameter.new
input.order_id = 'Test1002'
input.account_id = 'TestAccount0002'
input.card_id = 'ABCDE123456789ABCDEFGHIJK'
input.gross_amount = 1980
api = VtDirect::AccountCharges.new setting
response = api.charge_with_card_id input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountChargeRequest input = new AccountChargeRequest();
input.setAccountId("TestAccount0002");
input.setCardId("ABCDE123456789ABCDEFGHIJK");
input.setOrderId("TEST1002");
input.setGrossAmount(1980);
AccountCharges api = new AccountCharges(clientConfiguration);
AccountChargeResponse response = api.chargeWithCardId(input);

Request Example

{
    "order_id": "TEST1002",
    "account_id": "TestAccount0002",
    "card_id": "ABCDE123456789ABCDEFGHIJK",
    "gross_amount": 1980,
}

Details upon successful response.

{
  "data": {
    "order_id": "TEST1002",
    "gross_amount": 1980,
    "account_id": "TestAccount0002",
    "card_number": "555555********44",
    "card_expire": "08/2015",
    "card_brand": "MASTER",
    "card_id": "ABCDE123456789ABCDEFGHIJK",
    "with_capture": false
  },
  "mstatus": "success",
  "vresult_code": "A001H001X0010000",
  "transaction_type": "a",
  "pending": "0",
  "acquirer_code": "05",
  "trad_url": "https://www.example.com/abcde;fghij;klmno",
  "code": "Q000",
  "status": "success",
  "message": "Registered account charge transaction was successful"
}
                

Contents of failed response

When the unregistered Card Id was specified

{
  "data": {
    "order_id": "TEST1003",
    "gross_amount": 1980,
    "card_brand": "",
    "with_capture": false
  },
  "mstatus": "failure",
  "vresult_code": "AC22XH0900000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Parameter Error, Unregistered card error]",
  "errors": [
    "Parameter Error",
    "Unregistered card error"
  ]
}
                    

Simultaneous Registration and Payments (/entry_with_charges)

Associates card information with simultaneous registration and payment.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/entry_with_charges

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* account_id Set the identifier ID (created by the merchant) on the merchant's site. Valid characters are Half-width alphanumeric, hyphen and underscore and atmark and dot, up to 100 characters in length.
* token_id Set the TokenID issued by the Token API.
* gross_amount Set payment amount (1~99999999)
with_capture Set simultaneous register/capture or not by using a Boolean value. When not set, authorization will be executed. When set to true, registration and authorization will execute together.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.
jpo Set the Installment option for the payment. Default value is one time payment.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\EntryWithChargesParameter();
$input->order_id = "TEST1001";
$input->account_id = "TestAccount0003";
$input->token_id = "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111";
$input->gross_amount = 1980;
$api = new VtDirect\Client\EntryWithCharges($setting);
$response = $api->ChargeWithEntry($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::EntryWithChargesParameter.new
input.order_id = 'TEST1001'
input.account_id = 'TestAccount0003'
input.token_id = 'abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111'
input.gross_amount = 1980
api = VtDirect::EntryWithCharges.new setting
response = api.charge_with_entry input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
EntryWithChargeRequest input = new EntryWithChargeRequest();
input.setOrderId("TEST1001");
input.setAccountId("TestAccount0003");
input.setTokenId("abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111");
input.setGrossAmount(1980);
EntryWithCharges api = new EntryWithCharges(clientConfiguration);
EntryWithChargeResponse response = api.chargeWithEntry(input);

Request Example

{
    "account_id": "TestAccount0003",
    "token_id": "abcdef12-1234-abcd-ef12-abcdef1234ab-555555-4444",
    "order_id": "TEST1001",
    "gross_amount": 1980
}

Details upon successful response.

{
  "data": {
    "order_id": "TEST1001",
    "gross_amount": 1980,
    "account_id": "TestAccount0003",
    "card_number": "555555********44",
    "card_id": "ABCDE123456789ABCDEFGHIJK",
    "card_expire": "08/2015",
    "card_brand": "MASTER",
    "with_capture": false
  },
  "mstatus": "success",
  "vresult_code": "A001H001X0010000",
  "transaction_type": "a",
  "pending": "0",
  "acquirer_code": "05",
  "trad_url": "https://www.example.com/abcde;fghij;klmno",
  "code": "Q000",
  "status": "success",
  "message": "Add account and charge transaction was successful"
}
                

Contents of failed response

When credit card authorization fails.
{
  "data": {
    "order_id": "TEST1001",
    "gross_amount": 1980,
    "card_brand": "",
    "with_capture": false
  },
  "mstatus": "failure",
  "vresult_code": "AG72000000000000",
  "transaction_type": "init",
  "acquirer_code": "02",
  "code": "Q001",
  "status": "failure",
  "message": "[Card Error]",
  "errors": [
    "Card Error"
  ]
}
                    

3-D Secure

After completing 3-D Secure, executes payments and other processes.
When the status is "success" for the results for the API below, with the received response_contents from the response, redirect the browser to the 3-D Secure flow.

3-D Secure Payment (/mpi_charges)

After completing 3-D Secure, executes payments.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/mpi_charges

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* token_id Set the TokenID issued by the Token API.
* gross_amount Set the payment amount from 1 to 99999999.
* service_option_type Set one of the following
"mpi-complete": Complete verification
"mpi-company": Normal Verification (Card Company bears risk)
"mpi-merchant": Normal Verification (Card Company and Merchant bear risk)
push_uri Set the URL of the merchant's website for notification of 3-D Secure result. 256 half-width characters.
* redirection_uri Browser's return URL after completion of 3-D Secure. Up to 256 half-width characters.
* http_user_agent Set the browser's HTTP User-Agent header.
* http_accept Set the browser's HTTP Accept header.
with_capture Set the Boolean value if you want to charge at the time of authorization. When not set, authorization will be executed. When set to true, capture and authorization will execute together
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.
jpo Set the Installment option for the payment. Default value is one time payment.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\MpiChargesParameter();
$input->token_id = "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111";
$input->order_id = "TEST1005";
$input->gross_amount = 1980;
$input->service_option_type = "mpi-complete";
$input->push_uri = "https://example.com/push_receive";
$input->redirection_uri = "https://example.com/complete";
$input->http_user_agent = "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko";
$input->http_accept = "text/html, application/xhtml+xml, */*";
$api = new VtDirect\Client\MpiCharges($setting);
$response = $api->MpiChargeWithToken($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::MpiChargesParameter.new
input.token_id = 'abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111'
input.order_id = 'TEST1005'
input.gross_amount = 1980
input.service_option_type = 'mpi-complete'
input.push_uri = 'https://example.com/push_receive'
input.redirection_uri = 'https://example.com/complete'
input.http_user_agent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko'
input.http_accept = 'text/html, application/xhtml+xml, */*'
api = VtDirect::MpiCharges.new setting
response = api.mpi_charge_with_token input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
MpiChargeRequest input = new MpiChargeRequest();
input.setTokenId("abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111");
input.setOrderId("TEST1005");
input.setGrossAmount(1980);
input.setServiceOptionType("mpi-complete");
input.setPushUri("https://example.com/push_receive");
input.setRedirectionUri("https://example.com/complete");
input.setHttpAccept("text/html, application/xhtml+xml, */*");
input.setHttpUserAgent("Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko");
MpiCharges api = new MpiCharges(clientConfiguration);
MpiChargeResponse response = api.mpiChargeWithToken(input);

Request Example

{
    "token_id": "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111",
    "order_id": "TEST1006",
    "gross_amount": 1980,
    "service_option_type": "mpi-complete",
    "push_uri": "https://example.com/push_receive",
    "redirection_uri": "https://example.com/complete",
    "http_user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
    "http_accept": "text/html, application/xhtml+xml, */*"
}

Details upon successful response.

{
  "data": {
    "order_id": "TEST1006",
    "gross_amount": 1980,
    "with_capture": false,
    "service_option_type": "mpi-complete",
    "response_contents": "\u003c!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 ....(abbr",
    "res_corporation_id": "05",
    "res_brand_id": "5"
  },
  "mstatus": "success",
  "vresult_code": "G001H00100000000",
  "code": "Q000",
  "status": "success",
  "message": "mpi authorize request was successful"
}

Contents of failed response

Cannot execute 3-D secure authorization (Issuer or card member has not participate.)

{
  "mstatus": "failure",
  "vresult_code": "GE02000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Cannot perform the authentication]",
  "errors": [
    "Cannot perform the authentication"
  ]
}

Simultaneous Registration and 3-D Secure (/entry_with_mpi_charges)

Associates card details while simultaneously registering member and executing 3-D Secure.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/entry_with_mpi_charges

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* token_id Set the TokenID issued by the Token API.
* account_id Set the identifier ID (created by the merchant) on the merchant's site. Valid characters are Half-width alphanumeric, hyphen and underscore and atmark and dot, up to 100 characters in length.
* gross_amount Set the payment amount from 1 to 99999999.
* service_option_type Set one of the following.
"mpi-complete": Complete verification
"mpi-company": Normal Verification (Card Company bears risk)
"mpi-merchant": Normal Verification (Card Company and Merchant bear risk)
push_uri Set the URL of the merchant's website for notification of 3-D Secure result. 256 half-width characters.
* redirection_uri Browser's return URL after completion of 3-D Secure. Up to 256 half-width characters.
* http_user_agent Set the browser's HTTP User-Agent header.
* http_accept Set the browser's HTTP Accept header.
with_capture Set simultaneous authorise/capture or not by using a Boolean value. When not set, authorization will be executed. When set to true, capture and authorization will execute together.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.
jpo Set the Installment option for the payment. Default value is one time payment.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\EntryWithMpiChargesParameter();
$input->token_id = "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111";
$input->order_id = "TEST1007";
$input->account_id = "TestAccount0004";
$input->gross_amount = 1980;
$input->service_option_type = "mpi-complete";
$input->push_uri = "https://example.com/push_receive";
$input->redirection_uri = "https://example.com/complete";
$input->http_user_agent = "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko";
$input->http_accept = "text/html, application/xhtml+xml, */*";
$api = new VtDirect\Client\EntryWithMpiCharges($setting);
$response = $api->EntryWithMpiCharge($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::EntryWithChargesParameter.new
input.token_id = 'abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111'
input.order_id = 'TEST1007'
input.account_id = 'TestAccount0004'
input.gross_amount = 1980
input.service_option_type = 'mpi-complete'
input.push_uri = 'https://example.com/push_receive'
input.redirection_uri = 'https://example.com/complete'
input.http_user_agent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko'
input.http_accept = 'text/html, application/xhtml+xml, */*'
api = VtDirect::EntryWithMpiCharges.new setting
response = api.entry_with_mpi_charge input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
EntryWithMpiChargeRequest input = new EntryWithMpiChargeRequest();
input.setTokenId("abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111");
input.setOrderId("TEST1010");
input.setAccountId("TestAccount0004");
input.setGrossAmount(1980);
input.setServiceOptionType("mpi-company");
input.setPushUri("https://example.com/push_receive");
input.setRedirectionUri("https://example.com/complete");
input.setHttpAccept("text/html, application/xhtml+xml, */*");
input.setHttpUserAgent("Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko");
EntryWithMpiCharges api = new EntryWithMpiCharges(clientConfiguration);
MpiChargeResponse response = api.entryWithMpiCharge(input);

Request Example

{
    "token_id": "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111",
    "order_id": "TEST1007",
    "account_id": "TestAccount0004",
    "gross_amount": 1980,
    "service_option_type": "mpi-complete",
    "push_uri": "https://example.com/push_receive",
    "redirection_uri": "https://example.com/complete",
    "http_user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
    "http_accept": "text/html, application/xhtml+xml, */*"
}

Details upon successful response.

{
  "data": {
    "order_id": "TEST1007",
    "account_id": "TestAccount0004",
    "gross_amount": 1980,
    "with_capture": false,
    "service_option_type": "mpi-complete",
    "response_contents": "\u003c!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 ....(abbr",
    "res_corporation_id": "05",
    "res_brand_id": "5"
    },
  "mstatus": "success",
  "vresult_code": "G001H00100000000",
  "code": "Q000",
  "status": "success",
  "message": "mpi authorize request was successful"
}
                

3-D Secure Member Payment (/account_mpi_charges)

Executes 3-D Secure payments for previously registered members.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/account_mpi_charges

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* token_id Set the TokenID issued by the Token API.
* account_id Set the corresponding member's ID.
* card_id Set the Card ID for the previously registered member.
* gross_amount Set the payment amount from 1 to 99999999.
* service_option_type Set one of the following.
"mpi-complete":Complete Verification
"mpi-company": Normal Verification (Card Company bears risk)
"mpi-merchant": Normal Verification (Card Company and Merchant bear risk)
push_uri Set the URL of the merchant's website for notification of 3-D Secure result. 256 half-width characters.
* redirection_uri Browser's return URL after completion of 3-D Secure. Up to 256 half-width characters.
* http_user_agent Set the browser's HTTP User-Agent header.
* http_accept Set the browser's HTTP Accept header.
with_capture Set simultaneous authorise/capture or not by using a Boolean value. When not set, authorization will be executed. When set to true, capture and authorization will execute together.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.
jpo Set the Installment option for the payment. Default value is one time payment.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new VtDirect\Client\Request\Account\AccountMpiChargesParameter();
$input->order_id = "TEST1008";
$input->account_id = "TestAccount0004";
$input->card_id = "ABCDE123456789ABCDEFGHIJK";
$input->gross_amount = 1980;
$input->service_option_type = "mpi-merchant";
$input->push_uri = "https://example.com/push_receive";
$input->redirection_uri = "https://example.com/complete";
$input->http_user_agent = "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko";
$input->http_accept = "text/html, application/xhtml+xml, */*";
$api = new VtDirect\Client\AccountMpiCharges($setting);
$response = $api->AccountMpiCharge($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::Account::AccountMpiChargesParameter.new
input.order_id = 'TEST1008'
input.account_id = 'TestAccount0004'
input.card_id = 'ABCDE123456789ABCDEFGHIJK'
input.gross_amount = 1980
input.service_option_type = 'mpi-complete'
input.push_uri = 'https://example.com/push_receive'
input.redirection_uri = 'https://example.com/complete'
input.http_user_agent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko'
input.http_accept = 'text/html, application/xhtml+xml, */*'
api = VtDirect::AccountMpiCharges.new setting
response = api.account_mpi_charge input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
AccountMpiChargeRequest input = new AccountMpiChargeRequest();
input.setOrderId("TEST1011");
input.setAccountId("TestAccount0004");
input.setCardId("ABCDE123456789ABCDEFGHIJK");
input.setGrossAmount(1980);
input.setServiceOptionType("mpi-merchant");
input.setPushUri("https://example.com/push_receive");
input.setRedirectionUri("https://example.com/complete");
input.setHttpAccept("text/html, application/xhtml+xml, */*");
input.setHttpUserAgent("Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko");
AccountMpiCharges api = new AccountMpiCharges(clientConfiguration);
MpiChargeResponse response = api.accountMpiCharge(input);

Request Example

{
    "order_id": "TEST1008",
    "account_id": "TestAccount0004",
    "card_id": "ABCDE123456789ABCDEFGHIJK",
    "gross_amount": 1980,
    "service_option_type": "mpi-complete",
    "push_uri": "https://example.com/push_receive",
    "redirection_uri": "https://example.com/complete",
    "http_user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
    "http_accept": "text/html, application/xhtml+xml, */*"
}

Details upon successful response.

{
  "data": {
    "order_id": "TEST1008",
    "account_id": "TestAccount0004",
    "gross_amount": 1980,
    "with_capture": false,
    "service_option_type": "mpi-complete",
    "response_contents": "\u003c!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 ....(abbr",
    "res_corporation_id": "05",
    "res_brand_id": "5"
  },
  "mstatus": "success",
  "vresult_code": "G001H00100000000",
  "code": "Q000",
  "status": "success",
  "message": "mpi authorize request was successful"
}

Sales Processing (/capture)

API to capture the authorized funds with Order Id specified during authorization.
Sales are performed with the amount at the time of credit obtainment.

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/capture
Request parameter should be set in JSON Body.

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body *…Required

* order_id Specify the same OrderId that was specified when the authorization was performed on Charges API.
amount Specify the amount to be capture. Amount should be less than the amount at the time of authorization. When it's not specified, amount specified at the time of authorization will be captured.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\CaptureParameter();
$input->order_id = "TEST0005";
$api = new \VtDirect\Client\Capture($setting);
$response = $api->CaptureOrder($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::CaptureParameter.new
input.order_id = 'TEST0040'
api = VtDirect::Capture.new setting
response = api.capture_order input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
CaptureRequest input = new CaptureRequest();
input.setOrderId("TEST0050");
Capture api = new Capture(clientConfiguration);
CaptureResponse response = api.captureOrder(input);

Request Example

Create the JSON request like below.
{
  "order_id": "TEST0001"
}

Details upon successful response.

In normal case

{
  "data": {
    "order_id": "TEST0001",
    "transaction_status": "capture"
  },
  "vresult_code": "A001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Success do capture transaction"
}

Contents of unsuccessful response

In case of trying "Capture" twice.

{
  "vresult_code": "NH18000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[This order is already captured]",
  "errors": [
    "This order is already captured"
  ]
}

In case of trying "Capture" the order that has been already cancelled.

{
  "vresult_code": "NH02000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[Order invalid]",
  "errors": [
    "Order invalid"
  ]
}

In case of try to Capture the order that order doesn't exist.

{
  "code": "Q001",
  "status": "failure",
  "message": "[Order not found]",
  "errors": [
    "Order not found"
  ]
}

Search Payment Transaction Information (/search)

By setting Order Id, an API that retrieves payment transaction information.

Uri

Set the request to GET at the following URL.
https://api.veritrans.co.jp/vtdirect/v2/search?order_id={order_id}

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
Set the Base64 encoded Server Key to {base64encoded_server_key}.

Request Body

When searching for 3-D Secure results, use Request Id. At other times, use Order Id.
order_id Set the Order Id for the order that you applies to the payment transaction information.
request_id Set the Request Id for the key item to retrieve 3-D Secure result.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\SearchParameter();
$input->order_id = "TEST0011";
$api = new \VtDirect\Client\Search($setting);
$response = $api->GetOrderTransactionInfo($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::SearchParameter.new
input.order_id = 'TEST0011'
api = VtDirect::Search.new setting
response = api.get_order_transaction_info input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
SearchRequest input = new SearchRequest();
input.setOrderId("TEST1011");
Search api = new Search(clientConfiguration);
SearchResponse response = api.getOrderTransactionInformation(input);

Request Example

"https://api.veritrans.co.jp/vtdirect/v2/search?order_id=TEST0011"

Details upon successful response

In normal case

{
  "order_info": {
    "order_id": "TEST0011",
    "service_type_code": "mpi",
    "last_success_command": "Capture",
    "success_detail_transaction_type": "pa",
    "proper_order_info": {},
    "memo1": "memo",
    "free_key": "keyinfo",
    "transaction_info_array": [
      {
        "amount": 100,
        "command": "Authorize",
        "mstatus": "success",
        "vresult_code": "G001H00100000000",
        "transaction_datetime": "2014-12-16 12:06:21.048",
        "properTransactionInfo": {
          "transaction_kind": "mpi",
          "transaction_type": "auth",
          "corporation_id": "05",
          "res_3d_message_version": "1.0.2"
        }
      },
      {
        "amount": 100,
        "command": "Verify",
        "mstatus": "success",
        "vresult_code": "G011A00100000000",
        "transaction_datetime": "2014-12-16 12:06:46.74",
        "properTransactionInfo": {
          "transaction_kind": "mpi",
          "transaction_type": "vd",
          "res_3d_cavv": "OTg3NjU0MzIxMDk4NzY1NDMyMT\u003d\u003d",
          "res_3d_cavv_algorithm": "2",
          "res_3d_eci": "05",
          "res_3d_message_version": "1.0.2",
          "res_3d_transaction_id": "MDEyMzQ1Njc4OT\u003dxMjM0NTY3ODk\u003d",
          "res_3d_transaction_status": "Y"
        }
      },
      {
        "amount": 100,
        "command": "Verify",
        "mstatus": "success",
        "vresult_code": "G011A00100000000",
        "transaction_datetime": "2014-12-16 12:06:46.932",
        "properTransactionInfo": {
          "transaction_kind": "card",
          "res_auth_code": "000000",
          "res_center_error_code": "   "
        }
      },
      {
        "amount": 100,
        "command": "Capture",
        "mstatus": "success",
        "vresult_code": "A001000000000000",
        "transaction_datetime": "2014-12-18 14:46:10.94",
        "properTransactionInfo": {
          "transaction_kind": "card",
          "res_auth_code": "000000",
          "res_center_error_code": "   "
        }
      }
    ]
  },
  "vresult_code": "N001000000000000",
  "mstatus": "success",
  "code": "Q000",
  "status": "success",
  "message": "Search request was successful"
}

Contents of unsuccessful response

In case the specifying order that doesn't exist.

{
  "vresult_code": "N001000000000000",
  "mstatus": "success",
  "code": "Q001",
  "status": "failure",
  "message": "[such an order was not found]",
  "errors": ["such an order was not found"]
}

Cancellation of Payment (/void)

API to cancel the credit card authorization, credit card authorization with capture and convenience store payment of the specified Order Id

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/void

Request Parameter

Request Headers

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key} Set base 64 encoded Server Key.

Request Body *…Required

* order_id Specify OrderId of the order to be cancelled.
amount Specify the amount for cancellation. Partial refund for credit card is possible. Specify the amount less than that of Capture amount. When it's not specified, whole amount will be cancelled.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\VoidParameter();
$input->order_id = "TEST0011";
$api = new \VtDirect\Client\Cancel($setting);
$response = $api->VoidOrder($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::VoidParameter.new
input.order_id = 'TEST0040'
api = VtDirect::Void.new setting
response = api.void_order input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
VoidRequest input = new VoidRequest();
String orderId = "TEST0052";
input.setOrderId(orderId);
Void api = new Void(clientConfiguration);
VoidResponse response = api.voidOrder(input);

Request Example

Create the JSON request like below.
{
  "order_id": "TEST0002"
}

Contents of successful response

In normal case

{
  "data": {
    "order_id": "TEST0002",
    "transaction_status": "cancel"
  },
  "vresult_code": "A001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Success do void transaction"
}

Contents of unsuccessful response

When try to cancel the order that was already cancelled.

{
  "vresult_code": "NH18000000000000",
  "code": "Q001",
  "status": "failure",
  "message": "[This order is already cancelled]",
  "errors": [
    "This order is already cancelled"
  ]
}

Issue of Token (/tokens)

Token Id can be obtained by sending credit card information.
As normally the browser send credit card information to this API by veritrans.min.js it's not necessary to use this API from merchant websites' program at all.

Uri

Send the GET request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/tokens

Request Parameter

Request Body *…Required

* card_cvv Set the security code. 3 or 4 digit number.
* card_exp_month Set the month of credit card expiration date. 2 digit number.
* card_exp_year Set the year of credit card expiration year. 4 digit number.
* card_number Set the credit card number.
* client_key Set the Client Key.
callback In case veritrans.min.js calls this API, values will be set automatically and response will be in the form of JSONP. When callback is not specified, the response will be JSON.

PHP code

$setting = new \VtDirect\Client\Setting();
$input = new \VtDirect\Client\Request\TokensParameter();
$input->card_number = "4111111111111111";
$input->card_exp_month = "12";
$input->card_exp_year = "2018";
$input->card_cvv = "1234";
$input->client_key = "bbbbbbbb-2222-cccc-3333-eeeeeeeeeeee";
$tokens = new \VtDirect\Client\Tokens($setting);
$response = $tokens->GetToken($input);

Ruby code

setting = VtDirect::Setting.new
tokens = VtDirect::Tokens.new setting
response = tokens.get_token(
    'bbbbbbbb-2222-cccc-3333-eeeeeeeeeeee',
    '4111111111111111', '2018', '12', '123')

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
TokenRequest input = new TokenRequest();
input.setClientKey("bbbbbbbb-2222-cccc-3333-eeeeeeeeeeee");
input.setCardNumber("4111111111111111");
input.setCardExpireYear("2018");
input.setCardExpireMonth("12");
input.setCardCvv("123");
Tokens tokens = new Tokens(clientConfiguration);
TokenResponse response = tokens.getToken(input);

* The codes sample implementation on for merchant wesite side, but in principle, Tokens API is callback from veritrans.min.js

Request Example

"https://api.veritrans.co.jp/vtdirect/v2/tokens?card_number=4111111111111111&card_exp_month=08&card_exp_year=2015&card_cvv=123&client_key=bbbbbbbb-2222-cccc-3333-eeeeeeeeeeee&callback=json1"

Content of successful response

{
  "data": {
    "token_id": "abcdef12-1234-abcd-ef12-abcdef1234ab-411111-1111"
  },
  "code": "Q000",
  "status": "success",
  "message": "Success request new token"
}

* When Token Id is issued, token_id contains the first 6 digits and the last 4 digits of credit card number on its last part.

Content of unsuccessful response

In case client_key is not correct.

{
  "code": "Q001",
  "status": "failure",
  "message": "[Cannot find merchant]",
  "errors": [
    "Cannot find merchant"
  ]
}

In case card_number format is incorrect.

{
  "code": "Q001",
  "status": "failure",
  "message": "[Invalid card number]",
  "errors": [
    "Invalid card number"
  ]
}

Convenience Store Payment (/cvs)

Uri

Set the request parameter in JSON body and make a POST request to the following URL.
https://api.veritrans.co.jp/vtdirect/v2/cvs

Request Parameter

Request Header

Set the following headers as HTTP headers.
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key} Set base 64 encoded Server Key.

Request Body *…Required

* option_type "sej" : 7-Eleven
"econ" : LAWSON, FamilyMart, CircleKSunkus, MINISTOP, Seicomart
"other" : etc (Daily YAMAZAKI)
* order_id Set unique number for each payment. Valid characters are Half-width alphanumeric, hyphen and underscore, up to 100 characters in length.
* gross_amount Set payment amount between 1~300000.
* tel Set customer's telephone number in half-width between 10~11 digits without hyphen. Never use fixed value.
* name1 Set customer's full width last name with maximum size 20 byte. Letters available are below :
ー,々,ヽ,ヾ,ゝ,ゞ,〃,〆
Numbers, alphabet, Hira-gana, Kata-kana, Level 1 Kanji, Level 2 Kanji
* name2 Set consumers' full width first name with maximum size 20 bytes. Other restrictions are same as name1 parameter.
pay_limit Set due date for payment in 8half-width numbers in format yyyymmdd.
When option _type parameter value is set as "sej" then pay_limit can vary from same day till 150 days later.
When option _type parameter value is set "econ", then pay_limit can vary from same day till 60 days later.
If not specified, default value is applied.
test_mode Sets Boolean value to run either dummy or real transaction. Set to "true" during testing.
memo1 Set a memo for order. Up to 100 characters in length.
free_key Set a key information etc for order. Valid characters are Half-width alphanumeric, up to 256 characters in length.

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\CvsParameter();
$input->order_id = "TEST0014";
$input->gross_amount = 1980;
$input->name1 = 'テスト';
$input->name2 = 'タロウ';
$input->option_type = "sej";
$input->tel = '09000000000'; // Fixed Values not allowed
$api = new \VtDirect\Client\Cvs($setting);
$response = $api->PaymentAtCvs($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::CvsParameter.new
input.order_id = 'TEST0041'
input.gross_amount = 1980
input.name1 = 'テスト'
input.name2 = 'タロウ'
input.option_type = 'sej'
input.tel = '09000000000' # Fixed Values not allowed
api = VtDirect::Cvs.new setting
response = api.payment_at_cvs input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
CvsRequest input = new CvsRequest();
input.setOrderId("TEST0053");
input.setGrossAmount(1980);
input.setName1("テスト");
input.setName2("タロウ");
input.setOptionType("sej");
input.setTel("09000000000"); // Fixed Values not allowed
Cvs api = new Cvs(clientConfiguration);
CvsResponse response = api.paymentAtCvs(input);

Request Example

{
  "order_id": "TEST0013",
  "tel": "0900000000",
  "name1": "テスト",
  "name2": "タロウ",
  "gross_amount": 1980,
  "option_type": "sej"
}

Notification of deposit

POST Notification of deposit is sent to merchant website when deposit completion information (consumer's payment completion information) is received from payment center and deposit is considered to be completed.
Please refer to Changes in each type of URL for service setting method regarding notification URLs.
Parameter Detail
numberOfNotify Number of notifications
A single notification contains 1,000 records
For more than 1,000 records, please use another notification.
pushTime Notification time. (YYYYMMDDhhmmss)
pushId ID is incremented each time a PUSH notification is processed.
Maximum eight characters
The following parameters repeats for number of records in notification. Furthermore, a four digit sequential number (0000~9999) is appended to the end of the Field Name.
orderId Order Id specified when the order is sent.
Maximum 100 characters
cvsType Text to identify the convenience store where payment is performed.
"sej" : 7-Eleven
"econ-lw" : LAWSON
"econ-fm" : FamilyMart
"econ-mini" : MINISTOP
"econ-other" : SeicoMart
* In dummy transaction where "econ" is specified as option_type, fixed value "econ-lw" is returned.
"other" : etc (Daily YAMAZAKI)
receiptNo Text of receipt number
Maximum 32 Half-width letters and numbers.
receiptDate Date of completion of payment (YYYYMMDDhhmms)
rcvAmount Deposited amount
Maximum 6 digits numbers
dummy "1" in case of dummy transaction.

Content of successful response

{
  "data": {
    "order_id": "TEST0013",
    "gross_amount": 1980
  },
  "mstatus": "success",
  "vresult_code": "D001H00100000000",
  "url": "https://payment.sej.co.jp/od/hi.asp?HARAIKOMIXXXXXXXXXXXXX0000010001",
  "receipt_no": "2000000010001",
  "trad_url": "https://www.example.com/abcde;fghij;klmno",
  "code": "Q000",
  "status": "success",
  "message": "Success do cvs authorize transaction"
}

API Library

3G-Direct based on simple Web API, but API library with built in implementation for creating and sending the request can also be used.

PHP

Use the following PHP source code in your application.
3G-Direct-php
Support for PHP 5.4 or later. Enable SSL connection for https in cURL module of PHP.

Ruby

Use the following Ruby source code in your application.
3G-Direct-ruby
Support for Ruby 2.0 or later. Necessary to install the dependent RubyGem by Bundler.

Java

Use the following Java source code in your application.
3G-Direct-java
Support for JDK1.7. Necessary to install the dependency library by Maven. Groovy is used in some classes.