# Documentation

## NodeJS SDK for Chapa

URL: /docs

Accept payments in Ethiopia with the official Chapa Node.js SDK — initialize transactions, verify payments, split revenue, and manage subaccounts.

NodeJS SDK for Chapa

chapa-nodejs is a fully-typed Node.js SDK for the Chapa payment gateway. It gives you a clean, promise-based interface for initializing transactions, verifying payments, managing subaccounts, and splitting revenue — all with first-class TypeScript support so your editor catches mistakes before your users do.

The core primitive is a Chapa instance. You create one with your secret key and then call methods on it — initialize, verify, getBanks, createSubaccount, and generateTransactionReference. Every method returns a typed response, so you always know the shape of what you're working with.

If you're new, jump to Installation to add the package to your project, then follow the Quickstart to run your first transaction. The Guides cover split payments, subaccount management, and common troubleshooting steps.

---

## Guides

URL: /docs/guides

Practical runbooks for initializing payments, splitting revenue, and managing subaccounts with chapa-nodejs.

Guides

These guides cover the practical workflows you'll reach for after the initial setup. Each one focuses on a single task and gives you copy-pasteable code you can drop straight into your project.

- Split Payments — collect a transaction and automatically distribute a share to one or more subaccounts at settlement time.
- Subaccounts — register a merchant bank account with Chapa so it can receive split revenue.
- Troubleshooting — recover from the most common errors around credentials, validation, and API responses.

If you haven't set up the SDK yet, start with Installation. Once you're configured, the Quickstart shows the end-to-end payment flow before you add splits or subaccounts.

---

## Installation

URL: /docs/installation

Install and configure the Chapa Node.js SDK in your project.

Installation

This page walks you through adding chapa-nodejs to your project and creating a configured Chapa instance ready to make API calls.

Prerequisites

You need Node.js installed and a Chapa account with a secret key. You can get your secret key from the Chapa dashboard.

Install the package

Install with npm:

Or with Yarn:

Create a Chapa instance

Import Chapa from the package and instantiate it with your secret key. Every SDK method is called on this instance.

Note: Keep your secret key out of version control. Store it in an environment variable or a secrets manager and pass it in at runtime.

Verify the setup

Call getBanks() — it requires no arguments and returns immediately if your key is valid. It's the lightest possible check.

If you see a populated array, your credentials are working and you're ready to initialize transactions. Head to Quickstart for the full first-payment workflow.

---

## Quickstart

URL: /docs/quickstart

Initialize and verify your first Chapa payment in minutes.

Quickstart

This guide takes you from a fresh install to a completed payment flow — generating a transaction reference, initializing a charge, and verifying the result. You'll need a configured Chapa instance; see Installation if you haven't done that yet.

Step 1 — Generate a transaction reference

Every Chapa transaction requires a unique tx_ref. Use the built-in utility so you never have to think about uniqueness yourself.

You can customize the prefix and length if your system needs a specific format:

Step 2 — Initialize a transaction

Pass the reference along with the customer and payment details to initialize. On success, Chapa returns a checkout_url you redirect the customer to.

Step 3 — Verify the payment

After the customer completes payment and returns to your callbackurl, verify the transaction using the same txref.

The verify response includes the full transaction record — amount, currency, method, customer details, and timestamps — so you have everything you need to fulfill the order.

Next steps

For revenue sharing across multiple parties, see Guides to learn how to use split payments and subaccounts. If something isn't working, the Troubleshooting page covers the most common issues.

---