API リファレンス

共通仕様

Base URL

環境	URL
Sandbox	`https://ct-global.np-pay.com`
Production	https://np-pay-global.com

共通 HTTP ヘッダー

ヘッダー名	必須性	備考
`Content-Type`	必須	`application/json`
`Accept`	必須	`application/json`
`Authorization`	必須	Basic 認証（認証参照）
`Np-Service-Type`	必須	サービス・ブランド指定
`Np-Terminal-Id`	任意	契約時に連携された場合のみ、すべてのリクエストに含めてください。

Np-Service-Type ヘッダーで使用するサービスを指定します。詳細はサービス・ブランド指定を参照してください。

サービス・ブランド指定

値	ブランド・地域	デフォルト通貨
`JPN-ATN`	atone / Japan	JPY
`TWN-AFT`	AFTEE / Taiwan	TWD

認証

詳しくは、担当のカスタマーサクセスマネージャーまでお問い合わせください。

事前登録 API

事前登録 API は、取引開始前の準備として使用される API です。取引情報の登録とアカウント連携の 2 つの機能を提供します。

レスポンス仕様

事前登録 API は、いずれも成功時にリダイレクト先の URL を含むレスポンスを返します。ユーザーをこの URL にリダイレクトさせることで、該当するフローを開始できます。すべてのエンドポイントは成功時に HTTP 200 を返します。

1. 取引情報の事前登録

POST /v1/pre_registrations/transactions

取引データを事前登録し、ユーザーをチェックアウトモジュールへリダイレクトさせるためのURLを取得します。

名前

pre.txn

パラメータ

名前	型	必須	説明
`Np-User-Token` HEADER	string		ユーザートークン
`payment` BODY	object	○	加盟店が指定する決済データスキーマを見る→ payment
`expiration` BODY	epoch_time		チェックアウト有効期限（epoch秒）
`return_url` BODY	string	○	支払い完了後の戻り先URL

コード例

Curl

curl -X POST 'https://ct-global.np-pay.com/v1/pre_registrations/transactions' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT' \
  -d '{
    "expiration": 1712289600,
    "return_url": "https://example.com/callback",
    "payment": {
      "amount": 4539,
      "currency": "JPY",
      "merchant_transaction_id": "1685354884137Zx2FB217",
      "description": "サンプル取引の備考",
      "options": [],
      "immediate_settlement": false,
      "buyer": {
        "name": "山田太郎",
        "email": "test@example.com",
        "phone": "0900000000",
        "address": "東京都千代田区神田錦町3-7-1",
        "merchant_user_id": "shop-user-no-001"
      },
      "items": [
        {
          "id": "ITEM-001",
          "name": "プレミアム商品A",
          "category": "goods",
          "unit_price": 4539,
          "quantity": 1,
          "total_price": 4539
        }
      ]
    }
  }'

Json

{
  "expiration": 1712289600,
  "return_url": "https://example.com/callback",
  "payment": {
    "amount": 4539,
    "currency": "JPY",
    "merchant_transaction_id": "1685354884137Zx2FB217",
    "description": "サンプル取引の備考",
    "options": [],
    "immediate_settlement": false,
    "buyer": {
      "name": "山田太郎",
      "email": "test@example.com",
      "phone": "0900000000",
      "address": "東京都千代田区神田錦町3-7-1",
      "merchant_user_id": "shop-user-no-001"
    },
    "items": [
      {
        "id": "ITEM-001",
        "name": "プレミアム商品A",
        "category": "goods",
        "unit_price": 4539,
        "quantity": 1,
        "total_price": 4539
      }
    ]
  }
}

レスポンス例

200 登録成功

{
  "url": "https://ct-global.np-pay.com/settlement/1685354884137Zx2FB217?identifier=pr_u9qwI-Q9R8mO5AFe"
}

2. アカウント連携の事前登録

POST /v1/pre_registrations/user_tokens

加盟店ユーザーとNPサービスユーザーの連携情報を事前登録し、ユーザーを認証モーダルへリダイレクトさせるためのURLを取得します。

名前

pre.token

パラメータ

名前	型	必須	説明
`return_url` BODY	string	○	認証完了後の戻り先URL
`buyer` BODY	object		購入者情報プロパティ `name` string 購入者氏名 `email` string 購入者メールアドレス `phone` string 購入者電話番号 `address` string 購入者住所 `merchant_user_id` string 加盟店会員ID（連携対象のユーザー識別子）

コード例

Curl

curl -X POST 'https://ct-global.np-pay.com/v1/pre_registrations/user_tokens' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT' \
  -d '{
    "return_url": "https://example.com/callback",
    "buyer": {
      "name": "山田太郎",
      "email": "test@example.com",
      "phone": "0900000000",
      "address": "東京都千代田区神田錦町3-7-1",
      "merchant_user_id": "shop-user-no-001"
    }
  }'

Json

{
  "return_url": "https://example.com/callback",
  "buyer": {
    "name": "山田太郎",
    "email": "test@example.com",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "merchant_user_id": "shop-user-no-001"
  }
}

レスポンス例

200 登録成功

{
  "url": "https://ct-global.np-pay.com/account/bind/1685354884137Zx2FB217?identifier=ab_u9qwI-Q9R8mO5AFe"
}

取引操作 API

取引操作 API は、登録済みの取引に対する各種操作を提供します。

レスポンス仕様

注意: このセクションの取引 API は、特に記載がない限り、レスポンスとして transaction オブジェクトを返します。完全なプロパティについては、このページ末尾のtransaction スキーマを参照してください。すべてのエンドポイントは成功時に HTTP 200 を返します。

1. 取引を取得（id）

GET /v1/transactions/{id}

取引ID（id）で取引情報を取得します

名前

txn.get

パラメータ

名前	型	必須	説明
`id` PATH	string	○	取引ID（取引オブジェクトのservice_transaction_id）

コード例

Curl

curl -X GET 'https://ct-global.np-pay.com/v1/transactions/tr_GyhcP2Z8yh28AYS_' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT'

レスポンス例

200

{
  "metadata": {
    "object": "transaction",
    "service_transaction_id": "tr_GyhcP2Z8yh28AYS_",
    "livemode": true,
    "parent_transaction_ids": [],
    "recurring_transaction_id": null,
    "service_user_id": "np_user_id_001",
    "service_user_name": "090****1234",
    "options": []
  },
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "amount": 4539,
  "currency": "JPY",
  "description": "サンプル取引の備考",
  "authentication": {
    "user_token": "1234567890"
  },
  "authorization": {
    "result": 1,
    "ng_reason": null
  },
  "timeline": {
    "registration_timestamp": 1718208000,
    "settlement_timestamp": null,
    "reversal_timestamp": null
  },
  "buyer": {
    "name": "山田太郎",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "email": "test@example.com"
  },
  "items": [
    {
      "id": "ITEM-001",
      "name": "プレミアム商品A",
      "category": "goods",
      "unit_price": 4539,
      "quantity": 1,
      "total_price": 4539
    }
  ]
}

2. 取引を取得（merchant_transaction_id）

GET /v1/transactions?merchant_transaction_id={merchant_transaction_id}

加盟店の取引ID（merchant_transaction_id）で取引情報を取得します

名前

txn.get-by-merchant

パラメータ

名前	型	必須	説明
`merchant_transaction_id` QUERY	string	○	加盟店側の取引番号（ユニーク）

コード例

Curl

curl -X GET 'https://ct-global.np-pay.com/v1/transactions?merchant_transaction_id=1685354884137Zx2FB217' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT'

レスポンス例

200

{
  "metadata": {
    "object": "transaction",
    "service_transaction_id": "tr_GyhcP2Z8yh28AYS_",
    "livemode": true,
    "parent_transaction_ids": [],
    "recurring_transaction_id": null,
    "service_user_id": "np_user_id_001",
    "service_user_name": "090****1234",
    "options": []
  },
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "amount": 4539,
  "currency": "JPY",
  "description": "サンプル取引の備考",
  "authentication": {
    "user_token": "1234567890"
  },
  "authorization": {
    "result": 1,
    "ng_reason": null
  },
  "timeline": {
    "registration_timestamp": 1718208000,
    "settlement_timestamp": null,
    "reversal_timestamp": null
  },
  "buyer": {
    "name": "山田太郎",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "email": "test@example.com"
  },
  "items": [
    {
      "id": "ITEM-001",
      "name": "プレミアム商品A",
      "category": "goods",
      "unit_price": 4539,
      "quantity": 1,
      "total_price": 4539
    }
  ]
}

3. 取引を更新/再作成（transactions_update）

POST /v1/transactions

既存取引を元に内容を更新し、新しい取引として作成します

名前

txn.update

パラメータ

名前	型	必須	説明
`Np-User-Token` HEADER	string	○	ユーザートークン
`parent_transaction_ids` BODY	array		更新対象の`service_transaction_id`の配列（元の取引）。取引の更新では必須。
`recurring_transaction_id` BODY	string		定期取引オプション利用時の初回取引の取引ID。transaction_options: [1] を指定した場合のみ必須。
`payment` BODY	object	○	新しい構造化された決済データスキーマを見る→ payment

コード例

Curl

curl -X POST 'https://ct-global.np-pay.com/v1/transactions' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT' \
  -H 'Np-User-Token: stt_your_auth_token' \
  -d '{
    "parent_transaction_ids": ["tr_GyhcP2Z8yh28AYS_"],
    "payment": {
      "amount": 4539,
      "currency": "JPY",
      "merchant_transaction_id": "1685354884137Zx2FB217",
      "description": "更新取引の備考",
      "options": [],
      "immediate_settlement": false,
      "buyer": {
        "name": "山田太郎",
        "email": "test@example.com",
        "phone": "0900000000",
        "address": "東京都千代田区神田錦町3-7-1",
        "merchant_user_id": "shop-user-no-001"
      },
      "recipients": [
        {
          "name": "佐藤花子",
          "email": "dest@example.com",
          "phone": "0800000000",
          "address": "東京都新宿区西新宿1-1-1"
        }
      ],
      "items": [
        {
          "id": "ITEM-001",
          "name": "更新商品A",
          "category": "goods",
          "unit_price": 4539,
          "quantity": 1,
          "total_price": 4539
        }
      ]
    }
  }'

Json

{
  "parent_transaction_ids": [
    "tr_GyhcP2Z8yh28AYS_"
  ],
  "payment": {
    "amount": 4539,
    "currency": "JPY",
    "merchant_transaction_id": "1685354884137Zx2FB217",
    "description": "更新取引の備考",
    "options": [],
    "immediate_settlement": false,
    "buyer": {
      "name": "山田太郎",
      "email": "test@example.com",
      "phone": "0900000000",
      "address": "東京都千代田区神田錦町3-7-1",
      "merchant_user_id": "shop-user-no-001"
    },
    "recipients": [
      {
        "name": "佐藤花子",
        "email": "dest@example.com",
        "phone": "0800000000",
        "address": "東京都新宿区西新宿1-1-1"
      }
    ],
    "items": [
      {
        "id": "ITEM-001",
        "name": "更新商品A",
        "category": "goods",
        "unit_price": 4539,
        "quantity": 1,
        "total_price": 4539
      }
    ]
  }
}

レスポンス例

200

{
  "metadata": {
    "object": "transaction",
    "service_transaction_id": "tr_NewGyhcP2Z8yh28AYS_",
    "livemode": true,
    "parent_transaction_ids": ["tr_GyhcP2Z8yh28AYS_"],
    "recurring_transaction_id": null,
    "service_user_id": "np_user_id_001",
    "service_user_name": "090****1234",
    "options": []
  },
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "amount": 4539,
  "currency": "JPY",
  "description": "更新取引の備考",
  "authentication": {
    "user_token": "stt_your_auth_token"
  },
  "authorization": {
    "result": 1,
    "ng_reason": null
  },
  "timeline": {
    "registration_timestamp": 1718208000,
    "settlement_timestamp": null,
    "reversal_timestamp": null
  },
  "buyer": {
    "name": "山田太郎",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "email": "test@example.com"
  },
  "recipients": [
    {
      "name": "佐藤花子",
      "email": "dest@example.com",
      "phone": "0800000000",
      "address": "東京都新宿区西新宿1-1-1"
    }
  ],
  "items": [
    {
      "id": "ITEM-001",
      "name": "更新商品A",
      "category": "goods",
      "unit_price": 4539,
      "quantity": 1,
      "total_price": 4539
    }
  ]
}

4. 売上確定（transactions_settle）

PATCH /v1/transactions/{id}/settle

未確定の取引を売上確定します

名前

txn.capture

パラメータ

名前	型	必須	説明
`id` PATH	string	○	取引ID（取引オブジェクトのservice_transaction_id）

コード例

Curl

curl -X PATCH 'https://ct-global.np-pay.com/v1/transactions/tr_GyhcP2Z8yh28AYS_/settle' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT'

レスポンス例

200

{
  "metadata": {
    "object": "transaction",
    "service_transaction_id": "tr_GyhcP2Z8yh28AYS_",
    "livemode": true,
    "parent_transaction_ids": [],
    "recurring_transaction_id": null,
    "service_user_id": "np_user_id_001",
    "service_user_name": "090****1234",
    "options": []
  },
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "amount": 4539,
  "currency": "JPY",
  "description": "サンプル取引の備考",
  "authentication": {
    "user_token": "1234567890"
  },
  "authorization": {
    "result": 1,
    "ng_reason": null
  },
  "timeline": {
    "registration_timestamp": 1718208000,
    "settlement_timestamp": 1718208300,
    "reversal_timestamp": null
  },
  "buyer": {
    "name": "山田太郎",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "email": "test@example.com"
  },
  "items": [
    {
      "id": "ITEM-001",
      "name": "プレミアム商品A",
      "category": "goods",
      "unit_price": 4539,
      "quantity": 1,
      "total_price": 4539
    }
  ]
}

5. 取消（transactions_cancel）

PATCH /v1/transactions/{id}/cancel

取引を取消します

名前

txn.cancel

パラメータ

名前	型	必須	説明
`id` PATH	string	○	取引ID（取引オブジェクトのservice_transaction_id）
`reason` BODY	string	○	取消理由を示す短い識別子。

コード例

Curl

curl -X PATCH 'https://ct-global.np-pay.com/v1/transactions/tr_GyhcP2Z8yh28AYS_/cancel' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT' \
  -d '{
    "reason": "user_request"
  }'

Json

{
  "reason": "user_request"
}

レスポンス例

200

{
  "metadata": {
    "object": "transaction",
    "service_transaction_id": "tr_GyhcP2Z8yh28AYS_",
    "livemode": true,
    "parent_transaction_ids": [],
    "recurring_transaction_id": null,
    "service_user_id": "np_user_id_001",
    "service_user_name": "090****1234",
    "options": []
  },
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "amount": 4539,
  "currency": "JPY",
  "description": "サンプル取引の備考",
  "authentication": {
    "user_token": "1234567890"
  },
  "authorization": {
    "result": 1,
    "ng_reason": null
  },
  "timeline": {
    "registration_timestamp": 1718208000,
    "settlement_timestamp": null,
    "reversal_timestamp": 1718208600
  },
  "buyer": {
    "name": "山田太郎",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "email": "test@example.com"
  },
  "items": [
    {
      "id": "ITEM-001",
      "name": "プレミアム商品A",
      "category": "goods",
      "unit_price": 4539,
      "quantity": 1,
      "total_price": 4539
    }
  ]
}

ユーザートークン管理 API

ユーザートークン管理 API は、認証されたユーザーのトークン情報の取得・失効を行うための API です。

レスポンス仕様

注意: このセクションのユーザートークン API は、特に記載がない限り、レスポンスとして user_token オブジェクトを返します。完全なプロパティについては、このページ末尾のuser_token スキーマを参照してください。すべてのエンドポイントは成功時に HTTP 200 を返します。

1. ユーザートークンのステータスを取得

GET /v1/user_tokens

ユーザートークンのステータスを取得します

名前

token.get

パラメータ

名前	型	必須	説明
`Np-User-Token` HEADER	string		ユーザートークン（どちらか必須）
`merchant_user_id` QUERY	string		加盟店会員ID（どちらか必須）

コード例

Curl

curl -X GET 'https://ct-global.np-pay.com/v1/user_tokens?merchant_user_id=shop-user-no-001' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT' \
  -H 'Np-User-Token: tk_1b3D5g7$9A1X3y5z'

レスポンス例

200

{
  "metadata": {
    "object": "user_token",
    "livemode": true
  },
  "value": "tk_1b3D5g7$9A1X3y5z",
  "merchant_user_id": "shop-user-no-001",
  "service_user_id": "np_user_id_001",
  "service_user_name": "090****1234",
  "active": true,
  "timeline": {
    "issuance_timestamp": 1718208000,
    "revocation_timestamp": null
  }
}

404

{
  "object": "error",
  "code": "NOT_FOUND",
  "messages": ["user_token with provided parameters not found"]
}

2. ユーザートークンを失効

PATCH /v1/user_token/revoke

ユーザートークンを失効させます

名前

token.revoke

パラメータ

名前	型	必須	説明
`Np-User-Token` HEADER	string	○	ユーザートークンの値

コード例

Curl

curl -X PATCH 'https://ct-global.np-pay.com/v1/user_token/revoke' \
  -H 'Accept: application/json' \
  -H 'Np-Service-Type: TWN-AFT' \
  -H 'Np-User-Token: tk_1b3D5g7$9A1X3y5z'

レスポンス例

200

{
  "metadata": {
    "object": "user_token",
    "livemode": true
  },
  "value": "tk_1b3D5g7$9A1X3y5z",
  "merchant_user_id": "shop-user-no-001",
  "service_user_id": "np_user_id_001",
  "service_user_name": "090****1234",
  "active": false,
  "timeline": {
    "issuance_timestamp": 1718208000,
    "revocation_timestamp": 1718208600
  }
}

付録

Payment オブジェクト

取引事前登録などで使用する支払いデータの構造化スキーマ（加盟店リクエスト用）

Property	型	必須	説明
`amount`	integer	○	合計金額 ≥ 1
`currency`	string		取引通貨コード（ISO 4217形式）。指定しない場合はサービス別のデフォルト通貨が適用されます（atone: JPY、AFTEE台湾: TWD、AFTEEベトナム: VND）長さ ≥ 3 長さ ≤ 3 許容文字: 英字
`merchant_transaction_id`	string	○	加盟店側の取引ID 長さ ≥ 1 長さ ≤ 64 許容文字: 英数字 , `_` , `-`
`description`	string		取引の備考・説明長さ ≥ 0 長さ ≤ 100 許容文字: 英数字 , `.` , `_` , `-` , スペース , `,` , `.` , `!` , `?`
`options`	array		取引オプション
`options[]`	integer
`immediate_settlement`	boolean		注文と同時に売上確定するかデフォルト: `false`
`buyer`	object		購入者情報
`buyer.name`	string		購入者氏名長さ ≥ 1 長さ ≤ 100 許容文字: 英数字 , スペース , `.`
`buyer.email`	string		購入者メールアドレス長さ ≥ 3 長さ ≤ 255 許容文字: 英数字 , `.` , `_` , `-` , `@` , `+`
`buyer.phone`	string		購入者電話番号許容文字: 数字
`buyer.address`	string		購入者住所長さ ≥ 1 長さ ≤ 200 許容文字: 英数字 , スペース , `,` , `.` , `-` , `()`
`buyer.merchant_user_id`	string		加盟店会員ID 長さ ≥ 1 長さ ≤ 64 許容文字: 英数字 , `_` , `-`
`recipients`	array		配送先一覧
`recipients[].name`	string		配送先氏名長さ ≥ 1 長さ ≤ 100 許容文字: 英数字 , スペース , `.`
`recipients[].email`	string		配送先メールアドレス長さ ≥ 3 長さ ≤ 255 許容文字: 英数字 , `.` , `_` , `-` , `@` , `+`
`recipients[].phone`	string		配送先電話番号長さ ≥ 7 長さ ≤ 20 許容文字: 数字
`recipients[].address`	string		配送先住所長さ ≥ 1 長さ ≤ 200 許容文字: 英数字 , スペース , `,` , `.` , `-` , `()`
`items`	array		購入商品リスト要素数 ≥ 1
`items[].id`	string		商品ID 長さ ≥ 1 長さ ≤ 64 許容文字: 英数字 , `_` , `-`
`items[].name`	string		商品名長さ ≥ 1 長さ ≤ 100 許容文字: 英数字 , `.` , `_` , `-` , スペース , `,` , `.` , `!` , `?`
`items[].category`	string		商品カテゴリ長さ ≥ 0 長さ ≤ 50 許容文字: 英数字 , `.` , `_` , `-` , スペース , `,` , `.` , `!` , `?`
`items[].unit_price`	integer		単価 ≥ 0
`items[].quantity`	integer		数量 ≥ 1

{
  "amount": 4539,
  "currency": "JPY",
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "description": "サンプル取引の備考",
  "options": [],
  "immediate_settlement": false,
  "buyer": {
    "name": "山田太郎",
    "email": "test@example.com",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "merchant_user_id": "shop-user-no-001"
  },
  "recipients": [
    {
      "name": "佐藤花子",
      "email": "hanako@example.com",
      "phone": "0900000001",
      "address": "大阪府大阪市北区梅田1-1-1"
    }
  ],
  "items": [
    {
      "id": "ITEM-001",
      "name": "プレミアム商品A",
      "category": "electronics",
      "unit_price": 2500,
      "quantity": 1,
    },
    {
      "id": "ITEM-002"
      "name": "アクセサリーB",
      "category": "accessories",
      "unit_price": 2039,
      "quantity": 1,
    }
  ]
}

Transaction オブジェクト

取引操作時にやり取りされるデータの構造化スキーマ

Property	型	必須	説明
`metadata`	object	○	システムメタデータ情報
`metadata.object`	string	○	オブジェクトの種別例: `transaction`
`metadata.service_transaction_id`	string	○	NP 発行の取引 ID（加盟店側のmerchant_transaction_idと対応）
`metadata.merchant_id`	string	○	NP 発行の店舗 ID（JPN-ATNの場合はatn・TWN-AFTの場合はaftから始まる）
`metadata.livemode`	boolean	○	本番環境かどうかの真偽値
`metadata.parent_transaction_ids`	array		親（更新元）取引IDのリスト
`metadata.parent_transaction_ids[]`	string		親（更新元）取引IDのリスト
`metadata.recurring_transaction_id`	string		関連する継続取引のID（サブスクリプションなど）
`metadata.service_user_id`	string	○	ユーザーの NP サービス内における ID（加盟店側のmerchant_user_idと対応）
`metadata.service_user_name`	string		サービス内でのユーザー表示名（電話番号の一部をマスクした形式）
`metadata.options`	array	○	取引オプション（統合ガイドを参照）
`metadata.options[]`	integer	○	取引オプション（統合ガイドを参照）
`merchant_transaction_id`	string	○	加盟店側の取引ID（ユニーク、NP側のservice_transaction_idと対応）
`amount`	integer	○	取引金額
`currency`	string	○	取引通貨コード（ISO 4217形式）
`description`	string		取引の備考
`authorization`	object	○	与信審査の情報
`authorization.result`	integer	○	与信審査の結果（1:承認、2:拒否）
`authorization.ng_reason`	integer		与信拒否の理由（1:上限金額不足、9:その他事由、null:承認時）
`timeline`	object	○	取引の時系列情報
`timeline.registration_timestamp`	epoch_time	○	取引登録日時
`timeline.settlement_timestamp`	epoch_time		売上確定日時
`timeline.reversal_timestamp`	epoch_time		取り消し日時
`buyer`	object		購入者情報
`buyer.name`	string		顧客名
`buyer.phone`	string		電話番号
`buyer.address`	string		住所
`buyer.email`	string		メールアドレス
`buyer.merchant_user_id`	string		加盟店会員 ID（NP側のservice_user_idと対応）
`recipients`	array		配送先一覧
`recipients[].name`	string		配送先氏名
`recipients[].phone`	string		配送先電話番号
`recipients[].address`	string		配送先住所
`recipients[].email`	string		配送先メールアドレス
`items`	array		購入商品リスト
`items[].id`	string		商品ID
`items[].name`	string		商品名
`items[].category`	string		商品カテゴリ
`items[].unit_price`	integer		単価
`items[].quantity`	integer		数量
`reversal`	object		取り消し情報
`reversal.amount`	integer		取り消し金額
`reversal.reason`	string		取り消し理由
`reversal.description`	string		取り消し備考

{
  "metadata": {
    "object": "transaction",
    "service_transaction_id": "tr_GyhcP2Z8yh28AYS_",
    "merchant_id": "atn00001-00001",
    "livemode": true,
    "parent_transaction_ids": [],
    "recurring_transaction_id": null,
    "service_user_id": "np_user_id_001",
    "service_user_name": "090****1234",
    "options": []
  },
  "merchant_transaction_id": "1685354884137Zx2FB217",
  "amount": 4539,
  "currency": "JPY",
  "description": "サンプル取引の備考",
  "authorization": {
    "result": 1,
    "ng_reason": null
  },
  "timeline": {
    "registration_timestamp": 1718208000,
    "settlement_timestamp": null
  },
  "buyer": {
    "name": "山田太郎",
    "phone": "0900000000",
    "address": "東京都千代田区神田錦町3-7-1",
    "email": "test@example.com",
    "merchant_user_id": "shop-user-no-001"
  },
  "recipients": [],
  "items": [
    {
      "id": "ITEM-001",
      "name": "プレミアム商品A",
      "category": "electronics",
      "unit_price": 2500,
      "quantity": 1
    },
    {
      "id": "ITEM-002",
      "name": "アクセサリーB",
      "category": "accessories",
      "unit_price": 2039,
      "quantity": 1
    }
  ],
  "reversal": null
}

User Token オブジェクト

ユーザートークン管理時にやり取りされるデータの構造化スキーマ

Property	型	必須	説明
`metadata`	object	○	システムメタデータ情報
`metadata.object`	string	○	オブジェクトの種別例: `user_token`
`metadata.livemode`	boolean	○	本番環境かどうかの真偽値
`merchant_user_id`	string		加盟店会員ID 長さ ≥ 1 長さ ≤ 64 許容文字: 英数字 , `_` , `-`
`service_user_id`	string	○	ユーザーの NP サービス内における ID
`service_user_name`	string	○	サービス内でのユーザー表示名（電話番号の一部をマスクした形式）
`active`	boolean	○	トークンが有効かどうか（true: 有効、false: 失効済み）
`timeline`	object	○	トークンの時系列情報
`timeline.issuance_timestamp`	epoch_time	○	トークン発行日時
`timeline.revocation_timestamp`	epoch_time		トークン失効日時（失効済みの場合のみ）

{
  "metadata": {
    "object": "user_token",
    "livemode": true
  },
  "merchant_user_id": "shop-user-no-001",
  "service_user_id": "np_user_id_001",
  "service_user_name": "090****1234",
  "active": true,
  "timeline": {
    "issuance_timestamp": 1718208000,
    "revocation_timestamp": null
  }
}

Error オブジェクト

APIリクエストが失敗した際に返されるエラーレスポンスオブジェクト

Property	型	必須	説明
`object`	string	○	オブジェクトの種別（常に "error"）例: `error`
`code`	string	○	発生したエラーの種類を示すエラーコード例: `INVALID_REQUEST_PARAM`
`messages`	array	○	エラーの詳細を提供するエラーメッセージの配列例: `["amount is required"]`
`messages[]`	string	○

{
  "object": "error",
  "code": "INVALID_REQUEST_PARAM",
  "messages": ["amount is required"]
}

エラーコード一覧

Code	HTTP	Occurs When	Resolution	Retryable
`INVALID_REQUEST_PARAM`	400	Request has missing/invalid parameters, invalid JSON, or wrong Content-Type	Check required parameters and ensure valid JSON format with correct Content-Type header	×
`UNAUTHORIZED`	401	Missing or invalid authentication credentials, or token expired	Verify your authentication credentials. Contact your Customer Success Manager for authentication details	×
`NO_SERVICE_CONTRACT`	403	Authenticated but operation not permitted due to missing/invalid service contract or insufficient permissions	Contact support to verify service contract configuration and merchant permissions	×
`RESOURCE_NOT_FOUND`	404	The specified resource does not exist	Verify the resource ID and ensure it exists in the system	×
`CONFLICT`	409	Operation conflicts with current state (already processed, duplicate ID, token already used)	Use a unique identifier or check the current resource state before retrying	×
`INTERNAL_ERROR`	500	Unexpected server error occurred while processing the request	Retry the request. Contact support if the issue persists	○
`SERVICE_UNAVAILABLE`	503	Service is temporarily down or under maintenance	Wait and retry. Contact support if the issue persists	○
`GATEWAY_TIMEOUT`	504	Service is temporarily down or under maintenance	Wait and retry. Contact support if the issue persists	○