Docs / Payment statuses
Payment statuses: OPEN, PARTIALLY_FILLED, FILLED, OVER_FILLED and CANCELLED
A payment goes through a few states between creation and completion. Knowing what each means tells you when to ship and when to refund.
The short version: a PayRam payment has just five states. FILLED means paid in full, so ship. PARTIALLY_FILLED is an underpayment, so do not ship yet. OVER_FILLED is an overpayment: ship, and decide what to do with the excess. OPEN is still waiting for payment. CANCELLED means cancelled or expired.
1. The five states at a glance
| State | Meaning | What you do |
|---|---|---|
OPEN | The payment was created and no deposit has been detected yet (or the filled amount is zero) | Keep waiting. The order stays "awaiting payment" |
PARTIALLY_FILLED | A deposit was detected, but the filled amount is less than the requested amount | Do not ship. Ask the customer to top up, or follow your own policy, see below |
FILLED | The filled amount equals the requested amount | Fulfil the order or activate the service as normal |
OVER_FILLED | The filled amount is greater than the requested amount | You can ship, and you decide what to do with the excess |
CANCELLED | The payment was cancelled, usually because the payment link expired | Close the order. Let the customer start again if they still want to buy |
In the dashboard's payment link list you will see a simplified display: Pending, Successful and Cancelled. The API and webhooks use the five values above.
2. How states change
OPEN → (deposit detected → confirming: 1/N, 2/N … N/N) → FILLED
or PARTIALLY_FILLED
or OVER_FILLED
OPEN → CANCELLED (the payment link expired or was cancelled)A payment link expires after 24 hours by default, after which its state becomes CANCELLED. You can set a different window with expire when creating the payment.
3. Confirmation progress: the stage before it settles
An on-chain payment is not instant. It has to wait for block confirmations. During that time webhooks carry two numbers: confirmation_current (confirmations so far) and confirmation_required (confirmations needed), for example 3 / 12 or 5 / 12. You can use them to show "confirming 5 / 12" so the customer knows nothing is stuck.
On the final closed or cancelled notification both numbers are 0. Until the required confirmations are reached, the payment is not treated as settled.
4. How to handle each state
What follows is our suggested approach. Set the exact rules according to your own business policy.
FILLED: paid in full
This is the signal to ship. On receiving the notification, verify the signature and de-duplicate by reference_id, then mark the order paid. For important orders, double-check with the status endpoint. See the webhook guide.
PARTIALLY_FILLED: underpaid
According to the official documentation, an underpaid payment stays incomplete until the full amount is received. Common practice:
- Tell the customer how much is missing and ask them to top up before the payment link expires.
- If it is still short at expiry, you decide: close the order and refund what was received, or agree a top-up with the customer.
- A refund is a new payout sent from the hot wallet. See refunds and payouts.
OVER_FILLED: overpaid
The excess is clearly shown in the dashboard, and you decide: refund the extra to the customer, or record it as a customer credit against future invoices. Whichever you choose, keep a record and note it on the order.
CANCELLED: cancelled or expired
Close the order. If the customer still wants to buy, create a new payment rather than reusing the expired link. If a customer pays after the link has expired, first look up the payment record in the dashboard and then decide whether to refund or reinstate the order. Do not act on assumptions.
5. Ways to reduce underpayments and overpayments
- Warn customers about exchange withdrawal fees. Some exchanges deduct the network fee from the withdrawn amount, so the customer's payment arrives short. Ask customers to choose "fee on top" when withdrawing, or to send slightly more.
- Restrict the coin and network. Use
currencyandnetworkwhen creating a payment to narrow the choice, for example USDC on Base only. That leaves less room for choosing the wrong network. - State the amount and network clearly on the payment page. Sending on the wrong network or the wrong coin may make funds unrecoverable.
- Use stablecoins. With USDT or USDC the amount due is barely affected by price swings, so customers are less likely to come up short because the price moved.
6. Keep your order status in sync with webhooks and the status endpoint
We recommend using both together:
- Webhooks: they tell you the moment the state changes and are your main source.
- The status endpoint: query with the stored
reference_id. ThepaymentStatein the response is the current state. Use it to double-check and as a fallback.
curl --location 'https://pay.payramhost.com/api/v1/payment/reference/<reference_id>' \
--header 'API-Key: <your_api_key>'The full integration flow is in the API integration guide.
7. FAQ
After PARTIALLY_FILLED the customer tops up. Does the state change?
Yes. According to the official documentation an underpaid payment stays incomplete until the full amount arrives. Once the total reaches the requested amount the state becomes FILLED, and you will normally get a new notification. So your handler must not assume "one notification and done". Update on each change of state.
Can the state go backwards, for example from FILLED to OPEN?
In the normal flow states only move forward. To be safe, your handler should accept only a "later" state and ignore stale duplicates.
I received a notification with status OPEN. Is something wrong?
No. OPEN means the payment has been created and no deposit has been detected yet. Keep waiting. Once a deposit is detected, notifications carry the confirmation progress described above.
Can a customer still pay after CANCELLED?
You should not allow it. Treat a cancelled payment as finished and have the customer start a new one.
Related reading
- Webhook guide: How to receive PayRam webhooks: register an endpoint, verify X-Payram-Signature, understand retry rules and payment states, handle duplicates, with Node.js and Python examples.
- Create payments via API: Add crypto payments to your own site with the PayRam API: create a payment and get a payment link, send the customer to the payment page, confirm receipt with webhooks and the status endpoint, and reconcile by order number. With curl, Node.js and Python examples.
- Refunds and payouts: On-chain payments have no chargeback, so refunds are manual. How PayRam payouts work: address book, approvals and one-time codes, limits, status meanings, and what to check before you refund.