Test in sandbox

Create a payment link, pay it with each method, and test the error cases.

This page walks you through a full sandbox test: log in, create a payment link, pay it with every payment method, confirm it, and try the error cases. The Postman collection has every request below, in the same order.

You need a sandbox API key, your organisationId and Wallet ID (merchant portal → avatar menu → Profile → Company) and an HMACKey — create one here.

Prefer clicking to typing? Every endpoint in the API reference has a Try it button. Run Log in first with your API key — every other page then fills in the token and tenantId for you.

Sandbox moves test money only. Use a phone number or bank account you control — prompts and SMS codes are sent to it.

1. Log in#

bash

BASE="https://sandbox.eclipse.et/eclipse-conductor/rest/v1"
ZOORYA_API_KEY="zp-checkout-12345678:your-secret"
curl -X POST "$BASE/authentication/login" \
  -H "Content-Type: application/json" \
  -d "{\"identity\": \"${ZOORYA_API_KEY%%:*}\", \"password\": \"${ZOORYA_API_KEY#*:}\"}"

Keep headerValue and tenantId. The token works for about 15 minutes; log in again when calls return 401.

2. Create a payment link#

Every call with a new externalUniqueId creates a new one-time link for one order.

bash

curl -X POST "$BASE/tenants/TENANT_ID/organisations/ORGANISATION_ID/payments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "currency": "ETB",
    "type": "GLOBAL_PAYMENT_LINK",
    "externalUniqueId": "sandboxtest001",
    "destinationWalletId": WALLET_ID,
    "landingUrl": "https://example.com/done",
    "additionalFields": [
      { "id": "HMACKey", "value": "YOUR_HMAC_KEY" },
      { "id": "callbackUrl", "value": "https://YOUR-NGROK-URL/webhook" }
    ]
  }'

Open completionUrl from the response.

No code yet? You can also make a one-time link in the sandbox portal under Payment links → One-time link and open it. Portal links send a webhook only if you set a callback URL on the link.

3. Pay with each method#

On the payment page, pick a method and follow the steps. Create a new link (a new externalUniqueId) for each method you test.

Method	On the payment page	On your phone
telebirr — prompt	Choose telebirr, enter your number	Enter your telebirr PIN
telebirr — QR	Choose telebirr → QR code	Scan it with the telebirr app and approve
M-Pesa	Choose M-Pesa, enter your number	Enter your M-Pesa PIN
Nib Bank	Choose Nib Bank, enter your phone number	Approve the prompt
Dashen Bank	Choose Dashen Bank, enter your phone number	Approve the prompt
Zemen Bank	Choose Zemen Bank, enter your account number, then the SMS code	Read the SMS code
EthSwitch	Choose EthSwitch	Scan the QR code with your bank app

When the payment is done, the browser goes to your landingUrl.

Test the unhappy paths too#

Try this	Expected result
Ignore the prompt	`TIMEOUT`
Cancel the prompt on your phone	`CANCELLED` or `ERROR_PERM`, with the reason in `errorDescription`

4. Check the webhook#

If you set callbackUrl, your endpoint receives the payment when it finishes. The main fields:

json

{
  "paymentId": 4581646,
  "externalUniqueId": "sandboxtest001",
  "status": "SUCCESSFUL",
  "errorDescription": "",
  "amount": 10,
  "currency": "ETB",
  "gatewayTransactionId": "DJL0ABC123"
}

externalUniqueId is the ID you sent. See Webhook shape for every field.

To receive it on your laptop, run ngrok http 3000 and use the https://… address as callbackUrl.

5. Confirm#

bash

curl "$BASE/tenants/TENANT_ID/payments/PAYMENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Look for "status": "SUCCESSFUL" and the right amount. Then find the payment in the sandbox portal under Transactions.

6. Test the API rules#

Test	Send	Expected
Same ID again	An `externalUniqueId` you already used	`400` — use a new one every time
Expired token	A token older than about 15 minutes	`401` — log in again
Bad key	A wrong API key on Log in	`401`

7. Test C2B Direct and QR payments (optional)#

To pay without the payment page:

Open M-Pesa (or any method). After Log in, the token and tenantId are already filled in. Fill in your organisationId, destinationWalletId and your own phone number, and click Try it.
Approve the prompt on your phone.
Call Get a payment with the paymentId and check "status": "SUCCESSFUL".

For telebirr QR and EthSwitch QR, Try it draws the QR code under the response — scan it with the telebirr app or your bank app.

The same flows are in the Postman folders 3. C2B Direct and 4. QR payments. Details for every method: Payment methods.

Checklist before going live#

Paid at least once with every method your customers will use.
Webhook received and handled once, even when it repeats.
Goods released only when Get a payment says SUCCESSFUL and the amount matches.
Timeout and cancel handled in your app.

Then follow Go live.