PBE-PAY v1

Non-custodial merchant payments.

PBE-PAY binds an order reference to an exact transfer. Merchants verify all three payment dimensions: signed reference, recipient address and amount.

GET/rpc/commerce/info

Commerce capabilities

Public

Returns PBE-PAY version, chain/network IDs, default confirmation policy, settlement model and whether webhooks are enabled on this node.

cURL

Shell

curl https://paybyte.org/rpc/commerce/info

Example response

JSON

{"ok":true,"commerce":{"protocol":"PBE-PAY","version":1,"networkId":1,"chainId":"PBE-MAINNET","defaultConfirmations":12,"highValueConfirmations":30,"hardFinality":false,"settlementModel":"canonical-chain-depth"}}

POST/rpc/commerce/payment-request

Create payment request

Public

Creates a stateless request. The node does not create a merchant order record.

Parameters

Name	Location / Type	Required	Description
recipient	JSON string	yes	Mainnet PBE recipient address.
amount	JSON decimal string	one of amount / amountBaseUnits	PBE amount with up to 8 decimal places.
amountBaseUnits	JSON unsigned integer string	one of amount / amountBaseUnits	Exact base-unit amount.
reference	JSON string	no	Merchant order reference; generated if omitted.
label	JSON string	no	Display label, max 80 bytes.
confirmations	JSON integer	no	Required canonical confirmations; default 12, max 1000.

Request body

JSON

{"recipient":"pbe1...","amount":"25","reference":"order_8f42d1","label":"Golden Sword","confirmations":12}

cURL

Shell

curl -X POST https://paybyte.org/rpc/commerce/payment-request -H "Content-Type: application/json" -d @request.json

Example response

JSON

{"ok":true,"payment":{"protocol":"PBE-PAY","version":1,"networkId":1,"recipient":"pbe1...","amount":"2500000000","amountPbe":"25","reference":"order_8f42d1","label":"Golden Sword","requiredConfirmations":12,"paymentUri":"pbe:pbe1...?amount=25&ref=order_8f42d1&confirmations=12&label=Golden%20Sword","walletPath":"/wallet/?pay=...","statusPath":"/rpc/commerce/payment/order_8f42d1?..."}}

GET/rpc/commerce/payment/{reference}

Verify exact payment

Public

Looks up a transfer by the signed reference and requires the caller to supply the expected recipient and exact amount.

Parameters

Name	Location / Type	Required	Description
reference	path string	yes	Signed payment reference.
recipient	query address	yes	Expected merchant address.
amount	query decimal	one of amount / amountBaseUnits	Expected PBE amount.
amountBaseUnits	query unsigned integer	one of amount / amountBaseUnits	Expected base-unit amount.
confirmations	query integer	no	Confirmation target.

cURL

Shell

curl "https://paybyte.org/rpc/commerce/payment/order_8f42d1?recipient=pbe1...&amount=25&confirmations=12"

Example response

JSON

{"ok":true,"payment":{"state":"confirming","canonical":true,"txid":"...","recipient":"pbe1...","amount":"2500000000","reference":"order_8f42d1","confirmations":5,"requiredConfirmations":12,"hardFinality":false}}

Do not trust reference aloneA payment is valid only when reference, recipient and exact amount all match the merchant order.

Payment states

State	Meaning
unpaid	No matching mempool or canonical transaction is currently visible.
pending	Matching signed transaction is in the node mempool.
confirming	Matching transaction is canonical but below the requested confirmation depth.
confirmed	Matching transaction is canonical and meets the requested confirmation depth.

PBE payment URI

URI

pbe:pbe1MERCHANT...?amount=25&ref=order_8f42d1&confirmations=12&label=Golden%20Sword

The URI is a transport format. The signed transaction remains the authoritative proof. The wallet re-validates the recipient for the connected network and signs the exact tuple from the parsed request.