Introduction to 3G-Direct

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
- 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 modelVISA/
MASTERJCB AMEX DINERS One time 10 ○ ○ ○ ○ Not Specified Installment 61Cxx C=Installment option,
xx=No of Installments○ ○ ○ × Revolving 80 ○ ○ × ○
* 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
Server Key
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
For more detail, please refer to veritrans.min.js and Tokens API.
Error Handling
Below is the information for result decision.
Http Status Code
API library throws exception if Http Status Code is not 200.
code
status
message
Also contains information that which process is successful or the reason why the process was failed, etc.
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
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
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
<script src="https://api.veritrans.co.jp/vtdirect/v2/veritrans.min.js">
Sending 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)
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
https://api.veritrans.co.jp/vtdirect/v2/charges
Request Parameter
Request Header
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
{ "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
For Charges API, perform the page transition based on the response result and by referring the contents below.
mstatus
mstatus is success only when authorization and authorization with capture is successful.
mstatus | Indication |
---|---|
success | Success |
failure | Failure |
pending | Pending |
vresult_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 Account (/account)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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" ] }
{ "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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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
{ "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
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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request Header
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)
Sales are performed with the amount at the time of credit obtainment.
Uri
Request Parameter
Request Header
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
{ "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)
Uri
Request Parameter
Request Header
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)
Uri
Request Parameter
Request 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
{ "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)
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
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
Request Parameter
Request Header
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
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
PHP
3G-Direct-php
Support for PHP 5.4 or later. Enable SSL connection for https in cURL module of PHP.
Ruby
3G-Direct-ruby
Support for Ruby 2.0 or later. Necessary to install the dependent RubyGem by Bundler.
Java
3G-Direct-java
Support for JDK1.7. Necessary to install the dependency library by Maven. Groovy is used in some classes.