Skip to main content

Handle a transfer that needs action

A transfer in info_required is waiting for an action from the customer. Read its current requirements rather than assuming which action is needed. For proof of crypto wallet control, Self-custody wallets explains when proof is required and which methods the customer can use.

Handle the info_required state​

When Nodu requires an action, the transfer moves from in_review to info_required. Nodu holds the funds and does not send the payout until the required action is complete. You read the requirement from the transfer and show it to the customer.

How you learn of it​

  • The event. Nodu sends v1.transfer.info_required when the transfer enters the state. The transfer object of the event contains the requirements list.
  • The state. Retrieve a transfer returns state=info_required and the current requirements. To find every waiting transfer, call List all transfers with states[]=info_required.

The event shows the transfer at the moment of the change. Retrieve the transfer for the current list.

The requirements list​

A transfer has the requirements field only while an action is pending. For example, a transfer that waits for proof of ownership of the sending crypto wallet contains:

{
"state": "info_required",
"requirements": [
{
"id": "019657d0-d1a2-7b3c-8e4f-5a6b7c8d9e0f",
"action": "verify_wallet_ownership",
"side": "source",
"url": "https://customer.nodu.fi/wallet-verification/019657d0-c6c4-7947-94ec-42c4164cd51e"
}
]
}

Each item of the list is one action:

FieldMeaning
actionThe kind of action: verify_wallet_ownership, the proof of ownership of a crypto wallet.
sideThe crypto wallet that needs proof. source is the crypto wallet that sent the crypto to fund the transfer. destination is the crypto wallet that receives the payout.
urlThe address of the page where the customer gives the proof.
idThe identifier of the requirement.

Nodu can add other values of action. Handle unknown action values without causing your application to fail.

What you do​

  1. Retrieve the transfer. Read every item of requirements.
  2. Tell the customer that the transfer is waiting for them. Use side to say which crypto wallet needs proof.
  3. Send the customer to the url. On that page, the customer gives the proof with one of the two proof methods.
  4. Wait for the next event. Also retrieve the transfer when the customer returns to your interface.

Two details matter for your interface:

  • Read the url from the transfer each time you show the requirement. The page at the url works only while the requirement is pending.
  • If an attempt fails, the customer can try again at the same url.

How the transfer resumes​

When Nodu accepts the proof and no other requirement is pending, the transfer returns to in_review. Nodu sends the event v1.transfer.in_review. The transfer then continues without an API call from you. The requirements field is no longer present.

A transfer can need proof for both crypto wallets, one for source and one for destination. The list then has two items. The second item can appear while the transfer is already info_required. In that case the state does not change, so Nodu sends no new event. For this reason, retrieve the transfer after each event, and each time the customer returns. Show every item that the list contains.

When Nodu refuses the verification​

If Nodu's final decision is a refusal, the transfer moves to error. Nodu sends the event v1.transfer.error. See Track and cancel a transfer for your next action.

While the transfer waits​

  • Cancel a transfer works only in the state awaiting_funds, before the funds arrive.
  • If the customer cannot give the proof, contact Nodu. For example, the crypto came from a crypto wallet that the customer does not control.

Next steps​