node

Snippe 101 -- Node.js

All examples use native fetch (Node 18+). No external dependencies needed except for the webhook handler which uses Express.

Requirements

• Node.js 18 or later
• For webhook handler: npm install express

How to Run

Every file is standalone. Just run it directly:

node collection/01-mobile-money.js

Replace snp_your_api_key_here with your actual API key before running.

Collection (Accepting Payments)

Follow the files in order for the full payment flow:

File	What You'll Learn
collection/01-mobile-money.js	Create a payment that sends a USSD push to the customer's phone. They confirm on their device, you get paid. Supports Airtel Money, M-Pesa, Mixx by Yas, and Halotel.
collection/02-card-payment.js	Create a payment that returns a payment_url. Redirect your customer there to enter their card details. Requires full billing info (address, city, country). After payment, customer is sent to your redirect_url or cancel_url.
collection/03-dynamic-qr.js	Create a payment that returns a payment_qr_code string. Render it as a QR image in your app. Customer scans it with their mobile money app to pay. Great for in-store or POS.
collection/04-list-payments.js	Fetch all your payments with pagination. Use limit and offset query params to page through results. Returns amount, status, customer info, and settlement details for each payment.
collection/05-get-payment-status.js	Check a single payment by its reference. Use this to verify payment status after a webhook or to poll for completion. Statuses: pending, completed, failed, voided, expired.
collection/06-trigger-push.js	Retry the USSD push for a pending payment. Useful when the customer missed the first push or it timed out. You can also send the push to a different phone number.
collection/07-get-balance.js	Check your Snippe account balance. Shows both total balance and available balance (what you can withdraw or use for payouts).
collection/08-search-payments.js	Search for a specific payment by its reference. Useful when you need to look up a transaction from your order system.
collection/09-webhook-handler.js	Express server that listens for Snippe webhooks. Handles payment.completed, payment.failed, payout.completed, and payout.failed events. Includes HMAC-SHA256 signature verification.
collection/10-error-handling.js	Wraps a payment creation call with proper error handling for every HTTP status code (400, 401, 403, 404, 422, 429, 500, 503).

Disbursement (Sending Money)

File	What You'll Learn
disbursement/01-mobile-money-payout.js	Send money to a mobile money account. Specify amount, recipient phone number, and name. Supports Airtel, Tigo (Mixx by Yas), and HaloPesa. Response shows fees and total deducted.
disbursement/02-bank-transfer-payout.js	Send money to a bank account. Requires bank code (e.g. CRDB, NMB, ABSA), account number, and recipient name. Supports 40+ Tanzanian banks.
disbursement/03-list-payouts.js	Fetch all your payouts with pagination. Same limit/offset pattern as listing payments. Returns recipient info, fees, and status for each payout.
disbursement/04-get-payout-status.js	Check a single payout by its reference. Statuses: pending, completed, failed, reversed.
disbursement/05-calculate-payout-fee.js	Calculate the fee for a payout amount before sending it. Use this to check you have enough balance. Returns amount, fee_amount, and total_amount.
disbursement/06-webhook-handler.js	Same webhook handler as in collection -- handles both payment and payout events with signature verification.
disbursement/07-error-handling.js	Wraps a payout creation call with error handling. Includes the common insufficient balance scenario on 500 errors.