Quick Start Guide

Register your business and create a project

Create your HellOOpass account, then register a project for the app that will use the API. → Business Registration · Project Creation

Complete your business profile

Submit business information and documents for verification. Approval is required before credentials are issued. → Business Profile and Documents

Get your API credentials

Credentials arrive by email after approval and appear in the merchant dashboard. Store the secret key in your backend only.

# .env — backend only, never committed
HELLOOPASS_SECRET_KEY=YOUR_SECRET_API_KEY
HELLOOPASS_BASE_URL=https://sandbox-api.helloopass.example

Configure settlement and webhooks

Register your settlement bank account and a public HTTPS webhook endpoint. → Settlement Account Setup · Webhook Configuration

Initialize your first payment

curl -X POST https://sandbox-api.helloopass.example/v1/payments \
  -H "Authorization: Bearer $HELLOOPASS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "ETB", "reference": "order_1024"}'

Redirect the customer to the returned checkout_url.

Verify the payment

A browser redirect is not proof of payment. Confirm status on your backend, and cross-check signed webhooks.

const res = await fetch(`${process.env.HELLOOPASS_BASE_URL}/v1/payments/${paymentId}`, {
  headers: { Authorization: `Bearer ${process.env.HELLOOPASS_SECRET_KEY}` },
});
const payment = await res.json();
if (payment.status === "succeeded") fulfillOrderOnce(payment.reference);

→ Verify Payment

Go live

Swap in production credentials and webhook URL, enable signature verification, add monitoring, then run one end-to-end production test.