Skip to main content

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 the transfer as it was at that moment. See Receive and verify webhooks.
  • The current state. Retrieve a transfer returns the state, the sourceDepositInstructions, the receipt and any requirements.

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:

  1. awaiting_funds
  2. in_review
  3. funds_received
  4. payment_submitted
  5. payment_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 canceled and refunded are sure to be final. A transfer in payment_processed can still move to returned, if the payout comes back later.
  • Nodu can fill some receipt fields after the event v1.transfer.payment_processed. Use sourceTxHash to reconcile incoming crypto and destinationTxHash to 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.

stateMeaningWhat to show the customerWhat you do
awaiting_fundsNodu 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_reviewThe 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_requiredThe customer must complete an action before Nodu continues.The action, and where the customer completes it.See Handle the info_required state.
funds_receivedThe review is complete. Nodu is preparing the payout.The transfer is in progress.Nothing.
payment_submittedNodu has sent the payout. Its arrival is not confirmed yet.The payout is on its way.Nothing.
payment_processedThe payout has arrived at the destination.The result and the details of the receipt.Record the outcome.
undeliverableNodu 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.
returnedThe 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.
refundedThe 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.
canceledThe transfer was canceled before it was funded.The transfer is canceled. The customer must not pay.Record the outcome.
errorProcessing 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 has rule=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 refunded confirms 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, with clientReferenceId, or with one or more states[] values.
  • Send your own identifier as clientReferenceId when 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​