Go live
You build and test your whole integration in the sandbox, Nodu's test environment, before you use production. Nodu gives you access to production after you have onboarded a customer and made at least one transfer in the sandbox with the integration flow agreed with Nodu.
Build the agreed integration flow in the sandbox
First, agree with Nodu on the final functionality that your integration will use:
- Onboarding. The onboarding model. With API onboarding, also the exact list of the fields and documents that an application needs.
- Currencies and rails. The currencies and the payment rails on each side of a transfer: see Payment channels.
- Other features. For example, Nodu wallets and relays.
Build the agreed integration flow in the sandbox. Before requesting production access, complete this checklist:
- Onboard individual and business customers, as your integration flow includes them. See Test onboarding in the sandbox.
- Make transfers from and to every rail and currency of your integration flow, from the quote to the result. See Simulate funding in the sandbox.
- Test proof of ownership for crypto wallets when it applies to your transfers. See Simulate crypto wallet verification.
Use the sandbox to find and resolve problems before real customers and funds are involved.
Build the handling of failed transfers, and of the customer statuses suspended and blocked, from their descriptions: see Track and cancel a transfer and Suspended and blocked customers.
Recommended practices
Make requests safe to repeat
- Idempotency keys. Send an
Idempotency-Keyheader with everyPOSTrequest that creates an object or moves money. Store the key and the exact body before you send the request: see Idempotency. - Client reference ids. Send your own identifier as
clientReferenceIdwhen you create a customer, an external account, a counterparty, a relay or a wallet. It helps you match API objects to your records and complements idempotency handling: see Idempotency. - Timeouts. Repeat a request that timed out with the same key and the same body. A new key can create a second object.
- Errors. Handle errors by
status,codeandrule. Do not compare the text oftitleordetail. Handle arulethat you do not know: see Errors and rule codes.
Handle webhooks
Receive and verify webhooks explains each of these items.
- Signatures. Verify the signature of every webhook before you act on it.
- Duplicates and order. Record the
idof each event. Skip an event that you have already processed. Events can arrive more than once. They can also arrive out of order. - Unknown types. Return
2xxfor an event type that you do not handle. - Reconciliation. Do not depend on webhooks alone. Compare your records with the API from time to time: see Reconcile with the list.
Handle every status and state
- Customers. Offer transfers only when the customer has
status=active. Handle a request for more information, a final rejection, and the statusessuspendedandblocked: see How onboarding works, and customer statuses and Resubmission and rejection. - Payment channels. Handle
inactive,pendingandsuspended: see Payment channels. - Transfers. Handle every
state, includinginfo_required,undeliverable,returned,refunded,canceledanderror: see Track and cancel a transfer and Handle theinfo_requiredstate. - External accounts. Handle
update_requiredandarchived: see External accounts and counterparties.
Request access to production
When your integration works in the sandbox:
- Ask Nodu for a production API key. Store it in a secret manager, and call the API from your backend only: see Environments and API keys and Authentication.
- Give Nodu the URL of your production webhook endpoint, and the list of event types that you act on. Nodu registers the endpoint. You receive its signing secret separately. Store the secret as carefully as an API key.
Production starts empty: none of your sandbox customers, external accounts, transfers or other objects exist there. You can keep using the sandbox for later tests and development.
A suggestion for production: start with one customer and one transfer of a small amount. Follow the transfer to its outcome before you offer this transfer flow to all your customers.
Next steps
- Environments and API keys: the production base URL, and what to know about keys.
- Track and cancel a transfer: what you do in each transfer state.
- Test onboarding in the sandbox: produce each verification outcome before you go live.