Skip to main content

How onboarding works, and customer statuses

A customer is the person or business that you onboard and move money for. Create the customer, obtain terms acceptance and complete verification using your onboarding model. Use the status tables below to follow progress and decide when the customer can transact.

Customers​

You create a customer with Create a customer. Nodu returns the customer's id. Every later call for that customer uses this id: the terms, verification, payment channels, external accounts and transfers. Store the id with your own record of the customer.

A customer has one of two types:

  • individual: a person.
  • business: a company. You send the company name, and the name and email of the person who represents the company.

Create one customer for each person or company. A customer who returns to your platform continues with the same id.

The two steps of onboarding​

Onboarding starts when you create the customer. The new customer has status=pending. Then come two steps:

  1. Accept the Terms of Service. The customer accepts Nodu's Terms of Service.
  2. Complete customer verification. With hosted onboarding, the customer provides their information and documents on Nodu's verification page. With API onboarding, you provide all the required information and documents in an application, and submit it for verification. Nodu reviews them and decides.

If some information or documents need to be submitted again, Nodu can ask for them. The customer, or you with API onboarding, then corrects them and submits again: see Resubmission and rejection. After Nodu's final decision, verification is approved and the customer becomes active, or verification is permanently_rejected.

Onboarding is complete when the customer has status=active. Nodu sends the v1.customer.activated event when the customer's status becomes active. Check the customer's status before you offer transfers. Only an active customer can transact. For a customer with another status, Nodu refuses new quotes, transfers and external accounts with rule=customer_not_active.

Onboarding models compares the ways in which Nodu receives the customer's information.

Statuses​

Retrieve a customer returns three status fields. An application has a status of its own.

Customer status​

The status field says whether the customer can transact.

statusMeaningWhat you do
pendingOnboarding is not complete.Read tosAcceptanceStatus and verificationStatus to see which part is not complete. Do not offer transfers.
activeThe customer can transact.Offer transfers. First check the customer's payment channels.
suspendedNodu has suspended the customer. The customer cannot transact.Stop offering new transfers. See Suspended and blocked customers.
blockedNodu has blocked the customer. The customer cannot transact.Stop offering new transfers. See Suspended and blocked customers.

Terms acceptance status​

tosAcceptanceStatusMeaningWhat you do
pendingThe customer has not accepted Nodu's Terms of Service.Obtain the acceptance in the way your onboarding model describes.
acceptedThe customer has accepted the terms.Nothing.

Verification status​

verificationStatusMeaningWhat you do
pending_inputNodu is waiting for the customer's information and documents.With hosted onboarding, redirect the customer to Nodu's verification page. With API onboarding, complete the application and submit it.
under_reviewThe information is submitted. Nodu is reviewing it.Show the customer that the review is pending. Wait for the outcome.
awaiting_associatesThe business has submitted its application. Nodu reviews it once its associates have completed their verification.With hosted onboarding, redirect the customer to Nodu's verification page: it lists the associates who still have to verify and lets the customer send them their links. With API onboarding, follow Associates of a business.
resubmission_requiredNodu needs more information or a corrected document.Follow Resubmission and rejection.
permanently_rejectedNodu has rejected the verification. The decision is final.Show the outcome to the customer. Stop onboarding this customer.
approvedNodu has approved the verification.Nothing for verification. Check that status=active before you offer transfers.

A business can move from under_review to awaiting_associates a few seconds after it submits, and back to under_review once its associates have completed their verification.

Application status​

An application is the set of information and documents that Nodu reviews for one customer. The customer object names the current application in activeApplication, with its id and status. Retrieve an application returns the application itself.

statusMeaningWhat you do
draftThe application exists and is not submitted.With API onboarding, complete the application and submit it.
submittedNodu has accepted the application. For a business, the review starts once its associates have completed their verification.Wait for the outcome. You cannot change the application now.
under_reviewNodu is reviewing the application.Wait for the outcome. You cannot change the application now.
approvedThe review passed.Check that the customer has status=active.
rejectedThe review failed. The decision is final.Show the outcome to the customer. You cannot correct this application or submit it again.
resubmission_requiredNodu needs corrections.Read rejection in the application. Then follow Resubmission and rejection.

Not every application passes through every status. The customer has activeApplication=null when no application is in progress, for example after the application is approved or rejected. Store the application id if you want to read the application later.

Follow status changes​

Nodu sends a webhook event when a status changes: v1.customer.tos_accepted, v1.customer.verification_under_review, v1.customer.verification_awaiting_associates, v1.customer.verification_approved, v1.customer.verification_resubmission_required, v1.customer.verification_permanently_rejected, v1.customer.activated, v1.customer.suspended and v1.customer.blocked. Receive and verify webhooks describes each event.

An event is a notification, not the current state. The event contains the customer data from the time of the change. Events can arrive more than once and out of order. When an event conflicts with your stored information or the customer returns to your platform, call Retrieve a customer. Use the statuses in that response.

Submission and approval are separate steps. Submitting an application does not mean Nodu has approved it. After approval, check that the customer has status=active.

Next steps​