Open APIs V1

Copy page

Settle Payment

This is the V1 API. For new integrations we recommend Settle Payment (V2), which is conformant with the x402 v2 specification.

Code
POST /papi/v1/b402/settle

Executes on-chain settlement — submits the payment transaction to BNB Smart Chain. This operation is irreversible. Always call /verify first to validate the payment. Gas is sponsored; the merchant does not need to hold BNB for gas fees.

Request Body

The request body has the same structure as /verify, with one additional field:

Field	Type	Mandatory	Remarks
x402Version	integer	Yes	x402 protocol version (currently 1)
paymentPayload	object	Yes	Same structure as /verify request. See Verify Payment for full field descriptions.
paymentRequirements	object	Yes	Same structure as /verify request. See Verify Payment for full field descriptions.
settleAmount	string	Only for permit2-upto	The actual amount to settle, in the token's smallest unit. Must be ≤ the authorized amount in the signature. Ignored for eip3009 and permit2-exact modes.

Example — EIP-3009 Settle

Code
{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "eip155:56",
    "payload": {
      "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b",
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "to": "0x8B3a350e2f3E6B9cC6FB10Fd106bA08f08bec5D2",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "1710000600",
        "nonce": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:56",
    "amount": "1000000",
    "resource": "https://api.example.com/premium/data",
    "description": "Premium API access",
    "payTo": "0x8B3a350e2f3E6B9cC6FB10Fd106bA08f08bec5D2",
    "asset": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "USD Coin",
      "version": "2",
      "assetTransferMethod": "eip3009",
      "facilitatorAddress": "0x1111111111111111111111111111111111111111"
    }
  }
}

Example — Permit2 Upto Settle (with settleAmount)

Code
{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "eip155:56",
    "payload": {
      "signature": "0x112233...65bytes...4455",
      "permit2Authorization": {
        "permitted": {
          "token": "0x55d398326f99059ff775485246999027b3197955",
          "amount": "100000000"
        },
        "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "spender": "0x3333333333333333333333333333333333333333",
        "nonce": "5",
        "deadline": "1710086400",
        "witness": {
          "to": "0x8B3a350e2f3E6B9cC6FB10Fd106bA08f08bec5D2",
          "facilitator": "0x1111111111111111111111111111111111111111",
          "validAfter": "0"
        }
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:56",
    "amount": "100000000",
    "resource": "https://ai.example.com/api/v1/chat",
    "description": "AI Agent API - per-request billing",
    "payTo": "0x8B3a350e2f3E6B9cC6FB10Fd106bA08f08bec5D2",
    "asset": "0x55d398326f99059ff775485246999027b3197955",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "Tether USD",
      "version": "1",
      "assetTransferMethod": "permit2-upto",
      "facilitatorAddress": "0x3333333333333333333333333333333333333333"
    }
  },
  "settleAmount": "3000000"
}

In this example, the buyer authorized up to 100 USDT ("100000000") but the merchant only charges 3 USDT ("3000000") for this request.

Response Body

Field	Type	Presence	Remarks
success	boolean	Always	Whether the settlement succeeded
transaction	string	When TX submitted	On-chain transaction hash. 0x-prefixed, 32-byte hex string. Present on both success and on-chain failure.
payer	string	Always	Payer wallet address
network	string	When success=true	Settlement network in CAIP-2 format (e.g. "eip155:56")
amount	string	When success=true	Actual settled amount in token's smallest unit. For permit2-upto, equals the requested settleAmount; for other methods, equals the full signed amount.
confirmations	integer	When success=true	Number of block confirmations waited
errorReason	string	Only when success=false	Machine-readable failure reason
errorMessage	string	Only when success=false	Human-readable failure description

Example — Successful Settlement

Code
{
  "code": "000000",
  "message": "success",
  "data": {
    "success": true,
    "transaction": "0x89c91c789e57059b17285e7ba1716a1f5ff4c5dace0ea5a5135f26158d0421b9",
    "payer": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "network": "eip155:56",
    "amount": "1000000",
    "confirmations": 3
  }
}

Example — Failed Settlement

Code
{
  "code": "000000",
  "message": "success",
  "data": {
    "success": false,
    "errorReason": "settle_exact_failed_onchain",
    "errorMessage": "Transaction reverted: authorization is used",
    "payer": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "transaction": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Notes:

• An on-chain failure (e.g., nonce already used, token revert) still returns HTTP 200 with code: "000000". Check the success field in data for the settlement outcome.
• Irreversible operation. Once a settlement transaction is broadcast and confirmed on-chain, it cannot be reversed.
• Idempotent. A given (nonce, network, payer) tuple can only be settled once. Duplicate calls return the cached result without re-broadcasting.
• settleAmount behavior by mode:
  • eip3009 / permit2-exact — the settleAmount field is ignored; the full signed amount is always transferred.
  • permit2-upto — settleAmount is required and specifies the actual transfer amount. Must be ≤ permit2Authorization.permitted.amount.
• Settlement response times vary by amount. Small payments typically settle in ~10 seconds; medium payments in ~25 seconds; large payments may take up to ~45 seconds.
• Rate limit: 20 requests per second per merchant (X-Tesla-ClientId).
• All token transfers occur strictly peer-to-peer on the public blockchain from the buyer's wallet directly to the merchant's wallet. The Facilitator contract validates signatures and forwards the transfer on-chain but never holds tokens in custody.

ErrorReason Values

Machine-readable reasons returned in the errorReason field when success is false:

Value	Description
settle_exact_failed_onchain	On-chain transaction reverted
settle_exact_evm_transaction_confirmation_timed_out	Transaction confirmation timed out
settle_exact_node_failure	BSC RPC node unavailable
settle_service_unavailable	Settle service is temporarily unavailable
(any InvalidReason value)	Payment validation failed during settle — see InvalidReason Values for the full list