Concepts
Payment intents
A payment intent is your server’s record of one payment you expect: who it settles to, how much, in which asset, and for how long it is protected.
What an intent holds
| Field | Meaning |
|---|---|
recipient | The wallet the payment settles to: your business, a marketplace seller, a provider. Set per intent. |
amount | A string in the asset’s smallest unit, greater than zero. |
asset | The asset’s address. It must be your environment’s asset (Environments). |
protectionPeriod | How long the buyer is protected after paying. |
merchantReference | Optional, up to 128 characters: your order id. Unique among your open intents. |
metadata | Optional: up to 20 keys (a-z, 0-9, _, up to 40 characters) with string values up to 500 characters, 4 KB in all. |
expiresInSeconds | Optional: how long the intent accepts payment, 300 to 604800 seconds. Defaults to 86400 (24 hours). |
Protection periods
| Value | Period |
|---|---|
oneHour | 1 hour |
oneDay | 1 day |
threeDays | 3 days |
sevenDays | 7 days |
fourteenDays | 14 days |
thirtyDays | 30 days |
Status
| Status | Meaning |
|---|---|
requires_payment | Created and waiting for the buyer. checkoutUrl links to its hosted checkout. |
protected | Paid. The funds are held until release, expiry, or a dispute settles them. |
disputed | The buyer opened a dispute. The funds stay held. |
released | Settled to the recipient. Final. |
refunded | Refunded to the buyer. Final. |
canceled | You canceled it before it was paid. |
expired | Nobody paid it before expiresAt. |
Once paid, an intent’s status follows its payment’s state.
How a payment is matched to an intent
Each intent has a paymentId. The buyer’s payment is created with that id, and it is linked to the intent only after Protected Pay reads it from the network and confirms that its recipient, amount, asset, and protection period match the intent exactly.
- The same buyer cannot pay one intent twice: the payment’s address is derived from the buyer and the
paymentId. - If a second buyer pays an intent that is already paid, that payment is recorded as a duplicate (
role: "duplicate", eventpayment.duplicate). It is a complete protected payment with its own protection period and dispute rights. - A payment made after the intent expired or was canceled is still linked to it, marked
late: true.
Canceling
An intent can be canceled while it is requires_payment. Canceling closes the hosted checkout. A payment the buyer was already signing still completes, and is linked and marked late.