Reseller API v1

Payments API

Collect money from your customers: hosted checkout pages and permanent customer account numbers. Everything settles into your PowerWave wallet.

Every code block, endpoint and section has a Copy button.

Before you start

Accept bank-transfer payments from your customers. Money always settles into your PowerWave wallet (withdraw it, spend it, or pay it out). It needs an approved reseller business at Tier 3 with payments switched on. Use your reseller API key (pw_live_…). Your customer can pay by bank transfer, or with their own PowerWave wallet (Pay with PowerWave, no fee).

What you must send about the customer

Call	Name	Email	Phone
`POST /checkout/sessions`	required	required	optional
`POST /customers` (account number)	required	required	required

Paga needs a way to reach the customer to open a checkout or an account number, so a missing or invalid field is refused with 422 validation_error and nothing is created. Phone numbers are Nigerian numbers such as 08031234567.

How a checkout works

Your server calls POST /checkout/sessions with your order reference, the amount and the customer's name and email.
Send the customer to checkout_url (on checkout.powerwave.ng, run by PowerWave). It shows a one-time account number and a countdown; Paga only accepts the exact amount.
When the transfer lands we send the checkout.paid webhook and, if you gave a redirect_url, return the customer to it with ?reference=…&status=paid&signature=… (signature = HMAC-SHA256(your webhook signing secret, reference + "." + status), present once you have a webhook secret).
Before delivering, confirm with the signed webhook or GET /checkout/sessions/{reference}. Treat the redirect as a hint only.

Checkout

POST/v1/checkout/sessions

Open a checkout

Open a hosted checkout for one order. Send your customer to checkout_url; they pay by bank transfer (or with their PowerWave wallet) and the money lands in your wallet.

ParameterDescription

referencerequired

your unique order ID (4-64 characters: letters, numbers, . - _)

amountrequired

order amount in naira, e.g. "45000"

customer_namerequired

the customer's full name (max 150 characters)

customer_emailrequired

the customer's email address

customer_phoneoptional

Nigerian number, e.g. 08031234567

customer_refoptional

your own ID for the customer

descriptionoptional

shown to the customer (max 255 characters)

redirect_urloptional

an https:// URL; we send the customer back to it with ?reference=&status=&signature=

expires_in_minutesoptional

default 30 (5-1440)

fee_beareroptional

'reseller' (fee deducted from what you receive) or 'customer' (fee added to their total); default = your Payments setting

curl -X POST "https://api.powerwave.ng/v1/checkout/sessions" \
  -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"INV-2026-0142","amount":"45000","customer_name":"Adaeze Okafor","customer_email":"adaeze@example.com","description":"First term fees","redirect_url":"https://yourshop.com/paid"}'

$ch = curl_init('https://api.powerwave.ng/v1/checkout/sessions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PW_KEY'), 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'reference' => 'INV-2026-0142',
        'amount' => '45000',
        'customer_name' => 'Adaeze Okafor',
        'customer_email' => 'adaeze@example.com',
        'description' => 'First term fees',
        'redirect_url' => 'https://yourshop.com/paid',
    ]),
]);
$res = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.powerwave.ng/v1/checkout/sessions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PW_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
      "reference": "INV-2026-0142",
      "amount": "45000",
      "customer_name": "Adaeze Okafor",
      "customer_email": "adaeze@example.com",
      "description": "First term fees",
      "redirect_url": "https://yourshop.com/paid"
  }),
});
const json = await res.json();

Response data

{
    "reference": "INV-2026-0142",
    "checkout_reference": "PWCK7Q2M9XKD4RTB8WNA",
    "checkout_url": "https://checkout.powerwave.ng/PWCK7Q2M9XKD4RTB8WNA",
    "business_id": 12,
    "source": "api",
    "status": "pending",
    "paid_with": null,
    "amount": "45000.00",
    "fee": "675.00",
    "fee_bearer": "reseller",
    "customer_pays": "45000.00",
    "you_receive": "44325.00",
    "bank_name": "Paga",
    "account_number": "9946503468",
    "customer": {
        "name": "Adaeze Okafor",
        "email": "adaeze@example.com",
        "phone": null,
        "ref": null
    },
    "amount_paid": null,
    "note": null,
    "expires_at": "2026-10-06T20:01:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-06T19:31:00+01:00"
}

The customer's email is required; the phone number is optional.
Sending the same reference again returns the same checkout (header Idempotent-Replay: true) - a different amount is 409 idempotency_conflict.

GET/v1/checkout/sessions/{reference}

Get a checkout

One checkout by YOUR reference (or our checkout_reference). Use it to confirm payment before you deliver.

curl "https://api.powerwave.ng/v1/checkout/sessions/{reference}" \
  -H "Authorization: Bearer $PW_KEY"

$ch = curl_init('https://api.powerwave.ng/v1/checkout/sessions/{reference}');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PW_KEY'), 'Content-Type: application/json'],
]);
$res = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.powerwave.ng/v1/checkout/sessions/{reference}', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.PW_KEY}`, 'Content-Type': 'application/json' },
});
const json = await res.json();

Response data

{
    "reference": "INV-2026-0142",
    "checkout_reference": "PWCK7Q2M9XKD4RTB8WNA",
    "checkout_url": "https://checkout.powerwave.ng/PWCK7Q2M9XKD4RTB8WNA",
    "business_id": 12,
    "source": "api",
    "status": "pending",
    "paid_with": null,
    "amount": "45000.00",
    "fee": "675.00",
    "fee_bearer": "reseller",
    "customer_pays": "45000.00",
    "you_receive": "44325.00",
    "bank_name": "Paga",
    "account_number": "9946503468",
    "customer": {
        "name": "Adaeze Okafor",
        "email": "adaeze@example.com",
        "phone": null,
        "ref": null
    },
    "amount_paid": null,
    "note": null,
    "expires_at": "2026-10-06T20:01:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-06T19:31:00+01:00"
}

GET/v1/checkout/sessions?status=paid&page=1&per_page=20

List checkouts

Your checkouts, newest first.

ParameterDescription

statusoptional

pending, paid, under_review, expired, cancelled or failed

pageoptional

default 1

per_pageoptional

default 20, max 100

curl "https://api.powerwave.ng/v1/checkout/sessions?status=paid&page=1&per_page=20" \
  -H "Authorization: Bearer $PW_KEY"

$ch = curl_init('https://api.powerwave.ng/v1/checkout/sessions?status=paid&page=1&per_page=20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PW_KEY'), 'Content-Type: application/json'],
]);
$res = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.powerwave.ng/v1/checkout/sessions?status=paid&page=1&per_page=20', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.PW_KEY}`, 'Content-Type': 'application/json' },
});
const json = await res.json();

Response data

{
    "page": 1,
    "per_page": 20,
    "total": 58,
    "sessions": [
        {
            "reference": "INV-2026-0142",
            "checkout_reference": "PWCK7Q2M9XKD4RTB8WNA",
            "checkout_url": "https://checkout.powerwave.ng/PWCK7Q2M9XKD4RTB8WNA",
            "business_id": 12,
            "source": "api",
            "status": "paid",
            "paid_with": "bank_transfer",
            "amount": "45000.00",
            "fee": "675.00",
            "fee_bearer": "reseller",
            "customer_pays": "45000.00",
            "you_receive": "44325.00",
            "bank_name": "Paga",
            "account_number": "9946503468",
            "customer": {
                "name": "Adaeze Okafor",
                "email": "adaeze@example.com",
                "phone": null,
                "ref": null
            },
            "amount_paid": "45000.00",
            "note": null,
            "expires_at": "2026-10-06T20:01:00+01:00",
            "paid_at": "2026-10-06T19:40:12+01:00",
            "created_at": "2026-10-06T19:31:00+01:00"
        }
    ]
}

POST/v1/checkout/sessions/{reference}/cancel

Cancel a checkout

Close an unpaid checkout. (A transfer that still arrives goes to under_review, then is credited to you.)

curl -X POST "https://api.powerwave.ng/v1/checkout/sessions/{reference}/cancel" \
  -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

$ch = curl_init('https://api.powerwave.ng/v1/checkout/sessions/{reference}/cancel');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PW_KEY'), 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);
$res = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.powerwave.ng/v1/checkout/sessions/{reference}/cancel', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PW_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
const json = await res.json();

Response data

{
    "reference": "INV-2026-0142",
    "checkout_reference": "PWCK7Q2M9XKD4RTB8WNA",
    "checkout_url": "https://checkout.powerwave.ng/PWCK7Q2M9XKD4RTB8WNA",
    "business_id": 12,
    "source": "api",
    "status": "cancelled",
    "paid_with": null,
    "amount": "45000.00",
    "fee": "675.00",
    "fee_bearer": "reseller",
    "customer_pays": "45000.00",
    "you_receive": "44325.00",
    "bank_name": "Paga",
    "account_number": "9946503468",
    "customer": {
        "name": "Adaeze Okafor",
        "email": "adaeze@example.com",
        "phone": null,
        "ref": null
    },
    "amount_paid": null,
    "note": null,
    "expires_at": "2026-10-06T20:01:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-06T19:31:00+01:00"
}

Customer account numbers

POST/v1/customers

Create a customer account number

Give one of your customers their own permanent account number. Every transfer into it lands in your wallet (fee deducted). Calling again with the same customer_ref returns the same account.

ParameterDescription

customer_refrequired

your ID for the customer (max 80 characters)

customer_namerequired

the customer's full name

phonerequired

the customer's Nigerian phone number, e.g. 08039998877

emailrequired

the customer's email address

curl -X POST "https://api.powerwave.ng/v1/customers" \
  -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_ref":"STU-0042","customer_name":"Ife Adeyemi","phone":"08039998877","email":"ife@example.com"}'

$ch = curl_init('https://api.powerwave.ng/v1/customers');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PW_KEY'), 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'customer_ref' => 'STU-0042',
        'customer_name' => 'Ife Adeyemi',
        'phone' => '08039998877',
        'email' => 'ife@example.com',
    ]),
]);
$res = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.powerwave.ng/v1/customers', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PW_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
      "customer_ref": "STU-0042",
      "customer_name": "Ife Adeyemi",
      "phone": "08039998877",
      "email": "ife@example.com"
  }),
});
const json = await res.json();

Response data

{
    "customer_ref": "STU-0042",
    "customer_name": "Ife Adeyemi",
    "email": "ife@example.com",
    "phone": "08039998877",
    "bank_name": "Paga",
    "account_number": "9812962181",
    "account_name": "PowerWave - Ife Adeyemi (MyBiz Data)",
    "fee_percent": "1.50"
}

Both the customer's phone number and email are required - Paga needs them to open the account.
The account name your customer sees in their bank app is PowerWave - {customer_name} ({your business name}).

GET/v1/customers/{customer_ref}

Get a customer account

A customer's account number.

curl "https://api.powerwave.ng/v1/customers/{customer_ref}" \
  -H "Authorization: Bearer $PW_KEY"

$ch = curl_init('https://api.powerwave.ng/v1/customers/{customer_ref}');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PW_KEY'), 'Content-Type: application/json'],
]);
$res = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.powerwave.ng/v1/customers/{customer_ref}', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.PW_KEY}`, 'Content-Type': 'application/json' },
});
const json = await res.json();

Response data

{
    "customer_ref": "STU-0042",
    "customer_name": "Ife Adeyemi",
    "email": "ife@example.com",
    "phone": "08039998877",
    "bank_name": "Paga",
    "account_number": "9812962181",
    "account_name": "PowerWave - Ife Adeyemi (MyBiz Data)",
    "fee_percent": "1.50"
}

Fees

1.5% per payment, nothing else. Choose on your Payments page (or per checkout with fee_bearer): deduct it from what you receive, or add it to the customer's total. Payments into customer account numbers (POST /customers) always have the fee deducted, because the customer decides what to send. Pay with PowerWave payments have no fee.

Checkout statuses

status	Meaning
`pending`	Waiting for the transfer.
`paid`	Paid and credited to your wallet. Deliver the order.
`under_review`	A payment arrived but could not be verified automatically yet; our team is confirming it. Don't deliver yet - you get `checkout.paid` or `checkout.failed`.
`expired` / `cancelled`	Closed without payment. A transfer that still arrives is credited to you and the checkout becomes `paid` (with a `note`).
`failed`	Our team rejected a payment under review. Nothing was credited.

Wrong amounts are credited, not held

If the customer pays less, more, or after the link closed, whatever Paga confirms is credited to your wallet straight away. The checkout becomes paid with amount_paid and a note (for example "Underpaid: ₦600.00 received, ₦1,000.00 was due"). Check that amount_paid covers the order before you deliver. A later top-up on the same checkout sends checkout.additional_payment.

Payment webhooks

We send checkout.paid, checkout.expired, checkout.failed, checkout.additional_payment and, for customer account numbers, collection.received. Payloads and signature checking are on the Webhooks page.

Questions? Contact us.