目的と概要

このドキュメントは、加盟店様においてAPIを統合する技術スタッフ向けです。
決済APIは同期式（3Dセキュア決済を除く）であり、HTTP POST、JSON形式のデータを受け入れ、JSONデータを返します。
接続はステージング環境と本番環境の両方で常にSSL経由で保護されます。

用語集

管理コンソール

Albatal Payを利用するにあたり、Web上でアクセス可能な統合コンソールが提供されております。 コンソールは2種類あり、ステージング環境・本番環境に別れます。

認証

決済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ワークフロー

顧客がマーチャントのサイトで購入手続きを行う流れを示します。

1. マーチャントはWPF APIにリクエストを送信して決済を開始します。成功時の応答にはリダイレクト用のURLが含まれており、マーチャントはそれを顧客に渡します。
2. 顧客がそのリダイレクトURLにアクセスすると、ペイメントゲートウェイが提供する実際の決済フォーム（WPF）が表示されます。マーチャントが事前に送信した情報(商品情報,金額,その他詳細など)でフォームは既に入力されており、顧客は決済情報および個人情報を入力することでフォーム入力を完了させます。
3. 入力が完了し、フォームを送信すると決済が処理されます。3Dセキュア形式での決済では、そのプラットフォームのページにリダイレクトされることがあります。完了後、顧客はマーチャント側のリターンURLにリダイレクトされます¹。
4. 決済が処理されて最終状態に達した後、ゲートウェイは最初の作成リクエストで指定された通知URLに対して通知を送信します。
5. マーチャントは通知を受信し最終的な決済ステータスを確認する必要があります。

¹ 通常はマーチャントが最初に指定した return_success_url にリダイレクトされます。

補足:

• 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 https://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": "https://www.example.com/success",
        "return_failure_url": "https://www.example.com/failure",
        "return_cancel_url": "https://www.example.com/cancel.html",
        "return_pending_url": "https://www.example.com/payment-pending.html",
        "amount": 1980,
        "currency": "JPY",
        "consumer_id": "417155",
        "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,
      remember_card: true,
      transaction_type_name: "sale3d",
    }),
  });

継続決済（Managed Recurring）のWPF作成

継続決済（Managed Recurring）をWPFで開始する場合も、最初に「WPF作成」を1回だけ行います。 このWPF（初回決済）が完了（approved）すると、以降の継続課金は指定したスケジュールに従ってシステム側で自動実行され、結果は notification_url に通知されます（通知フォーマットは「継続決済通知（2回目以降）」を参照）。

実装上は、WPF作成リクエストで次のパラメータを指定してください。

• transaction_type_name に recurring_sale3d を指定
• recurring_type に managed を指定
• managed_recurring に継続条件を指定
  • mode: automatic（自動実行）
  • interval: 課金間隔の単位（days または months）
  • period: 課金間隔（必須、integer）。interval=days の場合は「日数」（最大: 30）、interval=months の場合は「月数」（最大: 12）を指定します。
  • first_date: 初回の継続課金を実行する日付（任意、YYYY-MM-DD）。未指定時は「作成日 + period」がデフォルトです。
  • amount: 2回目以降の継続課金額（※ リクエスト直下の amount は初回決済の金額です）
  • max_count: 最大実行回数（初回決済を除く）

first_date を指定することで、例えば「初回は割引価格で提供し、2回目以降は毎月通常価格で課金する」といった運用において、初回決済（WPF）と次回以降の課金タイミングを意図した日付に揃えることができます。

また、継続決済（2回目以降）の実行時に決済が処理できなかった場合（ユーザのカードが無効になった、与信枠が不足する等）は、Managed Recurring自体がキャンセルされ、次回以降は自動的に決済が行われません。

リクエスト例（Managed Recurring）

const payload = {
  transaction_id: transactionId,
  usage: "40208 concert tickets",
  description: "You are about to buy 3 shoes at www.shoes.com!",
  notification_url: notificationUrl,
  return_success_url: returnSuccessUrl,
  return_failure_url: returnFailureUrl,
  return_cancel_url: returnCancelUrl,
  return_pending_url: returnPendingUrl,
  amount: 1280,
  currency: "JPY",
  consumer_id: consumerId,
  consumer_email: email,
  transaction_type_name: "recurring_sale3d",
  recurring_type: "managed",
  remember_card: true,
  managed_recurring: {
    mode: "automatic",
    interval: "days",
    period: 30,
    amount: 980,
    max_count: 2,
  },
  billing_address: {
    first_name: "田中",
    last_name: "太郎",
    address1: "丸の内1-1-1",
    zip_code: "100-0005",
    city: "千代田区",
    neighborhood: "丸の内",
    state: "東京都",
    country: "JP",
  },
};

リクエストパラメータ

Notification URLについて

notification_url パラメータは、WPF決済が最終状態に達したときにゲートウェイがHTTP POSTリクエストを送信するURLを指定します。
通知先に指定したURLが、BASICやその他の認証を必要とすることのないパブリックにアクセス可能なURLであることを確認してください。
また、http、localhost、プライベートIPアドレス等を指定した場合はエラーとなります。 ローカルで動作確認を行う際は、ngrokやnginxのリバースプロキシ等を使用してパブリックにアクセス可能なURLを用意してください。

注:
* 「必須 ◯*」は、送信する取引タイプやビジネス要件によって必須となる場合がある条件付き必須フィールドです。 説明部分を参照してください。
* billing_addressは任意です。指定しない場合、自動的にダミーの値でゲートウェイに送信します。 本番利用であっても、この挙動は問題ありません。 加盟店側で情報として所有している場合は、承認率の関係上指定することを推奨します。 また、サブフィールドのパラメータの一部が提供されていない場合は、ユーザの決済情報入力時に当該項目を入力する欄が表示されます。

カード情報保存に関する注意事項

WPF作成時に加盟店でカード保存を有効化(remember_card:trueを指定)した場合、顧客はWPF上でカード情報を保存するかどうかを選択できます。

一度保存されますと、継続決済、単品決済の両方で同じカードを選択することが可能です。 この時、保存されていてもCVVの入力は毎度必須となります。

送信するconsumer_idとconsumer_emailパラメータの組が一致する場合に同一ユーザとして判定され、保存カードの選択が表示されます。

カード情報の保存は原則無期限ですが、加盟店様の接続先ゲートウェイのポリシーにより、予告なく一定期間後に自動的に削除される場合があります。

レスポンス例

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

Managed Recurring

Console API（Managed Recurring アイテム操作）

コンソール側で保持している定期決済情報であるManaged Recurringの「単体取得」「キャンセル」を提供します。

重要:

• パスパラメータ {transaction_id} は、WPF取引を作成した際に加盟店側が最初に指定した取引IDです。

Managed Recurring アイテムを取得（単体）

Managed Recurring アイテムを取得します。

GET /api/wpf/managed_recurring/items/{transaction_id}

リクエスト例

curl https://staging.albatal.ltd/api/wpf/managed_recurring/items/{transaction_id} \
  -X GET \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN"

成功レスポンス例

{
  "managed_recurring_item": {
    "unique_id": "527b78f60234b8a92103faa45515cdb1",
    "interval": "months",
    "period": 1,
    "amount": "5000.0",
    "max_count": 0,
    "current_count": 0,
    "first_date": "2025-04-15",
    "next_date": "2025-04-20",
    "time_of_day": 0
  }
}

成功レスポンスパラメータ

managed_recurring_item の各フィールドは以下の通りです。

Managed Recurring アイテムをキャンセル

Managed Recurring アイテムをキャンセルし、以降の決済を停止します。

DELETE /api/wpf/managed_recurring/items/{transaction_id}

リクエスト例

curl https://staging.albatal.ltd/api/wpf/managed_recurring/items/{transaction_id} \
  -X DELETE \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN"

成功レスポンス

空のJSONオブジェクトを返します。

{}

エラー/ステータスコード

このAPIが返す主なステータスは以下です。

通知

WPF通知は、WPF決済が最終状態に達したとき、および継続決済（Managed Recurring）が自動実行されたときに送信されます。 HTTP POST（application/x-www-form-urlencoded）を介してパラメータが送信されます。

通常決済（WPF完了通知）

WPF経由での初回決済（単発決済、または継続決済の初回登録）が完了した際に送信される通知です。

パラメータ例:

wpf_transaction_id=a0695fc8-31f7-45a8-b74d-5a0d5ed26e79&wpf_status=approved
&wpf_unique_id=04edd5bf9dcb30f9b6ee4c01123a8cfd&notification_type=wpf&signature=...
&payment_transaction_unique_id=c534328a155e57cf18908e778a5548c3
&payment_transaction_transaction_type=sale3d&payment_transaction_amount=1002&apc_card_brand=visa
&apc_card_last_four_digits=1111&apc_card_expiration_year=2025&apc_card_expiration_month=9

継続決済通知（2回目以降）

Managed Recurring機能により、スケジュールされた継続決済がシステム側で自動実行された際に送信される通知です。初回決済とはパラメータ名が異なりますのでご注意ください。

パラメータ例:

transaction_id=37bbfe0f25f083a979af8e8e83c5182b&unique_id=dd2c56e2fa47d91e7b564348066c8c9e
&merchant_transaction_id=3af71fa5faf24051e75f7f99659d71ac
&status=approved&signature=...&amount=980&transaction_type=sale

apc_card_ で始まるパラメータは、顧客カード情報が取得できた場合にのみ含まれます。 取得できなかった場合は、パラメータ自体が含まれないか、値がnullになります。

署名の検証

署名は、通知の正当性を保証するためのセキュリティ手段です。 通知の種類（通常決済/継続決済）によって、署名の生成に使用されるIDが異なります。

1. 通常決済（WPF完了通知）: <wpf_unique_id><加盟店シークレット> のハッシュ値

2. 継続決済（2回目以降）: <unique_id><加盟店シークレット> のハッシュ値 ※ unique_id は今回の通知に含まれる決済IDです。

※ ハッシュアルゴリズムは SHA-512となりますが、ゲートウェイの仕様により取引によってSHA-1が利用される場合もあります。両方での検証し、いずれかが一致すれば有効と判断してください。

加盟店シークレットの値は、管理コンソールからご自身の加盟店情報画面より確認することができます。(加盟店シークレットにもステージング環境と本番環境で異なる値が設定されていますので、ご注意ください。)

通知を受信したら、ゲートウェイが通知を受け入れたことを認識できるように、ステータス200のレスポンスを返信してください。 レスポンスを送信しない場合、標準では1分に1回、最大3回まで再送信を試みます。

WPFの状態

WPFトランザクションには、次のいずれかの状態があります。

クレジットカード番号

ゲートウェイのテストには、実在するカード番号を用いて決済を実行します。 または、オンラインクレジットカードジェネレーターを使用したカード番号を使用することもできますが、一部処理においては番号が無効と判断される場合もあります。
いずれの場合も、テスト時は、メッセージに以下のような内容が含まれ、請求が行われることはありません。

エラー

レスポンスに含まれる error_codeをもとに、以下の表で原因と対処の目安を確認してください。

エラーグループ一覧

エラーコードは範囲（100番台、200番台…）ごとにグループ化されています。

エラーコード一覧

システムエラー

通信エラー

入力データエラー

ワークフローエラー

処理エラー

リスクエラー

イシュアエラー（リモートエラー）