Keep the order unpaid.
Account creation is not payment confirmation. Continue checking unresolved records and route exceptions for review.
ONE COLLECTION FLOW. A PRACTICAL START.
From an NGN request
to a reconciled record.
A focused server-side Node.js sample for temporary accounts, payment status lookup and static-token webhook verification.
v0.1.0 · 8.6 KB · Node.js 24+ · crypto-js 4.2.0 · No signup required
Offline-tested, not live-certified.
Six mock tests validate sample behaviour without calling VelvPay. Test-key accounts are simulated and are not evidence of a bank transfer. Live use requires onboarding, enabled capabilities and an agreed production certification with VelvPay.
A sample you can inspect.
The ZIP includes a full README, a Node.js collection example, its package definition and six offline tests. It is a starting point for a technical evaluation, rather than a complete application or full SDK.
- Create a fixed-amount, temporary NGN account.
- Look up a transaction using its ID or your merchant reference.
- Classify pending, paid and failed results.
- Compare a configured static webhook token in constant time.
The tests cover authentication ciphertext, request URLs and payloads, simulated account state, amount handling and webhook token checks. They do not verify provider connectivity, bank settlement, public endpoint availability or production readiness.
01 / GET STARTED
Run the offline tests.
Use Node.js 24 or later. Download and inspect the ZIP, extract it, then run these commands from the extracted starter directory:
npm install
npm testInstallation retrieves the declared crypto-js dependency. The test suite itself uses mocked network responses and requires no VelvPay credentials. Review the README before adapting the sample for your backend.
File integrity · SHA-256
2ff4f4a461857ddd8491440660664f4a5437714fdf8a8f8d1be7e0551732a6c702 / KEEP THE BUSINESS CONTEXT
Carry one reference through the flow.
- Store your merchant reference first.
Use a stable, unique order or collection reference. Record it in your system before requesting a temporary account.
- Create the account on your server.
The sample sends integer kobo with isNaira set to false. Store the returned transaction ID, reference and expected amount together. Keep the order pending.
- Process the final-state event.
Configure the merchant-global webhook for your backend. Validate its static Bearer token before processing, then match the reference and amount and apply the change idempotently.
- Reconcile anything unresolved.
Look up the stored transaction ID or merchant reference when the outcome is unclear. Use a fresh request reference for lookup authentication. Reconcile before repeating an uncertain create request.
The README explains the v1 authentication scheme, amount conversion, request shapes and account validity rules. Generate authentication on your backend and keep all secret material outside browser code and logs.
03 / DO NOT CONFUSE A REQUEST WITH A PAYMENT
Let the transaction state decide.
Verify, then apply the paid transition.
Match the stored reference, transaction and expected amount. Make the update idempotent so repeated events cannot fulfil an order twice.
Close the attempt without fulfilment.
A failed payment attempt should not release goods or trigger a paid invoice state.
Read the transaction state inside the webhook data. An outer success envelope does not by itself mean the customer’s payment succeeded.
04 / BEFORE A CUSTOMER SEES A LIVE ACCOUNT
Agree the pilot boundaries.
- Complete business onboarding and confirm collection capability and provider availability.
- Use issued test credentials first and label all simulated accounts clearly.
- Configure your HTTPS webhook and keep its token in your secret manager.
- Exercise duplicate events, delayed delivery, amount mismatches, failed payments and uncertain requests.
- Agree production certification, fees, reconciliation responsibilities and rollout checks with VelvPay.
Vendor payouts are a separate asynchronous, provider-gated flow. An accepted payout request is pending, not proof that a vendor has been paid.