はじめに

Air-Directは、ECサイトにクレジットカード情報を送信することなく、容易なWeb APIを利用して決済を行うことのできる、新しいサービスです。

API エンドポイント

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

各APIのパス

  • /v1/veritrans.min.js
  • /v1/charges
  • /v1/recharges
  • /v1/creditcard/list
  • /v1/creditcard/destroy
  • /v1/capture
  • /v1/search
  • /v1/status
  • /v1/void
  • /v1/mpi_charges
  • /v1/tokens
  • /v1/cvs

用語集

本ドキュメントにて頻出する用語を以下に解説します。
マーチャント
Air-Directをご利用される事業者様を指します。
マーチャントサイト
事業者様が運営されるAir-Direct利用サイトのことを指します。
MAP
当社が提供する、マーチャント様向けの取引管理サイトのことを指します。
Air-Directで実施した決済はMAPにて取引検索を行うことで確認ができます。
API
Air-Directが提供するWeb APIを指します。
Air-Directの各機能は別々のURIに分かれており、利用したい機能のURIに対して、HTTPヘッダに認証情報、BODY部にパラメータをJSONシリアライズした文字列を指定し、GETやPOSTメソッドで送信することで処理が行われます。
処理結果もJSONで応答されますので、マーチャントサイトにて簡単に処理することが可能です。
APIライブラリ
Air-DirectのAPIにリクエストを送信するためのプログラムライブラリです。
API自体は容易な仕様になっておりますので、APIライブラリを利用せず、マーチャント様で独自に実装いただくことも可能です。
Client Key
Tokens APIを利用する際、要求パラメータに含める必要のある認証キー。HTMLやJavaScript上に記述して利用します。
Server Key
Tokens APIを除く、各APIを利用するための認証キー。HTTPヘッダにAuthorizationヘッダとして指定して利用します。重要な認証キーであるため、マーチャントサイトのサーバにのみ保存し、外部に漏らさないよう注意してください。
veritrans.min.js (veritrans.js)
カード情報をAir-Directに送信し、Token Idを取得するためのJavaScriptプログラムです。
マーチャントサイトのカード情報入力画面にて読み込み、関数にカード情報を渡すことで、ブラウザからAir-Directに直接カード情報が送信されます。
詳しい利用方法についてはveritrans.min.jsを参照ください。
トークン、Token Id
Tokens APIにカード情報を送信することで払い出される、英数ハイフンで構成された文字列です。
ランダムな36桁の文字と、クレジットカード番号の上6桁、下4桁で構成されます。Token Idはおよそ1分間有効であり、送信されたカード情報を識別するために必要なパラメータとなります。Charges APIでのみ利用しますが、一度送信すると失効し、再利用できません。
Order Id
Air-Directで決済を行うためには、マーチャントサイトで採番された一意の文字列をOrder Idとして、APIに送信する必要があります。
Order Idは後述のCapture API等で、Air-Directに登録された注文を識別するために必要なパラメータとなりますので、マーチャントサイト様のデータベースにて保存しておく必要があります。 多くの場合、マーチャントサイト側注文データベースのキー値をOrder Idとして利用できます。
Tokens API
Air-Directに一時的にカード情報を保持するためのAPIです。登録されたカード情報を識別するためのToken Idを応答します。
Charges API
クレジットカードでの与信または与信同時売上を実施するためのAPIです。
払い出されたToken Id、採番したOrder Id、決済金額の3つが最低限必要なパラメータとなります。
Token Idには有効期限がありますので、veritrans.min.jsにてブラウザがToken Idを取得したら即座にマーチャントサイトに送信し、Charges APIで決済を実施してください。
また、カード情報を再入力せず決済を行えるようにするためには、Charges APIにてオプションパラメータを指定し、マーチャントサイト側会員の紐づけを行う必要があります。
ReCharges API
過去の決済情報を利用し、再取引を行うことでカード情報を再入力せず決済を実施するためのAPIです。
後述のRegister Idを指定することで実施でき、カード情報を再度入力する必要がありません。
MAPから取引検索を行い、再取引を実行することでも同様の決済を行うことが可能です。
Customer Id
ReCharges APIを利用する際、Charges APIにてCustomer Idをパラメータとして指定できます。
これにより、Customer Idをキーに登録済みのカード情報をCreditcard/list APIにて取り出すことが可能となります。 多くの場合、マーチャントサイト側会員データベースのキー値をCustomer Idとして利用できます。
Air-DirectはCustomer Idと、再取引のための過去の決済情報を1対多の関係で保管しますので、マーチャントサイトで枝番の管理を行う必要はありません。
Register Id
Charges APIにてregisterパラメータを指定し、決済に成功した際に払い出されるRegister IdをReCharges APIのパラメータとして指定する必要があります。
Creditcard/list APIにて、指定したCustomer Idに紐づくRegister Idおよびクレジットカードブランド等の情報を取得できますので、必ずしもマーチャントサイト側データベースにてRegister Idを保持する必要はありません。
 

認証処理

Air-DirectのAPIを利用するには、認証用のパラメータを設定する必要があります。

Server Key

Charges APIやCapture APIなど、マーチャントサイトのサーバからAPIにリクエストを送信するAPIについては、HTTPヘッダにてServer Keyを指定する必要があります。
Acceptヘッダ、Content-Typeヘッダに加えて、以下のようにAuthorization HTTPヘッダを追加してください。
ヘッダ名
Accept application/json
Content-Type application/json
Authorization Basic {Server KeyをBase64エンコードした文字列}

Client Key

Tokens APIはveritrans.min.jsを利用し、ブラウザからAir-Directにカード情報を送信するAPIであるため、Server KeyではなくClient Keyをパラメータに含める必要があります。
詳しくはveritrans.min.jsまたはTokens APIを参照してください。
 

エラー処理

マーチャントサイトはAPIの応答結果から決済が成功したかどうか判定し、画面遷移等を制御する必要があります。
応答結果を判定するための情報を以下に記載します。

Http Status Code

応答結果のHttp Status Codeが200であることをまずは確認してください。
APIライブラリでは、Http Status Codeが200でなかった場合、例外をスローします。

code

応答結果のJSONには必ずcodeが含まれます。詳細は右の応答code一覧を参照してください。

status

応答結果のJSONには必ずstatusが含まれます。詳細は右の応答status一覧を参照してください。

message

応答結果のJSONには必ずmessageが含まれます。
どのような処理に成功したか、または何が原因で失敗したか、といった情報が含まれます。

errors

パラメータ不備や与信の失敗など、codeがQ001となった場合はerrorsに失敗原因が含まれます。
messagesに含まれるものと内容は同じですが、パラメータ不備が複数あった場合等は、errorsにString配列で失敗原因が一つずつ格納されます。

タイムアウトについて

通常は数秒で応答しますが、決済処理は2分が上限となっているため、 APIへの要求のタイムアウトは130秒程度を設定してください。

応答パターン

code 意味
Q000
処理が成功した場合。
Q001
送信パラメータに不備があった場合や、検証ができなかった場合。また、決済が失敗した場合。
Q002
veritrans.min.jsを利用してTokens APIにカード情報を送信する際、Client Keyが空だった場合。
Q099
Air-Directにて想定外のエラーが発生した場合。
status 意味
success
codeがQ000の場合
failure
codeがQ001の場合
fatal
codeがQ099の場合
transaction_type
(カード決済)
意味
init
エラー発生時
a
与信
ax
与信(期限切れ)
ac
与信売上
pa
売上
va,rad,rae
与信→取消
vac,racd,race
与信売上→取消
vpa,rpad,rpae
売上→取消
transaction_type
(コンビニ決済)
意味
authorize
申込完了(失敗含む)
cancel_authorize
キャンセル済み
fix_capture
入金済み

failureエラーサンプル

failureエラーが発生した場合の応答JSONのサンプルです。
{
  "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エラーサンプル

fatalエラーが発生した場合の応答JSONです。
{
  "code": "Q099",
  "status": "fatal",
  "message": "Fatal error, please contact veriTrans"
}

veritrans.min.js

Air-Directで決済を行うには、まずTokens APIにカード情報を送信し、Token Idを取得する必要があります。
通常はマーチャントサイトに用意したカード情報入力画面にて、入力された情報をveritrans.min.jsのメソッドを利用し、ブラウザから直接Tokens APIに送信します。

読み込み

カード情報入力画面のscriptタグにて、Air-Direct上のveritrans.min.jsを読み込むよう記述してください。
<script src="https://air.veritrans.co.jp/vtdirect/v1/veritrans.min.js">

カード情報送信

Veritrans.tokenGet関数で、カード情報を送信するコードを記述してください。
// Client Keyをセット
Veritrans.client_key = "Client Key";

function _error(d) {
  var message = d.message;
  // 失敗時のナビゲーションを行うコードを記述
}

function _success(d) {
  var token_id = d.data.token_id;
  // 取得したToken Idをマーチャントサイトに送信するコードを記述
}

function _cardSet() {
  return {
    "card_number": "カード番号", // 入力されたカード番号をセット
    "card_exp_month": "有効期限(MM)", // 入力された有効期限(月)をセット
    "card_exp_year": "有効期限(YYYY)", // 入力された有効期限(年)をセット
    "card_cvv": "セキュリティコード" // 入力されたセキュリティコードをセット
  }
}

// ボタンが押下されたらカード情報を送信するコードを記述
$("button.submit").bind("click", function () {
  Veritrans.tokenGet(_cardSet, _success, _error);
});

クレジットカード決済 (/charges)

Token Idを利用して決済を行うAPIです。
Token Idにはおよそ1分間の有効期限があるため、ブラウザからToken Idがマーチャントサイトに送信されたら、即座に本APIを利用してカード決済を実施する必要があります。
2回目以降、カード情報を入力しなくても決済できるようにするには、オプションのregisterパラメータおよびReCharges APIを利用してください。

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/charges

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* token_id Tokens APIによって払い出されたTokenIdを指定する。
* order_id 決済ごとにユニークな番号を指定する。利用可能文字は半角英数とハイフン、アンダースコアで100桁以内であること。
* gross_amount 決済金額を1~99999999で指定する。
with_capture 同時売上するかどうかをBooleanで指定する。指定しなかった場合は与信のみ実施する。trueを指定した場合は与信と同時に売上も行う。
register マーチャントサイト側会員に本決済の取引を紐づけるかどうかをBooleanで指定する。指定しなかった場合は紐づけしない。Trueを指定した場合は、本決済の取引IDをAir-Directに記録する。(決済が失敗した場合は記録しない)
customer_id マーチャントサイト側会員の識別ID(マーチャントが採番したもの)を指定する。RegisterにTrueを指定すれば、Customer Idを指定しなくてもRegister Idは払い出されるが、その場合はマーチャントで払い出されたRegister Idを保管する必要がある。
test_mode 決済をダミー取引とするかどうかをBooleanで指定する。指定しなかった場 合は本取引となり、ダミー取引とならない。テスト時はtrueを指定すること。

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 = "1c0cc4c0-9973-40db-bf81-8caf5349037d-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 = 'c4a94573-3b03-4289-be1a-bb4d8dbcce04-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("3d499de5-b009-47b2-a331-2d9b2a00b288-411111-1111");
ChargeResponse response = api.ChargeWithToken(input);
            

リクエストサンプル1

以下のようなJSONをリクエスト本文に記述する。
{
  "token_id": "7caebe94-b39c-4468-aad0-4da4e42648a8-411111-1111",
  "order_id": "TEST0001",
  "gross_amount": 1980
}
        

リクエストサンプル2

2回目以降の決済のためにマーチャントサイト側会員と決済を紐づけるためには、以下のようなJSONをリクエスト本文に記述する。
{
  "token_id": "64761c74-3b1c-4d73-b6e9-18d0bf721db7-411111-1111",
  "order_id": "TEST0002",
  "register": true,
  "customer_id": "C0001",
  "gross_amount": 1980
}
        

成功時のレスポンスの内容

register無効時

{
  "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"
}
        

register有効時

{
  "data": {
    "order_id": "TEST0005",
    "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",
  "register_id": "3a582e5c-4d68-47c5-861e-74bb1b50a05d1384309014",
  "customer_id": "C0001",
  "code": "Q000",
  "status": "success",
  "message": "Success do charge transaction"
}
        

※customer_idにはcharge要求時に指定した文字列が入る。

カード決済処理エラー

カード決済では様々な要因により、与信が失敗することがあります。
Charges APIやReCharges APIでは以下の記載内容を参考に、応答結果により画面遷移等の制御を実装してください。

mstatus

処理結果コードが入ります。mstatusには以下の3種類があります。
与信または与信同時売上に成功した場合のみ、successとなります。
mstatus 意味
success 正常終了
failure 異常終了
pending 保留

vresult_code

詳細結果コードが入ります。
mstatusがsuccessにならなかった場合の主なエラーコードとその原因を以下に記載します。
必要に応じてナビゲーションを表示するよう実装してください。
vresult_code上4桁 原因
AG33 カード使用不可。
AG39 取引判定保留(有人判定)です。
AG41 セキュリティコード誤りです。
AG44 1口座利用回数または金額オーバーです。
AG45 1日限度額オーバーです。
AG46 クレジットカードが無効です。
AG47 事故カードです。
AG48 無効カードです。
AG49 会員番号エラーです。
AG51 金額エラーです。
AG61 支払い区分エラーです。
AG64 有効期限エラーです。
AG70 当該要求拒否です。
AG71 当該自社対象業務エラーです。
AG72 接続要求自社受付拒否です。
ACD6 元取引が存在しません。

失敗時のレスポンスの内容

Token有効期限切れ

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

OrderID重複時

{
  "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"
  ]
}

カードエラー

{
  "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"
  ]
}

クレジットカード再取引決済 (/recharges)

カード情報の再入力をせず、Register Idを利用して決済を行うAPIです。
Charges APIにてオプションのregisterパラメータおよびCustomer Idパラメータを指定して決済を行うことで、Customer Idに紐づくRegister Idが払い出されます。
Customer Idに紐づくRegister Idおよびカード情報を取得するにはCreditcard/list APIを利用してください。

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/recharges

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* order_id 決済ごとにユニークな番号を指定する。利用可能文字は半角英数とハイフン、アンダースコアで100桁以内であること。
* register_id Chargesにて、registerパラメータをtrueとして決済した場合に払い出されるIDを指定する。
* gross_amount 決済金額を1~99999999で指定する。
with_capture 同時売上するかどうかをBooleanで指定する。指定しなかった場合は与信の み実施する。trueを指定した場合は与信と同時に売上も行う。

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\ReChargesParameter();
$input->register_id = "3a582e5c-4d68-47c5-861e-74bb1b50a05d1384309014";
$input->order_id = "TEST0009";
$input->gross_amount = 1980;
$charges = new \VtDirect\Client\ReCharges($setting);
$response = $charges->ReChargeWithRegisterId($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::ReChargesParameter.new
input.order_id = 'TEST0032'
input.gross_amount = 1980
input.register_id = 'bd7067e7-275e-47d4-b7e1-8986ee897caf1384337330'
api = VtDirect::ReCharges.new setting
response = api.re_charge_with_register_id input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
ReChargeRequest input = new ReChargeRequest();
input.setOrderId("TEST0052");
input.setGrossAmount(1980);
input.setRegisterId("8e5456ed-966a-44fb-bb69-d4b0a377bed21384413841");
ReCharges api = new ReCharges(clientConfiguration);
ReChargeResponse response = api.ReChargeWithRegisterId(input);

リクエストサンプル

以下のようなJSONをリクエスト本文に記述する。
{
  "order_id": "TEST0007",
  "register_id": "3a582e5c-4d68-47c5-861e-74bb1b50a05d1384309014",
  "gross_amount": 1980
}
        

成功時のレスポンスの内容

{
  "data": {
    "order_id": "TEST0007",
    "gross_amount": 1980,
    "with_capture": false
  },
  "mstatus": "success",
  "vresult_code": "A001000000000000",
  "transaction_type": "a",
  "pending": "0",
  "acquirer_code": "05",
  "register_id": "3a582e5c-4d68-47c5-861e-74bb1b50a05d1384309014",
  "customer_id": "C0001",
  "trad_url": "https://www.example.com/abcde;fghij;klmno",
  "code": "Q000",
  "status": "success",
  "message": "Success do recharge transaction"
}
        

カード決済処理エラー

ReCharges APIの場合も、Charges APIと同様のカード決済エラーが発生する場合があります。
また、400日を経過した取引データは削除されるため、Charges/ReCharges APIで決済に成功した取引が古い場合は、決済に失敗する場合があります。
応答結果がエラーであった場合の制御はCharges API同様に実装してください。

失敗時のレスポンスの内容

OrderID重複時

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

指定されたRegisterIDで登録が見つからなかった場合

{
  "code": "Q001",
  "status": "failure",
  "message": "[No such credit card bind]",
  "errors": [
    "No such credit card bind"
  ]
}

カード情報管理 (/creditcard)

カード情報一覧取得 (Creditcard/list)

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/creditcard/list

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* customer_id マーチャントサイト側会員の識別IDを指定。

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\CreditCardListParameter();
$input->customer_id = "C0001";
$api = new \VtDirect\Client\CreditCardList($setting);
$response = $api->ListCreditCardBind($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::CreditCardListParameter.new
input.customer_id = 'C0002'
api = VtDirect::CreditCardList.new setting
response = api.list_credit_card_bind input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
CreditCardListRequest input = new CreditCardListRequest();
input.setCustomerId("C0006");
CreditCardList api = new CreditCardList(clientConfiguration);
CreditCardListResponse response = api.ListCreditCardBind(input);

リクエストサンプル

以下のようなJSONをリクエスト本文に記述する。
{
  "customer_id": "C0001"
}

成功時のレスポンスの内容

{
  "cards": [
    {
      "register_id": "414264f0-87da-4bba-8da8-25df92fd35dc1384314166",
      "brand": "MASTER",
      "last4": "4444",
      "original_order_id": "TEST0010",
      "last_updated": "2013-11-13 12:40:08",
      "customer_id": "C0001"
    },
    {
      "register_id": "3a582e5c-4d68-47c5-861e-74bb1b50a05d1384309014",
      "brand": "VISA",
      "last4": "1111",
      "original_order_id": "TEST0009",
      "last_updated": "2013-11-13 11:40:16",
      "customer_id": "C0001"
    }
  ],
  "customer_id": "C0001",
  "code": "Q000",
  "status": "success",
  "message": "Success do query credit card list"
}

カード情報削除 (Creditcard/destroy)

指定したRegister Idで紐づけられたカード情報を削除するAPIです。

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/creditcard/destroy
要求パラメータはJSONでBodyに記述すること。

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* register_id register有効時にAir-Directから払い出された識別ID。

PHP code

$setting = new \VtDirect\Client\Setting();
$setting->SetServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
$input = new \VtDirect\Client\Request\CreditCardDestroyParameter();
$input->register_id = "3a582e5c-4d68-47c5-861e-74bb1b50a05d1384309014";
$api = new \VtDirect\Client\CreditCardDestroy($setting);
$response = $api->DestroyCreditCardBind($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::CreditCardDestroyParameter.new
input.register_id = 'bd7067e7-275e-47d4-b7e1-8986ee897caf1384337330'
api = VtDirect::CreditCardDestroy.new setting
response = api.destroy_credit_card_bind input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
CreditCardDestroyRequest input = new CreditCardDestroyRequest();
input.setRegisterId("8e5456ed-966a-44fb-bb69-d4b0a377bed21384413841");
CreditCardDestroy api = new CreditCardDestroy(clientConfiguration);
CreditCardDestroyResponse response = api.DestroyCreditCardBind(input);

リクエストサンプル

以下のようなJSONをリクエスト本文に記述する。
{
  "register_id": "414264f0-87da-4bba-8da8-25df92fd35dc1384314166"
}

成功時のレスポンスの内容

{
  "customer_id": "C0001",
  "register_id": "414264f0-87da-4bba-8da8-25df92fd35dc1384314166",
  "code": "Q000",
  "status": "success",
  "message": "Success do destroy credit card bind"
}

失敗時のレスポンスの内容

登録されていないregister_idを指定した場合

{
  "register_id": "414264f0-87da-4bba-8da8-25df92fd35dc1384314166",
  "code": "Q001",
  "status": "failure",
  "message": "[No such credit card bind]",
  "errors": [
    "No such credit card bind"
  ]
}

売上処理 (/capture)

Order Idを指定して、与信済みの決済を売上するAPIです。
与信取得時の金額で売上が行われます。

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/capture
要求パラメータはJSONでBodyに記述すること。

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* order_id Charges APIにて与信を行った際に指定したOrder Idを指定する。
amount 売上金額を与信時の金額以下の数値で指定する。未指定時は与信金額が売上金額となる。

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.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
CaptureRequest input = new CaptureRequest();
input.setOrderId("TEST0050");
Capture api = new Capture(clientConfiguration);
CaptureResponse response = api.CaptureOrder(input);

リクエストサンプル

以下のようなJSONをリクエスト本文に記述する。
{
  "order_id": "TEST0001"
}

成功時のレスポンスの内容

正常時

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

失敗時のレスポンスの内容

2回Captureしようとした場合

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

キャンセル済みの注文をCaptureしようとした場合

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

存在しない注文をCaptureしようとした場合

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

決済トランザクション情報取得 (/search)

Order Idを指定して、決済のトランザクション情報を取得するAPIです。

Uri

以下のURLへGETで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/search?order_id={order_id}

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文

本人認証結果取得時はRequest Idのみ指定、それ以外の場合はOrder Idのみ指定する
order_id 決済トランザクション情報を取得する対象の注文のOrder Idを指定する。
request_id 本人認証結果を取得するためのキー項目であるRequest Idを指定する。
test_mode ダミー取引を検索する場合はTrueを指定する。

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 settings
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);

リクエストサンプル

"https://air.veritrans.co.jp/vtdirect/v1/search?order_id=TEST0011"

成功時のレスポンスの内容

正常時

{
  "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"
}

失敗時のレスポンスの内容

存在しないオーダーIDを指定した場合

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

決済状況取得 (/status)

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/status
要求パラメータはJSONでBodyに記述すること。

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* order_id 決済トランザクション情報を取得する対象の注文のOrder Idを指定する。

PHP code

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

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
input = VtDirect::Request::StatusParameter.new
input.order_id = 'TEST0031'
api = VtDirect::Status.new setting
response = api.get_order_status input

Java code

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setServerKey("aaaaaaaa-1111-ffff-bbbb-000000000000");
StatusRequest input = new StatusRequest();
String orderId = "TEST0052";
input.setOrderId(orderId);
Status api = new Status(clientConfiguration);
StatusResponse response = api.GetOrderStatus(input);

リクエストサンプル

以下のようなJSONをリクエスト本文に記述する。
{
  "order_id": "TEST0011"
}

成功時のレスポンスの内容

正常時

{
  "data": {
    "order_id": "TEST0011",
    "service_type_code": "card",
    "order_status": "end",
    "last_success_transaction_type": "Authorize",
    "success_detail_transaction_type": "a",
    "amount": 1980,
    "transaction_type": "a",
    "gateway_request_date": "2013-11-13 15:41:37",
    "gateway_response_date": "2013-11-13 15:41:37",
    "pending": "0",
    "auth_code": "000000",
    "action_code": "000"
  },
  "vresult_code": "N001000000000000",
  "code": "Q000",
  "status": "success",
  "message": "Success search card order transaction"
}

失敗時のレスポンスの内容

存在しないオーダーIDを指定した場合

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

決済のキャンセル (/void)

Order Idを指定して、カード与信済み、カード売上済み、コンビニ決済をキャンセルするAPIです。

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/void

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* order_id キャンセルを行う注文のOrder Idを指定する。
amount カード売上の一部キャンセル金額を指定する。売上金額以下の数値を指定する必要がある。未指定時は全額取消となる。

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\Void($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);

リクエストサンプル

以下のようなJSONをリクエスト本文に記述する。
{
  "order_id": "TEST0002"
}

成功時のレスポンスの内容

正常時

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

失敗時のレスポンスの内容

キャンセル済みの注文をキャンセル

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

本人認証決済 (/mpi_charges)

本人認証を実施後、決済および各種処理を行います。
下記APIの応答結果にて、statusがsuccessだった場合はresponse_contentsを印字し、ブラウザを本人認証フローにリダイレクトさせてください。

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/mpi_charges

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* order_id 決済ごとにユニークな番号を指定する。利用可能文字は半角英数とハイフン、アンダースコアで100桁以内であること。
* token_id Tokens APIによって払い出されたTokenIdを指定する。
* gross_amount 決済金額を1~99999999で指定する。
* service_option_type 次のどれかを指定する。
"mpi-complete":完全認証
"mpi-company":通常認証(カード会社リスク負担)
push_uri 本人認証結果Push通知の送信先マーチャントサイトURLを指定する。半角256桁以内であること。
* redirection_uri ブラウザの戻り先マーチャントサイトURLを指定する。半角256桁以内であること。
* http_user_agent ブラウザのHTTP User-Agentヘッダを指定する。
* http_accept ブラウザのHTTP Acceptヘッダを指定する。
with_capture 同時売上するかどうかをBooleanで指定する。指定しなかった場合は与信のみ実施する。trueを指定した場合は与信と同時に売上も行う。
test_mode 決済をダミー取引とするかどうかをBooleanで指定する。指定しなかった場 合は本取引となり、ダミー取引とならない。テスト時はtrueを指定すること。
memo1 取引に関するメモ情報を指定する。100文字以内であること。
free_key 取引に関するキー情報(マーチャント様にて別途管理しているID等)を指定する。半角英数で2560桁以内であること。

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

リクエストサンプル

{
    "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, */*"
}

成功時のレスポンスの内容

{
  "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 ....(省略",
    "res_corporation_id": "05",
    "res_brand_id": "5"
  },
  "mstatus": "success",
  "vresult_code": "G001H00100000000",
  "code": "Q000",
  "status": "success",
  "message": "mpi authorize request was successful"
}

失敗時のレスポンスの内容

本人認証実行不可(イシュアまたは会員が未参加)

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

トークン発行 (/tokens)

カード情報を送信することで、Token Idを払い出します。
通常はveritrans.min.jsにより、ブラウザから本APIにカード情報が送信されますので、マーチャントサイト側プログラムから本APIを利用することはありません。

Uri

以下のURLへGETで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/tokens

リクエストパラメータ

リクエスト本文 *…必須

* card_cvv セキュリティコードを指定する。3~4ケタ数字。
* card_exp_month カード有効期限の月を指定する。2桁数字。
* card_exp_year カード有効期限の年を指定する。4桁数字。
* card_number カード番号を指定する。
* client_key Client Keyを指定する。
callback veritrans.min.jsから本APIが呼び出された場合は自動的に値がセットされ、応答形式がJSONPになります。callbackを指定しない場合は、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);

※上記コードはマーチャントサイト側での実装サンプルですが、Tokens APIは原則としてveritrans.min.jsから利用されるAPIとなります。

リクエストサンプル

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

成功時のレスポンスの内容

{
  "data": {
    "token_id": "8ebec161-b054-4d31-83a1-4b58de696f89-411111-1111"
  },
  "code": "Q000",
  "status": "success",
  "message": "Success request new token"
}

※正常にTokenIdが払い出された場合は、token_idの最後にカード番号の上6桁と下4桁が付与されます。

失敗時のレスポンスの内容

client_keyが正しくない

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

card_numberの書式が正しくない

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

コンビニ決済 (/cvs)

Uri

要求パラメータをJSONでBodyに記述し、以下のURLへPOSTで要求を行ってください。
https://air.veritrans.co.jp/vtdirect/v1/cvs

リクエストパラメータ

リクエストヘッダ

HTTPヘッダとして、以下のヘッダを指定すること。
Accept application/json
Content-Type application/json
Authorization Basic {base64encoded_server_key}
{base64encoded_server_key}には、Base64エンコードしたServer Keyを指定する。

リクエスト本文 *…必須

* option_type セブンイレブンを利用する場合は"sej"を指定し、ローソン・ファミリーマート・ミニストップ・セイコーマート・サークルKサンクスのどれかを利用する場合は"econ"を指定する。
* order_id 決済ごとにユニークな番号を指定する。利用可能文字は半角英数とハイフン、アンダースコアで100桁以内であること。
* gross_amount 決済金額を1~300000で指定する。
* tel 顧客電話番号を半角数字10~11桁で指定する。ハイフンは不可。固定値としないこと。
* name1 顧客姓を全角20バイトで指定する。利用可能な文字は以下の通り。
長音符 ー 同の字点 々 一の字点 ヽ ヾ ゝ ゞ ノノ字点 〃 しめ 〆
数字・アルファベット、平仮名、カタカナ、第一水準漢字、第二水準漢字
* name2 顧客名を全角20バイトで指定する。利用可能な文字はname1パラメータと同様。
pay_limit 支払有効期限を半角数字8桁、yyyymmddの形式で指定する。
option_typeパラメータに"sej"を指定した場合は当日~150日後を指定可能。
"econ"を指定した場合は当日~60日後を指定可能。
未指定の場合は既定値が利用される。
test_mode 決済をダミー取引とするかどうかをBooleanで指定する。指定しなかった場 合は本取引となり、ダミー取引とならない。テスト時はtrueを指定すること。

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'; //固定値不可
$api = new \VtDirect\Client\Cvs($setting);
$response = $api->PaymentAtCvs($input);

Ruby code

setting = VtDirect::Setting.new
setting.server_key = 'aaaaaaaa-1111-ffff-bbbb-000000000000'
setting.ca_cert_path = 'D:\\cacert.pem'
input = VtDirect::Request::CvsParameter.new
input.order_id = 'TEST0041'
input.gross_amount = 1980
input.name1 = 'テスト'
input.name2 = 'タロウ'
input.option_type = 'sej'
input.tel = '09000000000'
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");
Cvs api = new Cvs(clientConfiguration);
CvsResponse response = api.PaymentAtCvs(input);

リクエストサンプル

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

入金通知

決済センターからの入金完了情報(消費者の支払完了情報)を受け取り、該当の入金が完了したと判断した場合にマーチャントサイトに入金通知をPOST送信します。
通知先URLはサービス設定より確認ください。
パラメータ 詳細
numberOfNotify 通知数
1回の入金完了情報に含まれる通知件数は最大1000件
1001件以上は次回通知となる
pushTime 通知した日時(YYYYMMDDhhmmss)
pushId 通知が送信されるたびに採番されるID
最大8文字
通知件数分下記の項番を繰り返す。尚、フィールド名の後ろに4ケタの連番(0000~0999)を付与する。
orderId 注文申込時に指定されたOrder Id
最大100文字
cvsType 支払を行ったコンビニの識別文字列
"sej":セブン-イレブン
"econ-lw":ローソン
"econ-fm":ファミリーマート
"econ-mini":ミニストップ
"econ-other":セイコーマート
"econ-ck":サークルK
"econ-sn":サンクス
※option_typeとして"econ"を指定したダミー取引の場合は"econ-lw"固定となる。
receiptNo 受付番号文字列
半角英数記号で最大32文字
receiptDate 支払完了日(YYYYMMDDhhmmss)
rcvAmount 入金金額
数値で最大6桁
dummy ダミー取引の場合は"1"
コンビニ決済入金通知に対してECサイト側がHTTPステータスコード"200"を返戻した場合、ECサイトでの受信処理が正常に終了したものと判断します。ECサイト側よりHTTPステータスコード"200"以外のコードが返戻された場合は、受信失敗と判断し、一定期間通知を繰り返します。

HTTPS での結果通知受信を希望される場合は、ECサイト側設置サーバにてSSL 通信環境をご用意ください。SSL 証明書は認証局発行のものをご使用ください。
※自己署名(Self-Sign)のSSL 証明書はご利用できませんので、ご注意ください。

成功時のレスポンスの内容

{
  "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ライブラリ

Air-Directは容易なWeb APIとして作成されていますが、リクエストパラメータの作成や通信部分を実装したライブラリを利用することも可能です。

PHP

以下のPHPソースコードをシステムに組み込んでご利用ください。
Air-Direct-php
PHP 5.4以降対応。PHPのcURLモジュールにてSSL通信が可能である必要があります。

Ruby

以下のRubyソースコードをシステムに組み込んでご利用ください。
Air-Direct-ruby
Ruby 2.0以降対応。依存するRubyGemをBundlerでインストールする必要があります。

Java

以下のJavaソースコードをシステムに組み込んでご利用ください。
Air-Direct-java
JDK1.7対応。依存するライブラリをMavenでインストールする必要があります。一部のクラスにGroovyを利用しています。

エラーコード一覧

本システムでエラーが発生した場合に応答されるvresult_codeの一覧です。 クレジットカード決済での一般的なエラーについてはカード決済処理エラーを参照してください。

カード決済

vresult_code上4桁 原因
NH18 既に決済済みのOrder Idを指定してchargeを要求した場合
NH02 指定されたOrder Idの注文が既にキャンセルされているなど、取引の状態に問題がある場合
また、ダミー取引でテスト用として正しくないパラメータが指定された場合や、本番申込中の状態で本取引を実施した場合
AG** カード与信に失敗した場合
NH04 取引が重複
NH40 order idが他のサービスで使用済み
AC25 カード番号パラメータの書式が誤り
AC27 カード番号パラメータの値がディジットエラー
AC30 カード有効期限パラメータの書式が誤り
NH05 取引が処理中
NC06 無効なパラメータ
AE10 トランザクションが保留
ACD3 取引は期限切れ
ACD4 元取引は成功の状態ではない

コンビニ決済

vresult_code上4桁 原因
DC47, NH11 利用できないoption_typeパラメータを指定された場合
NC04, NC06 無効なパラメータが指定された場合
DC05 支払期限が有効期間外の場合
DC07 顧客名(カナ)に正しくない書式で指定された場合
DC08 支払期限に正しくない書式で指定された場合
DE05, DG37 テスト取引の決済条件が正しくない場合
DH15 ベリトランスゲートウェイ内でエラーが発生し、取引に失敗した場合
NH18 既に成功している
NH02 取引が無効の場合
また、ダミー取引でテスト用として正しくないパラメータが指定された場合や、本番申込中の状態で本取引を実施した場合
NH04 取引が重複
NH40 Order Idが他のサービスで使用済み
NH05 取引が処理中
DC06 無効なパラメータ
DC09 無効なパラメータ
DC10 オーダー決済状態が適切ではない
DC48 無効なパラメータ
DC49 無効なパラメータ
DG19 レシート発券中のためキャンセルに失敗
DH15 取引に失敗

売上処理

vresult_code上4桁 原因
NH18 指定されたOrder Idの注文が既に計上されていた場合
NH02 指定されたOrder Idの注文が既にキャンセルされていた場合
NH05 取引が処理中
AC38 パラメータで指定した金額が超過
NH40 取引IDが他のサービスで使用済み

決済のキャンセル

vresult_code上4桁 原因
NH18 指定されたOrder Idの注文が既にキャンセルされていた場合
NH02 取引が無効
NH05 取引が処理中
AC38 パラメータで指定した金額が超過
DG19 レシート発券中のためキャンセルに失敗
DC10 オーダー決済状態が適切ではない

本人認証

vresult_code上4桁 原因
GC** パラメータ不備
GE** 本人認証が実行できない、または失敗
※[本人認証について] を参照してください。