目的と概要
このドキュメントは、加盟店様においてAPIを統合する技術スタッフ向けです。
決済APIは同期式（3Dセキュア決済を除く）であり、HTTP POST、JSON形式のデータを受け入れ、JSONデータを返します。
接続はステージング環境と本番環境の両方で常にSSL経由で保護されます。
用語集
| 用語 | 説明 |
|---|---|
| Merchant | Merchantは、ご契約いただく加盟店のことを指します。また、同一の契約主体(法人様単位)であっても、決済を導入する先のサイトが異なる(ドメインが異なる)場合は、それぞれにMerchantが作成されます。 |
| コンシューマー | コンシューマーは、決済を行う顧客のことを指します。 |
| Web Payment Form (WPF) | WPF（Web Payment Form）は、決済ゲートウェイ上でホストされるセキュアなWebフォームです。顧客の支払いを簡単に処理できる直感的なUIを提供します。 加盟店様システムがカード情報を所有することなく決済を実現することが可能です。 |
| Managed Recurring | Managed Recurringとは、定期的に実行される繰り返し型の決済です。 毎月課金・サブスクリプション型の決済はこの機能を利用します。 |
| Reconcile | このセクションでは、取引の照合、取引履歴の取得に関連するAPIを提供します。 |
| 加盟店グループ | 加盟店グループとは、同一の契約主体(法人様単位)で複数のMerchantをもつ場合に利用する機能です。 複数のサイトにおける決済を横断で確認するためのものです。 |
管理コンソール
Albatal Payを利用するにあたり、Web上でアクセス可能な統合コンソールが提供されております。 コンソールは2種類あり、ステージング環境・本番環境に別れます。
| ステージング | 本番 | |
|---|---|---|
| URL | https://staging.console.albatal.ltd | https://console.albatal.ltd |
認証
決済APIと連携するには、（認証情報は管理画面で確認できます。）
認証は Bearer トークン方式です。HTTP リクエストの Authorization ヘッダーに以下の形式でトークンを渡してください。
Authorization: Bearer <YOUR_BEARER_TOKEN>
# 環境変数 YOUR_BEARER_TOKEN にトークンを設定している想定
curl -X POST "https://staging.console.albatal.ltd/api/gateway/route-path" \
-H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"consumer_id":"123456"
}'
// Node 18+ の組み込み fetch を想定
const token = process.env.YOUR_BEARER_TOKEN;
async function callGateway() {
const res = await fetch('https://staging.console.albatal.ltd/api/form/ja/wpf', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
consumer_id: '123456'
})
});
if (!res.ok) {
const text = await res.text();
throw new Error(`HTTP ${res.status}: ${text}`);
}
return await res.json();
}
callGateway().then(console.log).catch(console.error);
補足:
- トークンは管理コンソールから確認・発行します（トークンの保管にご注意ください）。
- リクエスト/レスポンスのペイロードは JSON形式を使用します。Content-Type ヘッダーで明示してください。
APIエンドポイント
WPF系API
WPFに関連する処理の呼び出し
接続先URL/api/wpf
https://staging.console.albatal.ltd/api/gateway/process/TERMINAL_TOKEN/
WPF
WPF（Web Payment Form）は、ペイメントゲートウェイが提供するコンポーネントです。マーチャントが顧客の決済を簡単に処理できる直感的なユーザーインターフェースを提供し、PCI-DSSに準拠する形式となっています。
ワークフロー
WPFワークフロー
顧客がマーチャントのサイトで購入手続きを行う流れを示します。
- マーチャントはWPF APIにリクエストを送信して決済を開始します。成功時の応答にはリダイレクト用のURLが含まれており、マーチャントはそれを顧客に渡します。
- 顧客がそのリダイレクトURLにアクセスすると、ペイメントゲートウェイが提供する実際の決済フォーム（WPF）が表示されます。マーチャントが事前に送信した情報(商品情報,金額,その他詳細など)でフォームは既に入力されており、顧客は決済情報および個人情報を入力することでフォーム入力を完了させます。
- 入力が完了し、フォームを送信すると決済が処理されます。 完了後、顧客はマーチャント側のリターンURLにリダイレクトされます¹。
- 決済が処理されて最終状態に達した後、ゲートウェイは最初の作成リクエストで指定された通知URLに対して通知を送信します。
- マーチャントは通知を受信し最終的な決済ステータスを確認する必要があります。
¹ 通常はマーチャントが最初に指定した return_success_url にリダイレクトされます。3Dセキュア形式での決済では、そのプラットフォームのページにリダイレクトされることがあります。
補足:
- 3Dセキュア（3DS）対応のWPF決済は常に非同期で行われます。WPF送信後、顧客は認証のためにプロバイダーへリダイレクトされ、認証結果に応じて成功・失敗のURLへ戻されます（未登録の場合は失敗URLへ）。
- return／success／cancel の各URLは、顧客に表示するためのページを提供する目的であり、これらのURLへのリダイレクトだけで決済結果が確定するわけではありません。決済の確定状況はサイトで受信した通知をご確認ください。
- 通知およびユーザのreturn/success/cancelで指定したURLへのリダイレクトの順序は保証されていません（通知が先に届く場合もあります）。
URL
作成:
WPF API作成メソッドのURLは次のとおりです。
https://console.albatal.ltd/api/wpf/create
テストシステムのURLは次のとおりです。
https://staging.console.albatal.ltd/api/wpf/create
作成
Web Payment Form APIは、次のトランザクションタイプに対して3DSv2認証プロトコルをサポートしています： Sale3d。 詳細については、以下のリクエストパラメータと右側のリクエスト例を確認してください。
リクエストの例
curl http://staging.console.albatal.ltd/api/wpf/create \
-X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "bf7e2c27-318e-46f6-b98a-9c317bb4dab9",
"usage": "コンサートチケット",
"description": "コンサートチケットの購入代金です",
"notification_url": "https://www.example.com/notify",
"return_success_url": "http://www.example.com/success",
"return_failure_url": "http://www.example.com/failure",
"return_cancel_url": "http://www.example.com/cancel.html",
"return_pending_url": "http://www.example.com/payment-pending.html",
"amount": 1980,
"currency": "JPY",
"consumer_id": "abcd1234",
"consumer_email": "enteric_bezels9c@icloud.com",
"billing_address": {
"first_name": "太郎",
"last_name": "山田",
"address1": "東京都千代田区丸の内1-1-1",
"zip_code": "100-0005",
"city": "千代田区",
"neighborhood": "丸の内",
"state": "Tokyo",
"country": "JP"
},
"transaction_type_name": "sale3d"
}'
const response = await fetch("https://staging.console.albatal.ltd/api/wpf/create", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.ALBATAL_PAY_API_KEY}`,
},
body: JSON.stringify({
transaction_id: transactionId,
usage: internalTransactionDescription,
amount,
currency,
consumer_id: consumerId,
description,
consumer_email: consumerEmail,
notification_url: notificationUrl,
return_success_url: returnSuccessUrl,
return_failure_url: returnFailureUrl,
return_cancel_url: returnCancelUrl,
return_pending_url: returnPendingUrl,
transaction_type_name: "sale3d",
}),
});
リクエストパラメータ
| パラメータ | 必須 | 形式 | 説明 |
|---|---|---|---|
| transaction_id | ◯ | string(255) | マーチャントが定義する一意の取引IDで、CUID形式またはUUID形式である必要があります。一度処理を実行したIDを再利用することはできません。 |
| usage | ◯ | string(255) | 取引の説明。 ユーザが自身で編集できます。 |
| description | ◯ | string | 決済理由の顧客向け表示用テキストです。 |
| amount | ◯ | integer (>100) | 決済取引額を整数で指定します。 最低金額は設定によって変更できる場合があります。 |
| currency | ◯ | string(3) | ISO 4217通貨コード "JPY"のみ |
| consumer_id | ◯ | string(255) | 加盟店側が所有している顧客を識別するIDです。 consumer_emailと組で一意である必要があります。 |
| consumer_email | ◯ | 顧客の有効なメールアドレス。 メールアドレスが変更された場合、consumer_idも別のものにして送信する必要があります。 | |
| notification_url | ◯ | url | この取引の結果通知を受け取るマーチャントURL |
| return_success_url | ◯ | url | 決済成功時のユーザのリダイレクトURL |
| return_failure_url | ◯ | url | 決済失敗時のユーザのリダイレクトURL |
| return_cancel_url | ◯ | url | ユーザーがキャンセルした場合のリダイレクトURL |
| return_pending_url | ◯ | url | 非同期決済の保留時のURL |
| billing_address | ◯* | object | 請求先住所（下のサブフィールド参照） |
| first_name | ◯* | string(255) | 名 |
| last_name | ◯* | string(255) | 姓 |
| address1 | ◯* | string(255) | 主要住所 |
| zip_code | ◯* | string | 郵便番号 |
| city | ◯* | string(255) | 市区町村 |
| neighborhood | ◯* | string(255) | 地区 |
| state | ◯* | string(2) | 州コード（米国/カナダで必須） |
| country | ◯* | string(2) | ISO 3166国コード |
| transaction_types | ◯ | array | 受け入れる取引タイプ（例: Sale3d） |
注:
* 「必須 ◯*」は、送信する取引タイプやビジネス要件によって必須となる場合がある条件付き必須フィールドです。 説明部分を参照してください。
* billing_addressは任意ですが、パラメータとして提供されない場合は、決済情報入力時にユーザ自身が入力する必要があります。また、提供される場合はすべてのサブフィールドが必須となります。
レスポンス例
{
status: 'new',
unique_id: '8d9c6acd0df466d96d2ca7a64d3bf1bc',
transaction_id: 'n3hln4f7a01taiyzppp4u0v5',
consumer_id: '417155',
timestamp: '2025-11-21T08:12:56Z',
amount: '1980',
currency: 'JPY',
redirect_url: 'https://staging.wpf.emerchantpay.net/ja/v2/payment/8d9c6acd0df466d96d2ca7a64d3bf1bc'
}
| パラメータ | タイプ | 説明 |
|---|---|---|
| status | string(255) | WPF取引のステータス、状態を参照 |
| unique_id | string(32) | ゲートによって定義された一意のID（後で取引を無効化、または返金する場合に使用する必要があります） |
| transaction_id | string(255) | マーチャントが定義した一意の取引ID |
| redirect_url | url | ユーザーが決済プロセスを完了するためにリダイレクトされる必要があるURL |
| timestamp | string(255) | 取引が処理された時刻（ISO 8601結合日時形式、例：2007-08-30T17:46:11Z） |
| amount | integer | 通貨の最小単位での取引金額、詳細は通貨と金額の処理を参照 |
| currency | string(255) | ISO 4217の通貨コード |
| code | integer | エラーの場合に含まれます。エラーコード表によるエラーコード |
| technical_message | string(255) | エラーの場合に含まれます。技術的なエラーメッセージ（内部使用のみ、ユーザーに表示しないでください） |
| message | string(255) | エラーの場合に含まれます。ユーザーに表示できる人間が読める形式のエラーメッセージ |
通知
WPF通知は、WPF決済が最終状態に達したときに一度送信され、HTTP POST（application/x-www-form-urlencoded）を介して次のパラメータが含まれます。
リクエスト例
wpf_transaction_id=a0695fc8-31f7-45a8-b74d-5a0d5ed26e79&wpf_status=approved
&wpf_unique_id=04edd5bf9dcb30f9b6ee4c01123a8cfd¬ification_type=wpf&signature=171ffc4fb1423f586a6927f63958484d8bf4b39eacf495e66a7c418d3bb943a540e5f1b261ae9ae3749265f0cc6fca1ea63306ef57fd009e6c75f6ff5b5839b0&
payment_transaction_terminal_token=2e5ab4572ece9ca8810dced87da66e5567035afa&payment_transaction_unique_id=c534328a155e57cf18908e778a5548c3&payment_transaction_transaction_type=sale3d&payment_transaction_amount=1002&eci=07&consumer_id=425979&
payment_transaction_token=6e9b672e-e24d-4eb0-99f2-7b762ee3c0b5&authorization_code=071823&scheme_transaction_identifier=580122830802202&threeds_target_protocol_version=2
| 名前 | タイプ | 説明 |
|---|---|---|
| signature | string | 通知の署名。通知がペイメントゲートウェイによって送信されたことを確認するために使用する必要があります |
| payment_transaction_transaction_type | string | 取引のトランザクションタイプ（例：sale3d） |
| payment_transaction_terminal_token | string | 処理URLで使用されるターミナルトークン |
| payment_transaction_unique_id | string | ペイメントゲートウェイによって生成された一意のID |
| payment_transaction_amount | string | 支払いトランザクションの金額。トランザクションが部分的に承認された場合、これは部分的に承認された金額です。詳細は部分承認を確認してください |
| wpf_transaction_id | string | マーチャントが生成した取引ID |
| wpf_status | string | 支払い取引のステータス |
| wpf_unique_id | string | ペイメントゲートウェイによって生成された一意のID |
| notification_type | string | 定数値 "wpf" |
| payment_transaction_cvv_result_code | string | カード確認値の応答コード。任意。アクワイアラーがサポートしている場合にのみ返されます。 |
| authorization code | string | 一部の取得者から返されるコードで、カード支払いが承認されたことを示します。 |
| retrieval_reference_number | string | 一部の取得者から返される、特定のカード所有者取引に関連するすべてのメッセージを追跡するために使用される参照番号。 |
| status | string* | 取引ステータス。 |
| consumer_id | string* | Albatal Pay内部で発行された顧客ID |
string* = これは任意のパラメータです。
署名は、ゲートが本当に通知の送信者であることを保証するためのセキュリティ手段です。これは、支払いの unique_id と加盟店シークレットを文字列で連結し、そのSHA-512ハッシュ（16進数）を生成することによって生成されます。
<wpf_unique_id><加盟店シークレット> のSHA-512ハッシュ（16進数）
加盟店シークレットの値は、管理コンソールからご自身の加盟店情報画面より確認することができます。
通知を受信したら、ゲートウェイが通知を受け入れたことを認識できるように、ステータス200のレスポンスを返信してください。 レスポンスを送信しない場合、標準では1分に1回、最大3回まで再送信を試みます。
WPFの状態
WPFトランザクションには、次のいずれかの状態があります。
| ステータス | 説明 |
|---|---|
| new | wpfトランザクションの初期ステータス。 |
| requested | Albatal PayがWPFを作成し、マーチャントへURLを送信した直後で、ユーザへリダイレクトURLを提供する必要がある状態です。 |
| user | ユーザーがWPFフォームに入力して送信するのを待っています。 |
| timeout | トランザクションが長時間保留され、タイムアウト期間に達しました。 ユーザが決済情報を入力せずに一定時間が経過した場合などを指します。 |
| in_progress | トランザクションは現在処理中です。 |
| pending | トランザクションが処理中です。 (ユーザの決済情報入力待ちなど) |
| pending_hold | 非同期トランザクションはユーザーによって確定されましたが、プロバイダーからの最終更新を待っています。 |
| approved | トランザクションはスキームによって承認され、成功しました。 |
| declined | トランザクションはスキームまたはリスク管理によって拒否されました。 |
| error | 処理中にエラーが発生しました。 |
| refunded | 承認されたトランザクションが返金されると、状態は refunded に変わります。 |
| voided | トランザクションは承認されましたが、後でマーチャントによってキャンセルされたものです。 |
| chargebacked | 承認されたトランザクションがチャージバックされると、状態は chargebacked に変わります。チャージバックは、カード所有者または発行者が、資金がすでに送金された承認済みトランザクションを拒否した場合に発生します。 |
| chargeback_reversal | チャージバックされたトランザクションが課金されると、状態は chargeback_reversal に変わります。 |
| represented | マーチャントがチャージバックが不正であることを証明する証拠を提出すると、チャージバックされたトランザクションの状態は represented に変わります。 |
| representment_reversed | マーチャントによって開始された再提示が、エラーまたは無効な再提示理由のために取得者（マーチャントの銀行）によってキャンセルまたは拒否された場合。再提示の結果として最初にマーチャントに返金された資金は、発行者口座（カード所有者の銀行）に差し戻されます。 |
| second_chargebacked | chargeback_reversed/represented トランザクションがチャージバックされると、状態は second chargebacked に変わります。 |
| pending_review | トランザクションは保留中です。手動レビューを実行する必要があります。 |
| submitted | WPFフォームはユーザーによって送信されました。 |
WPF取引タイプ
Webペイメントフォームでは、セールス、継続課金の初期化など、一般的なカード関連の取引タイプをサポートしています。
Webペイメントフォームには、デフォルトの決済方法という概念があります。特定の取引タイプに default 属性が true に設定されている場合、カード保有者がWebペイメントフォームにリダイレクトされたときに、その取引タイプがデフォルトとして事前選択されます。複数の取引タイプに default 属性がある場合、この属性を持つ最初のものが事前選択されます。リクエストされた取引タイプが1つだけの場合（default=true の有無にかかわらず）、その取引タイプは設計上自動的にデフォルトとして設定されます。
| 取引タイプ | カスタム属性 | 必須 | 説明 |
|---|---|---|---|
authorize3d |
3Dセキュアベースのオーソリゼーション | ||
default |
任意 | デフォルトとして設定するかどうか | |
expiration_date |
任意 | 有効期限の月と年 | |
sale3d |
3Dセキュアベースの売上 | ||
default |
任意 | デフォルトとして設定するかどうか | |
expiration_date |
任意 | 有効期限の月と年 | |
| 合も入力必須です。 | |||
init_recurring_sale3d |
3Dセキュアベースの継続課金の初期化 | ||
default |
任意 | デフォルトとして設定するかどうか | |
managed_recurring |
任意 | マネージド継続課金を参照。継続的な取引を自動的にスケジュールするオプションを提供します |
クレジットカード番号
ゲートウェイのテストには、実在するカード番号を用いて決済を実行します。
テスト時は、メッセージに以下のような内容が含まれ、請求が実行されることはありません。