Statuses
The Merchant API uses three sets of statuses: transaction statuses for payouts, transfers, and other transactions; payment statuses for orders paid through crypto invoices; and invoice statuses that describe a crypto payment in more detail.
Transaction statuses
Returned by Get transaction and Get transaction history.
| Status | Meaning | Final |
|---|---|---|
CREATED | The transaction has been created. | No |
READY_TO_PROCESS | The transaction is ready for processing. | No |
PENDING | The transaction is waiting for an action or a check. | No |
PROCESSING | The transaction is being processed. | No |
EXCHANGING | Currency conversion is in progress. | No |
COMPLETED | The transaction has been completed. | Yes |
CANCELLING | Cancellation is in progress. | No |
CANCELED | The transaction has been canceled. | Yes |
REFUNDING | A refund is in progress. | No |
REFUNDED | The transaction has been refunded. | Yes |
Treat a payout as completed only when its status is COMPLETED. Keep tracking a transaction until it reaches a final status.
A final status can still change if a refund is made later: a COMPLETED transaction then moves to REFUNDING and REFUNDED.
Payment statuses
Returned in paymentStatus by Get payment order.
| Status | Meaning | Recommended action |
|---|---|---|
CREATED | The invoice is created. Volet.com has not finished processing a payment for it. | Keep the order pending. |
PROCESSING | Volet.com is processing the payment. | Keep the order pending. |
COMPLETED | The payment is completed, and the funds are credited to your account. Final status. | Mark the order as paid and fulfill it. |
FAILED | The payment failed or its transaction was canceled. Final status. | Do not fulfill the order. |
paymentStatus has no value for refunds. A refund shows in transaction.status and invoice.invoiceStatus.
When the invoice expires, paymentStatus does not change to FAILED by itself: a customer can still send a payment after the expiration time.
Invoice statuses
Returned in invoice.invoiceStatus by Get payment order. Use them to explain a problem payment, not to decide whether the order is paid.
| Status | Meaning |
|---|---|
NEW | The invoice is created, and no payment has been received yet. |
RECEIVED | A blockchain transaction for the invoice is received. Checks can still be running, so the funds are not credited yet. |
EXCHANGING | Volet.com is converting the received crypto to the receiver currency. |
COMPLETED | The invoice is processed, and the funds are credited to your account. |
REFUND_CONFIRMATION | A refund of the payment is waiting for confirmation. |
REFUND_REQUESTED | A refund is requested. |
REFUNDED | The payment is returned to the customer. |
CLOSED | The invoice is closed. |
invoice.penalties lists how the received payment differs from the invoice. It is empty when the payment matches:
UNDERPAYMENT— the customer sent less thansenderAmount.OVERPAYMENT— the customer sent more thansenderAmount. A small overpayment within the allowed tolerance is not flagged.EXPIRED— the payment arrived after the invoice expired. Such a payment is not credited automatically.
invoice.externalStatus combines invoiceStatus and penalties into one value, for example UNDERPAYMENT_RECEIVED or EXPIRED_PAYMENT_REFUNDED. PAYMENT_RECEIVED does not mean that the funds are credited. Use externalStatus for display only.
Related
- Errors — error format and how to handle errors
- API integration for accepting payments — the full payment flow
- API integration for mass payouts — the full payout flow