Track and cancel a transfer
After you create a transfer, you follow it through its states to an outcome. For each state, the table below gives its meaning, what to show the customer and what you do. Cancellation, failed payouts, refunds, errors and reconciliation follow the table.
Follow a transfer
- Events. Nodu sends a webhook event when the state of a transfer changes. The event type ends with the name of the new state: for example,
v1.transfer.payment_processed. Each event carries thetransferas it was at that moment. See Receive and verify webhooks. - The current state. Retrieve a transfer returns the
state, thesourceDepositInstructions, thereceiptand anyrequirements.
An event is a notification, not the current state. Process each event once. When an event conflicts with what you know, retrieve the transfer.
The order of the states
In the diagram, the green states are final. The red states mean that the payout failed or that processing stopped. A transfer in error moves on when Nodu resolves the error: to undeliverable, returned or refunded.
A transfer usually moves through these states in order:
awaiting_fundsin_reviewfunds_receivedpayment_submittedpayment_processed
During the review, a transfer can wait in info_required. A transfer whose destination is a Nodu wallet goes from funds_received straight to payment_processed.
- Only
canceledandrefundedare sure to be final. A transfer inpayment_processedcan still move toreturned, if the payout comes back later. - Nodu can fill some
receiptfields after the eventv1.transfer.payment_processed. UsesourceTxHashto reconcile incoming crypto anddestinationTxHashto reconcile a blockchain payout. If a field is missing, retrieve the transfer again.
Transfer states
The column "What to show the customer" is a suggestion for your interface. The API does not require it.
state | Meaning | What to show the customer | What you do |
|---|---|---|---|
awaiting_funds | Nodu is waiting for the payment that funds the transfer. For a transfer funded from a Nodu wallet, Nodu is waiting for enough balance. | Deposit instructions for an external payment; a balance-wait message for a Nodu wallet source. | Wait for funding. You can update the amount or fee, or cancel the transfer. |
in_review | The funds have arrived. Nodu is reviewing the transfer. | The payment has arrived and the transfer is being checked. | Nothing. Wait for the next event. |
info_required | The customer must complete an action before Nodu continues. | The action, and where the customer completes it. | See Handle the info_required state. |
funds_received | The review is complete. Nodu is preparing the payout. | The transfer is in progress. | Nothing. |
payment_submitted | Nodu has sent the payout. Its arrival is not confirmed yet. | The payout is on its way. | Nothing. |
payment_processed | The payout has arrived at the destination. | The result and the details of the receipt. | Record the outcome. |
undeliverable | Nodu could not deliver the payout. For example, the destination is not valid. The state can also follow error. | The payout failed. A refund to the payer is pending. | See Failed payouts and refunds. |
returned | The payout came back to Nodu after Nodu sent it. The state can also follow error. | The payout failed. A refund to the payer is pending. | See Failed payouts and refunds. |
refunded | The funds are back with the payer: the party that funded the transfer. The state can also follow error. | The funds were refunded. | Record the outcome. |
canceled | The transfer was canceled before it was funded. | The transfer is canceled. The customer must not pay. | Record the outcome. |
error | Processing stopped. Nodu must handle the transfer manually. | The transfer is on hold. | See Errors. |
Cancel a transfer
Cancel a transfer works only while the transfer is awaiting_funds. After a successful request, the transfer is canceled.
- Check the response. Funds can arrive while you cancel. The transfer is then no longer
awaiting_funds. Nodu refuses the request with a business rule violation, which hasrule=transfer_cannot_be_cancelled. Retrieve the transfer and continue to track it. - Tell the customer not to pay. A canceled transfer must not be funded.
- If the customer has already paid, contact Nodu. Cancellation does not reverse a payment that the customer has made.
Failed payouts and refunds
undeliverable and returned both mean that the payout did not reach the recipient. In both states, Nodu holds the funds. A refund to the payer follows.
- Only
refundedconfirms that the payer has the funds back. - Do not promise the customer a time for the refund.
- Do not ask the customer to pay again before the first transfer is resolved.
- When the destination was not valid, register a new external account with the correct details. Use it for the next transfer.
Errors
error means that processing has stopped. Nodu must handle the transfer manually. Contact Nodu if Nodu has not contacted you. When Nodu resolves the error, the transfer moves to undeliverable, returned or refunded: see Failed payouts and refunds.
Also contact Nodu in these cases:
- The customer paid an amount that differs from the amount of the transfer.
- The customer paid, and the transfer stays
awaiting_funds.
Keep the id of the transfer and the evidence of the payment.
A create request that timed out
Recover the result with the same Idempotency-Key and exact request body. See Idempotency.
Reconcile with the list
Do not depend on webhooks alone. Periodically compare your records with the results of List all transfers.
- The list returns the most recent transfers first. It is paginated: see Pagination.
- Filter with
customerId, withclientReferenceId, or with one or morestates[]values. - Send your own identifier as
clientReferenceIdwhen you create a transfer. You can then find the transfer by that identifier.
Record a transfer as complete in your system when its outcome is confirmed, not when you create it.
Next steps
- Handle the
info_requiredstate: what you do when a transfer is waiting for the customer. - Errors and rule codes: the errors that a request can return.
- Simulate funding in the sandbox: move a test transfer through its states.