Invoice API

服务地址: https://invoice-api.psp.example.com
认证: Ed25519 签名
版本: 1.0.0
OpenAPI: 下载规范

Invoice service surface for merchant invoice write flows. This service only accepts invoice account secrets and rejects transfer/query/webhook/proof traffic. A missing X-API-ID header returns 400 INVALID_REQUEST. A missing X-API-Key header or invalid credentials return 401 UNAUTHORIZED. A credential store failure returns 500 INTERNAL_ERROR before the request handler runs.

Invoice Payment Intents

Create a invoice payment intent

POST/api/v1/payments/intents

Requires a invoice account secret and invoices:write scope.

Send the idempotency key in X-Idempotency-Key or Idempotency-Key; at least one is required. When both are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. The Ed25519 signature covers X-Idempotency-Key when it is sent, otherwise Idempotency-Key.

Unlike other write operations, this one is not deduplicated by the idempotency key: the gateway keeps no response cache for it, and the key does not decide retries. The invoice service identifies a retry by merchant_order_id within the merchant account; reusing a merchant_order_id with a different request is rejected with 409 CONFLICT.

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`payment_method`	enum	必填	可选值：`pix`、`spei`、`upi`、`credit_card`、`apple_pay`、`google_pay`、`cash_app`、`paypal`、`zelle`、`chime`、`venmo`、`emt`、`boleto`
`rail_variant`	string	必填	Canonical rail variant paired with payment_method; cash_app accepts standard/ecashapp, paypal accepts standard/epaypal, and zelle/chime/venmo/emt use standard.
`amount`	integer<int64>	必填	≥ 1
`currency`	string	必填	最短 3 · 最长 3
`instruction`	object	可选	—
`items`	object[]	可选	—
`items[].name`	string	必填	最长 160
`items[].description`	string	可选	最长 500
`items[].sku`	string	可选	最长 80
`items[].quantity`	integer	必填	≥ 1 · ≤ 999999
`items[].unit_amount`	integer<int64>	必填	≥ 0
`items[].currency`	string	可选	最短 3 · 最长 3
`items[].image_url`	string<uri>	可选	最长 2048
`payer_info`	object	可选	—
`payer_info.name`	string	可选	最长 200
`payer_info.tax_id`	string	可选	付款人证件号。账户 payin_payer_validation_mode 为 optional 或 required 且提交了本字段时，须符合账户市场格式：巴西 CPF（11 位数字含校验位）或 CNPJ （14 位，数字或字母数字，含官方校验位，例如 00.000.000/E08G-12）；墨西哥 RFC （12 或 13 位，日期段月份 01–12、日期 01–31）。格式错误返回 INVALID_REQUEST。 required 档未提交亦返回 INVALID_REQUEST。 · 最长 50
`payer_info.email`	string<email>	可选	最长 200
`payer_info.phone`	string	可选	最长 50
`payer_info.account`	string	可选	最长 200
`description`	string	可选	最长 500
`merchant_order_id`	string	必填	最长 100
`return_url`	string<uri>	可选	HTTPS return URL for provider-hosted checkout or 3DS completion. · 最长 500
`webhook_url`	string<uri>	可选	最长 500
`expires_in_minutes`	integer	可选	≥ 1 · ≤ 1440
`allow_different_amount`	boolean	可选	—
`allow_multiple_payments`	boolean	可选	—
`metadata`	object	可选	—

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/payments/intents' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_method": "pix",
    "rail_variant": "standard",
    "amount": 1,
    "currency": "string",
    "instruction": {},
    "items": [
      {
        "name": "string",
        "description": "string",
        "sku": "string",
        "quantity": 1,
        "unit_amount": 0,
        "currency": "string",
        "image_url": "https://example.com"
      }
    ],
    "payer_info": {
      "name": "string",
      "tax_id": "string",
      "email": "[email protected]",
      "phone": "string",
      "account": "string"
    },
    "description": "string",
    "merchant_order_id": "string",
    "return_url": "https://example.com",
    "webhook_url": "https://example.com",
    "expires_in_minutes": 1,
    "allow_different_amount": false,
    "allow_multiple_payments": false,
    "metadata": {}
  }'

响应

Payment intent created

字段	类型	必填	说明
`id`	string<uuid>	必填	—
`invoice_number`	string	必填	—
`payment_method`	string	必填	—
`classification`	object	可选	—
`amount`	integer<int64>	必填	—
`currency`	string	必填	—
`paid_amount`	integer<int64>	可选	—
`refunded_amount`	integer<int64>	可选	—
`status`	string	必填	—
`state`	string	可选	—
`merchant_order_id`	string	可选	—
`payment_url`	string	可选	—
`psp_checkout_url`	string	可选	—
`provider_checkout_url`	string	可选	—
`payment_url_source`	string	可选	—
`instruction`	object	可选	—
`expected_payer_info`	object	可选	—
`expected_payer_info.name`	string	可选	最长 200
`expected_payer_info.tax_id`	string	可选	付款人证件号。账户 payin_payer_validation_mode 为 optional 或 required 且提交了本字段时，须符合账户市场格式：巴西 CPF（11 位数字含校验位）或 CNPJ （14 位，数字或字母数字，含官方校验位，例如 00.000.000/E08G-12）；墨西哥 RFC （12 或 13 位，日期段月份 01–12、日期 01–31）。格式错误返回 INVALID_REQUEST。 required 档未提交亦返回 INVALID_REQUEST。 · 最长 50
`expected_payer_info.email`	string<email>	可选	最长 200
`expected_payer_info.phone`	string	可选	最长 50
`expected_payer_info.account`	string	可选	最长 200
`payer_info`	object	可选	—
`payer_info.name`	string	可选	最长 200
`payer_info.tax_id`	string	可选	付款人证件号。账户 payin_payer_validation_mode 为 optional 或 required 且提交了本字段时，须符合账户市场格式：巴西 CPF（11 位数字含校验位）或 CNPJ （14 位，数字或字母数字，含官方校验位，例如 00.000.000/E08G-12）；墨西哥 RFC （12 或 13 位，日期段月份 01–12、日期 01–31）。格式错误返回 INVALID_REQUEST。 required 档未提交亦返回 INVALID_REQUEST。 · 最长 50
`payer_info.email`	string<email>	可选	最长 200
`payer_info.phone`	string	可选	最长 50
`payer_info.account`	string	可选	最长 200
`items`	object[]	可选	—
`items[].name`	string	必填	最长 160
`items[].description`	string	可选	最长 500
`items[].sku`	string	可选	最长 80
`items[].quantity`	integer	必填	≥ 1 · ≤ 999999
`items[].unit_amount`	integer<int64>	必填	≥ 0
`items[].currency`	string	可选	最短 3 · 最长 3
`items[].image_url`	string<uri>	可选	最长 2048
`allow_different_amount`	boolean	可选	—
`allow_multiple_payments`	boolean	可选	—
`expires_at`	string<date-time>	可选	—
`created_at`	string<date-time>	必填	—
`updated_at`	string<date-time>	必填	—
`metadata`	object	可选	—

{
  "id": "00000000-0000-7000-8000-000000000000",
  "invoice_number": "string",
  "payment_method": "string",
  "classification": {},
  "amount": 0,
  "currency": "string",
  "paid_amount": 0,
  "refunded_amount": 0,
  "status": "string",
  "state": "string",
  "merchant_order_id": "string",
  "payment_url": "string",
  "psp_checkout_url": "string",
  "provider_checkout_url": "string",
  "payment_url_source": "string",
  "instruction": {},
  "expected_payer_info": {
    "name": "string",
    "tax_id": "string",
    "email": "[email protected]",
    "phone": "string",
    "account": "string"
  },
  "payer_info": {
    "name": "string",
    "tax_id": "string",
    "email": "[email protected]",
    "phone": "string",
    "account": "string"
  },
  "items": [
    {
      "name": "string",
      "description": "string",
      "sku": "string",
      "quantity": 1,
      "unit_amount": 0,
      "currency": "string",
      "image_url": "https://example.com"
    }
  ],
  "allow_different_amount": false,
  "allow_multiple_payments": false,
  "expires_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "metadata": {}
}

Cancel a invoice payment intent

POST/api/v1/payments/intents/{invoice_number}/cancel

路径参数

名称	类型	必填	说明
`invoice_number`	string	必填	—

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json

字段	类型	必填	说明
`reason`	string	可选	最长 500

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/payments/intents/{invoice_number}/cancel' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "string"
  }'

响应

Payment intent canceled

字段	类型	必填	说明
`status`	enum	必填	可选值：`canceled`

{
  "status": "canceled"
}

Create a invoice refund

POST/api/v1/payments/intents/{invoice_number}/refund

The same header key is also the refund’s business idempotency key within the merchant: a retry with the same key returns the existing refund, and reusing the key for a different refund is rejected with 409 CONFLICT.

New requests evaluate the original account’s published refund rules before creating the refund or freezing funds. A block returns 403 RISK_REJECTED; risk dependency failure returns 503 SERVICE_UNAVAILABLE. The refund amount is evaluated against the original frozen method/rail; no new invoice or transfer limit reservation is created.

路径参数

名称	类型	必填	说明
`invoice_number`	string	必填	—

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`amount`	integer<int64>	必填	≥ 1
`reason`	string	可选	最长 500
`metadata`	object	可选	—

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/payments/intents/{invoice_number}/refund' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1,
    "reason": "string",
    "metadata": {}
  }'

响应

Invoice refund created

字段	类型	必填	说明
`id`	string<uuid>	必填	—
`invoice_number`	string	必填	—
`refund_number`	string	必填	—
`original_intent_id`	string<uuid>	可选	—
`amount`	integer<int64>	必填	—
`currency`	string	必填	—
`status`	string	必填	—
`reason`	string	可选	—
`created_at`	string<date-time>	可选	—
`updated_at`	string<date-time>	可选	—

{
  "id": "00000000-0000-7000-8000-000000000000",
  "invoice_number": "string",
  "refund_number": "string",
  "original_intent_id": "00000000-0000-7000-8000-000000000000",
  "amount": 0,
  "currency": "string",
  "status": "string",
  "reason": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Invoice Credit Cards

Create a credit card authorization

POST/api/v1/cards/authorizations

This operation has two idempotency layers. The header key is covered by the signature and deduplicates the request at the gateway. The required JSON field idempotency_key in the request body is the business idempotency key: the card service uses it to recognize a retried authorization within the merchant account. The gateway does not check that the two values are equal. Send the same value in both places and keep it unchanged when retrying.

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`invoice_number`	string	必填	—
`idempotency_key`	string	必填	—
`channel_id`	string<uuid>	必填	—
`amount`	integer<int64>	必填	≥ 1
`currency`	string	必填	最短 3 · 最长 3
`card_token`	string	可选	—
`card_cvv`	string	可选	—
`card_info`	object	可选	—
`card_info.card_number`	string	必填	—
`card_info.cvv`	string	必填	—
`card_info.expiry_month`	integer	必填	≥ 1 · ≤ 12
`card_info.expiry_year`	integer	必填	—
`card_info.cardholder_name`	string	必填	—
`payer_info`	object	必填	—
`payer_info.name`	string	必填	—
`payer_info.email`	string<email>	必填	—
`payer_info.phone`	string	可选	—
`description`	string	可选	—
`merchant_order_id`	string	可选	—
`require_3ds`	boolean	可选	—
`pre_auth`	boolean	可选	—
`metadata`	object	可选	—

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/cards/authorizations' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_number": "string",
    "idempotency_key": "string",
    "channel_id": "00000000-0000-7000-8000-000000000000",
    "amount": 1,
    "currency": "string",
    "card_token": "string",
    "card_cvv": "string",
    "card_info": {
      "card_number": "string",
      "cvv": "string",
      "expiry_month": 1,
      "expiry_year": 0,
      "cardholder_name": "string"
    },
    "payer_info": {
      "name": "string",
      "email": "[email protected]",
      "phone": "string"
    },
    "description": "string",
    "merchant_order_id": "string",
    "require_3ds": false,
    "pre_auth": false,
    "metadata": {}
  }'

响应

201 Created
500 Server Error

Authorization created

Complete 3DS for an authorization

POST/api/v1/cards/authorizations/{authorization_id}/complete-3ds

The header key only signs and deduplicates the request; the request body has no idempotency_key. A replayed completion is rejected by the one-time cres_nonce with 409 CONFLICT.

路径参数

名称	类型	必填	说明
`authorization_id`	string	必填	—

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`invoice_id`	string<uuid>	必填	—
`transaction_id`	string	必填	—
`auth_value`	string	必填	—
`eci`	string	必填	—
`cres_nonce`	string	必填	—

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/cards/authorizations/{authorization_id}/complete-3ds' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_id": "00000000-0000-7000-8000-000000000000",
    "transaction_id": "string",
    "auth_value": "string",
    "eci": "string",
    "cres_nonce": "string"
  }'

响应

Authorization updated

Capture a credit card authorization

POST/api/v1/cards/captures

This operation has two idempotency layers. The header key is covered by the signature and deduplicates the request at the gateway. The required JSON field idempotency_key in the request body is the business idempotency key: the card service uses it to recognize a retried capture. The gateway does not check that the two values are equal. Send the same value in both places and keep it unchanged when retrying.

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`invoice_id`	string<uuid>	必填	—
`capture_amount`	integer<int64>	必填	≥ 1
`idempotency_key`	string	必填	—
`reason`	string	可选	—

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/cards/captures' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_id": "00000000-0000-7000-8000-000000000000",
    "capture_amount": 1,
    "idempotency_key": "string",
    "reason": "string"
  }'

响应

Capture completed

字段	类型	必填	说明
`invoice_id`	string<uuid>	可选	—
`captured_amount`	integer<int64>	可选	—
`total_captured`	integer<int64>	可选	—
`status`	string	可选	—
`captured_at`	string<date-time>	可选	—

{
  "invoice_id": "00000000-0000-7000-8000-000000000000",
  "captured_amount": 0,
  "total_captured": 0,
  "status": "string",
  "captured_at": "2026-01-01T00:00:00Z"
}

Create a credit card refund

POST/api/v1/cards/refunds

This operation has two idempotency layers. The header key is covered by the signature and deduplicates the request at the gateway. The required JSON field idempotency_key in the request body is the business idempotency key: within the merchant account, a retry with the same idempotency_key and the same refund returns the first refund, and reusing it for a different refund is rejected with 409 DUPLICATE_IDEMPOTENCY_KEY. The gateway does not check that the two values are equal. Send the same value in both places and keep it unchanged when retrying.

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`invoice_id`	string<uuid>	必填	—
`idempotency_key`	string	必填	—
`merchant_refund_id`	string	可选	—
`refund_amount`	integer<int64>	必填	≥ 1
`reason`	string	可选	—
`notes`	string	可选	—
`metadata`	object	可选	—

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/cards/refunds' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_id": "00000000-0000-7000-8000-000000000000",
    "idempotency_key": "string",
    "merchant_refund_id": "string",
    "refund_amount": 1,
    "reason": "string",
    "notes": "string",
    "metadata": {}
  }'

响应

201 Created
500 Server Error

Card refund created

Invoice Tokenization

Tokenize a card

POST/api/v1/tokenization/cards

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`customer_id`	string	必填	—
`card_number`	string	必填	最短 16 · 最长 16
`expiry_month`	string	必填	最短 2 · 最长 2
`expiry_year`	string	必填	最短 4 · 最长 4
`cardholder_name`	string	必填	—
`cvv`	string	可选	最短 3 · 最长 4
`scope`	enum	可选	可选值：`single_use`、`multi_use`、`permanent`

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/tokenization/cards' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "string",
    "card_number": "string",
    "expiry_month": "string",
    "expiry_year": "string",
    "cardholder_name": "string",
    "cvv": "string",
    "scope": "single_use"
  }'

响应

201 Created
500 Server Error

Token created

字段	类型	必填	说明
`token_id`	string	必填	—
`customer_id`	string	必填	—
`token_type`	enum	必填	可选值：`card`、`bank_account`
`scope`	string	可选	—
`created_at`	string<date-time>	必填	—
`expires_at`	string<date-time>	可选	—
`masked_info`	object	必填	—

{
  "token_id": "string",
  "customer_id": "string",
  "token_type": "card",
  "scope": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "expires_at": "2026-01-01T00:00:00Z",
  "masked_info": {}
}

Tokenize a bank account

POST/api/v1/tokenization/bank-accounts

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json · 必填

字段	类型	必填	说明
`customer_id`	string	必填	—
`account_number`	string	必填	—
`bank_code`	string	必填	—
`account_type`	enum	可选	可选值：`checking`、`savings`
`account_holder_name`	string	必填	—
`branch_code`	string	可选	—
`scope`	enum	可选	可选值：`single_use`、`multi_use`、`permanent`

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/tokenization/bank-accounts' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "string",
    "account_number": "string",
    "bank_code": "string",
    "account_type": "checking",
    "account_holder_name": "string",
    "branch_code": "string",
    "scope": "single_use"
  }'

响应

201 Created
500 Server Error

Token created

字段	类型	必填	说明
`token_id`	string	必填	—
`customer_id`	string	必填	—
`token_type`	enum	必填	可选值：`card`、`bank_account`
`scope`	string	可选	—
`created_at`	string<date-time>	必填	—
`expires_at`	string<date-time>	可选	—
`masked_info`	object	必填	—

{
  "token_id": "string",
  "customer_id": "string",
  "token_type": "card",
  "scope": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "expires_at": "2026-01-01T00:00:00Z",
  "masked_info": {}
}

Detokenize a token

POST/api/v1/tokenization/tokens/{token_id}/detokenize

路径参数

名称	类型	必填	说明
`token_id`	string	必填	—

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/tokenization/tokens/{token_id}/detokenize' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>'

响应

200 OK
500 Server Error

Sensitive token data returned

Extend a token

POST/api/v1/tokenization/tokens/{token_id}/extend

路径参数

名称	类型	必填	说明
`token_id`	string	必填	—

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求体 application/json

字段	类型	必填	说明
`extension_days`	integer	可选	≥ 1 · ≤ 365 · 默认 `365`

请求示例

curl -X POST 'https://invoice-api.psp.example.com/api/v1/tokenization/tokens/{token_id}/extend' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "extension_days": 365
  }'

响应

200 OK
500 Server Error

Token extended

Revoke a token

DELETE/api/v1/tokenization/tokens/{token_id}

路径参数

名称	类型	必填	说明
`token_id`	string	必填	—

请求头

名称	类型	必填	说明
`X-Idempotency-Key`	string	可选	Idempotency key. Send it in this header or in Idempotency-Key; at least one of the two is required. When this header is sent, the Ed25519 signature covers its value. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1
`Idempotency-Key`	string	可选	Idempotency key, alternative to X-Idempotency-Key; at least one of the two is required. The Ed25519 signature covers this header only when X-Idempotency-Key is not sent. If both headers are sent they must be equal, otherwise the request is rejected with 400 INVALID_REQUEST. · 最短 1

请求示例

curl -X DELETE 'https://invoice-api.psp.example.com/api/v1/tokenization/tokens/{token_id}' \
  -H 'X-API-ID: <api-id>' \
  -H 'X-API-Key: <api-key>' \
  -H 'X-Timestamp: <timestamp>' \
  -H 'X-Signature: <signature>'

响应

204 No Content
500 Server Error

Token revoked