Introduction

Base URL

Every request in this reference is made against:

https://api.merebpay.com

Hosted checkout pages and payment links (the paymentUrl / generatedUrl your customers land on) are served from https://checkout.merebpay.com.

Creating an API key

Keys are created from the dashboard, not via a bootstrap API call — this endpoint requires a logged-in session that holds the PER_ADD_API_KEY permission.

curl -X POST https://api.merebpay.com/api/v1/apiKey \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "apiName": "Production Backend",
    "testApi": false,
    "apiKeyType": "PAYMENT"
  }'

Response

{
  "status": 200,
  "message": "Saved api key",
  "content": {
    "apiKeyId": 42,
    "apiKey": "K1lz...redacted-88-char-base64...==",
    "enabled": true,
    "adminEnabled": true,
    "apiName": "Production Backend",
    "apiKeyType": "PAYMENT",
    "testApi": false,
    "companyId": 21,
    "creationDate": "2026-08-20T09:00:00Z"
  }
}

Keys are a 64-byte random value, standard Base64-encoded (~88 characters). There is no sk_live_ / sk_test_ style prefix — whether a key is test or live is tracked only by the testApi flag on the server side, not by anything visible in the key string itself. Treat every key as sensitive regardless of its testApi value.

Using your API key

Pass it on every request as a header — not as a bearer token, not as a query param:

apiKey: YOUR_API_KEY

curl -X POST https://api.merebpay.com/api/v1/payment/request/api \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

IP whitelisting

Requests can additionally be restricted to specific source IPs. If you never add any whitelist entries, requests are not IP-restricted.

Sandbox vs. live mode

Every request that creates money movement — a payment request, a withdrawal, a payment link — accepts an isTest (or test) boolean. When true:

• No real money moves. PSP calls are simulated.
• Transactions are tagged test: true and excluded from your live analytics/reporting totals.
• You can force a specific outcome using the sandbox checkout-completion endpoint, rather than waiting on a real payment method.

There is no separate sandbox subdomain or sandbox-only API key — the same credentials and the same base URL are used for both; the isTest flag on each request is what routes it.

Create a payment request

Creates a hosted checkout session and returns a payment URL to redirect your customer to.

Example request

curl -X POST https://api.merebpay.com/api/v1/payment/request/api \
  -H "Content-Type: application/json" \
  -H "apiKey: YOUR_API_KEY" \
  -d '{
    "method": "LINK",
    "paymentMethodCode": "TELE_BIRR",
    "currency": "ETB",
    "customerName": "Abebe Kebede",
    "customerPhone": "251985968554",
    "amount": 500.00,
    "orderId": "order-10293",
    "description": "Order #10293",
    "isTest": true
  }'

Example response

{
  "status": 200,
  "message": "Payment request generated successfully",
  "content": {
    "paymentRequestId": 133,
    "systemReference": "e9ad7c34ddfa4f12b437ee33f1e67acc",
    "externalReference": null,
    "method": "LINK",
    "status": "PENDING",
    "customerName": "Abebe Kebede",
    "customerPhone": "251985968554",
    "amount": 500.00,
    "currency": "ETB",
    "orderId": "order-10293",
    "description": "Order #10293",
    "paymentUrl": "https://checkout.merebpay.com/payment/checkout/e9ad7c34...",
    "requestDate": "2026-08-20T09:00:00Z",
    "expiryDate": "2026-08-21T09:00:00Z",
    "completionDate": null,
    "isTest": true
  }
}

Redirect your customer to paymentUrl to complete payment on the hosted checkout page. systemReference is how you'll look this transaction up afterward, and is also the ID used in webhook events for this transaction.

Checking status

This is what powers the printable receipt page and is safe to link customers to directly.

// GET /api/v1/transaction/receipt/{referenceId} — public, no auth required
{
  "status": 200,
  "message": "Transaction detail",
  "content": {
    "referenceId": "e9ad7c34ddfa4f12b437ee33f1e67acc",
    "status": "SUCCESS",
    "baseAmount": 500.00,
    "totalAmount": 500.00,
    "commissionAmount": 12.50,
    "vatAmount": 1.88,
    "customerName": "Abebe Kebede",
    "customerPhone": "251985968554",
    "paymentType": "TELE_BIRR",
    "paymentChannel": "PaymentLink",
    "paymentDate": "2026-08-20T09:05:22Z",
    "amountInWords": "five hundred 00/100 birr and zero 00/100 cents"
  }
}

status is one of PENDING, PROCESSING, SUCCESS, FAILED, EXPIRED.

Completing a sandbox payment

In test mode, there's no real Telebirr/CBE/etc. to complete the payment through. Instead:

curl -X POST https://api.merebpay.com/api/v1/payment/sandbox/checkout/pay \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": 1,
    "paymentIntentUniqueId": "e9ad7c34ddfa4f12b437ee33f1e67acc",
    "phone": "251985968554",
    "testMode": { "testModeType": "SIMULATED_TEST", "simulationStatus": "SUCCESS" }
  }'

Use simulationStatus: FAILED to test your failure-handling path without needing a real declined payment.

Payment links

A payment link is a reusable checkout URL you can share (QR code, invoice, social post) instead of generating a new payment request per order.

Response

{
  "status": 200,
  "message": "Created payment link",
  "content": {
    "paymentLinkId": 88,
    "title": "Support Our Cause",
    "price": null,
    "commissionPaidByCustomer": false,
    "description": "One-time or recurring donation",
    "linkType": "FREE_FORM",
    "image": null,
    "category": "CUSTOM",
    "generatedUrl": "https://checkout.merebpay.com/payment-link/a1b2c3d4"
  }
}

Managing payment links

Split Payments

Route a percentage or fixed amount of a payment to another party automatically — a vendor, a partner, a payee you don't want to pay out manually every time. Register the recipient once as a subaccount, then reference it on any future payment. The recipient is paid out on your own normal settlement cycle, alongside your own funds — not instantly.

Creating a subaccount

curl -X POST https://api.merebpay.com/api/v1/subaccount \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme Vendor",
    "accountNumber": "1000987654",
    "accountHolder": "Acme Vendor PLC",
    "bankId": 1,
    "paymentMethodCode": "CBE"
  }'

Response

{
  "status": 200,
  "message": "Split recipient created",
  "content": {
    "splitRecipientId": 42,
    "label": "Acme Vendor",
    "maskedAccountNumber": "****7654",
    "accountHolder": "Acme Vendor PLC",
    "bankName": "Commercial Bank of Ethiopia",
    "paymentMethodCode": "CBE",
    "status": "ACTIVE"
  }
}

Attaching a split to a payment

Add a splitPayment block to any payment request you already create (see Create a payment request) — everything else about that call stays the same.

curl -X POST https://api.merebpay.com/api/v1/payment/intent \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000.00,
    "currency": "ETB",
    "allowedMethods": ["CBE"],
    "splitPayment": {
      "splitRecipientId": 42,
      "splitType": "PERCENTAGE",
      "value": 10
    },
    "returnUrl": "https://example.com/return",
    "expireIn": 600,
    "commissionPaidByCustomer": false
  }'

Managing subaccounts

Disabling is a soft delete — a disabled recipient can no longer be used on a new payment, but stays attached to its historical transactions and payouts.

Settlement & refunds

Every accrued split for a recipient is summed and paid into their account as part of your own next settlement run — no separate payout call needed. Refund behavior depends on whether the split was already paid out:

• Refund a payment whose split hasn't been paid out yet → the split is simply excluded. Nothing to claw back.
• Refund a payment whose split has already been paid out → it's debited from that recipient's next payout instead. The original payout itself is never reversed.

Webhooks

Webhooks let you receive real-time notifications instead of polling the receipt endpoint.

Registering your webhook

Regenerating your keys

Generates a brand-new key pair server-side. Returns only a success message — the new keys are not included in the response, so retrieve them immediately after via the endpoint below.

Retrieving your current public key

// GET /api/v1/webhook/search?test={true|false}
{
  "status": 200,
  "message": "...",
  "content": {
    "webHookUrl": "https://yourapp.com/webhooks/merebpay",
    "webHookPubk": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."
  }
}

Your private key is never returned by any API call after the moment you upload it — keep your own copy.

Receiving an event

We send a POST to your registered URL with this envelope:

{
  "webHookEvent": "PAYMENT_SUCCESS",
  "signature": "base64-rsa-signature-of-the-body-field",
  "body": "{\"paymentIntentId\":123,\"uuid\":\"...\",\"transaction\":{...},\"totalAmount\":500.00,\"currency\":\"ETB\", ...}"
}

The parsed body contains (among other fields): paymentIntentId, uuid, totalAmount, currency, test, transaction (with referenceId, transactionStatus, merchantNet, adminNet, paymentType), and merchantCustomer (name, email, phone).

Verifying the signature

Algorithm: SHA256withRSA. The signature is computed over the raw body string (before you parse it) and Base64-encoded.

const crypto = require('crypto');

function verifyWebhook(envelope, yourStoredPublicKeyPem) {
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(envelope.body, 'utf8');
  verifier.end();
  return verifier.verify(yourStoredPublicKeyPem, envelope.signature, 'base64');
}

app.post('/webhooks/merebpay', (req, res) => {
  if (!verifyWebhook(req.body, MY_MEREB_PUBLIC_KEY)) {
    return res.status(400).send('invalid signature');
  }

  const data = JSON.parse(req.body.body); // body is a JSON string — parse twice
  // handle data.transaction.transactionStatus, etc.

  res.status(200).send('ACK'); // must be 2xx AND contain ACK / SUCCESS / OK
});

Acknowledging delivery

Retry behavior

If delivery isn't acknowledged, we retry automatically: up to 3 attempts with a 5-second backoff between attempts. If all attempts are exhausted, the event is marked failed on our side — implement idempotent handling on your end in case of any edge-case duplicate delivery, and reach out to support if you notice a webhook you never received.

Refunds

Refunds go through a request → admin-approval flow; they are not instant.

curl -X POST https://api.merebpay.com/api/v1/merchant/refund \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionReferenceId": "e9ad7c34ddfa4f12b437ee33f1e67acc",
    "amount": 200.00,
    "reason": "Customer requested partial refund"
  }'

Response (201 Created)

// 201 Created
{
  "status": 201,
  "message": "Refund request submitted",
  "content": {
    "referenceId": "REF-a1b2c3d4",
    "status": "PENDING_APPROVAL"
  }
}

Refund status progresses through: PENDING_APPROVAL → APPROVED → PROCESSING → REFUNDED (or REJECTED/FAILED).

Checking refund status

Withdrawals

Transfers (ad-hoc payouts)

Unlike Withdrawals above, which pays out to a bank account you've already registered on your dashboard, a Transfer sends money directly to any bank account or mobile wallet you specify in the request — no prior registration needed. Requires a separate WITHDRAWAL-type API key (same key family as your PAYMENT key, different type) and withdrawal_enabled on your account.

Check your balance first

curl https://api.merebpay.com/api/v1/balance \
  -H "apiKey: YOUR_API_KEY"

Look up a bank code

curl https://api.merebpay.com/api/v1/bank \
  -H "apiKey: YOUR_API_KEY"

Send the Transfer

curl -X POST https://api.merebpay.com/api/v1/payment/express/withdraw \
  -H "apiKey: YOUR_WITHDRAWAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "currency": "ETB",
    "withdrawalIntentUniqueId": "payout-2026-10-08-001",
    "creditAccount": "0911223344",
    "phoneNumber": "0911223344",
    "method": "TELE_BIRR",
    "expireIn": 600,
    "commissionPaidByCustomer": false,
    "customerInfo": { "phone": "0911223344", "name": "Recipient Name" }
  }'

Check a Transfer's status

curl -X POST https://api.merebpay.com/api/v1/payment/express/withdraw/status \
  -H "apiKey: YOUR_WITHDRAWAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "withdrawalIntentUniqueId": "payout-2026-10-08-001" }'

{
  "status": 200,
  "message": "Fetched transfer status",
  "content": {
    "uniqueId": "payout-2026-10-08-001",
    "status": "SUCCESS",
    "totalAmount": 500.00,
    "merchantNet": 500.00,
    "creditAccount": "0911223344",
    "currency": "ETB"
  }
}

List your Transfer history

curl "https://api.merebpay.com/api/v1/payment/express/withdraw?fromDate=2026-10-01T00:00:00&toDate=2026-10-08T23:59:59&status=SUCCESS" \
  -H "apiKey: YOUR_WITHDRAWAL_API_KEY"

Optional query params: fromDate, toDate, currency, status.

Bulk payouts

For paying out many recipients (e.g. payroll, disbursements) in one batch via a CSV/Excel upload.

File format

3 columns, no fixed header requirement — a header row is auto-detected and skipped if present.

Each row is independently verified against the destination account before the batch can proceed:

• All rows valid → batch status PENDING, awaiting admin approval.
• Some rows valid, some invalid → batch status AWAITING_CONFIRMATION — you choose whether to proceed with just the valid rows or discard the batch.
• No rows valid → the batch is rejected outright with “No rows passed account verification.”

A row can fail verification for: the account not existing, the declared name not matching the account holder on file, or the account existing but not in an active state (dormant/closed/blocked).

Customers

MerbPay automatically records a customer profile the first time someone pays through your checkout, matched by email, then phone, then name (in that priority order) — you don't need to create customers explicitly.

Search parameters (GET /api/v1/merchant/customer)

Error handling

Most common shape

{ "status": 400, "message": "A specific description of what went wrong." }

Validation errors additionally include a field-level breakdown

{
  "status": 400,
  "message": "Validation error occurred while processing request object.",
  "validationErrors": { "amount": "must not be null" }
}

Common error scenarios you'll encounter

Always build your integration to read message for the human-readable reason rather than branching only on HTTP status — several different failure conditions can share the same status code.