Payment Sessions
How Plaidly payment sessions work
Payment Sessions
A payment session is the core primitive in Plaidly. It represents a single payment request — a customer owes you a specific amount in a specific currency on a specific chain.
Lifecycle
pending → partial_paid → finalizing → confirmed/completed
↘ expired
↘ failed| Status | Description |
|---|---|
pending | Session created, awaiting on-chain payment |
partial_paid | Some funds arrived, but the expected amount is not yet satisfied |
finalizing | Payment satisfied and the settlement pipeline is finishing up |
confirmed | Payment fully confirmed — safe to fulfill |
completed | Payment settled and the receipt is ready |
expired | Session TTL elapsed with no payment detected |
failed | Payment detected but amount mismatch or wrong token |
Creating a session
POST /v1/payment_sessions
X-API-Key: your_api_key
{
"amount": 10.0,
"expires_in": "15m",
"paymentMethod": {
"methodID": 0,
"chain": "solana",
"token": "USDC",
"network": "mainnet"
},
"metadata": {
"order_id": "ord_123"
}
}Fields
| Field | Required | Description |
|---|---|---|
amount | Yes | Exact amount as a number |
expires_in | Yes | Expiry duration such as 15m or 1h |
paymentMethod | Yes | Nested chain/token/network descriptor |
metadata | No | Arbitrary key-value pairs, returned in webhooks |
Retrieving a session
GET /v1/payment_sessions/{session_id}
X-API-Key: your_api_keyTolerance window
The API accepts the exact requested amount. Underpayments or wrong-token payments settle as failed; confirmed and completed both mean the session is safe to fulfill.
Expiry
Sessions expire after expires_in. Expired sessions cannot receive payments. Create a new session if a customer needs more time.