Zoorya Pay Developers

Create one-time link

POSThttps://sandbox.eclipse.et/eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/payments

Recent Requests

TimeStatusUser agent

Make a request to see history.

Step 2 of a checkout. Creates a link for one order. Send completionUrl from the response to the payer — they open it and pay with any method. See Payment links.

  1. 1

    Log in first

    Call Log in with your API key: copy it in the merchant portal (Developer → API keys) and paste it. Keep headerValue and tenantId from the response.

  2. 2

    Then call this endpoint with the token

    Copy headerValue from the Log in response and paste it as the Authorization header of this call — it already starts with Bearer . Put tenantId in the URL, with your organisationId and destinationWalletId from the merchant portal.

Note:

The token works for about 15 minutes (expires in the login response). Reuse it for every payment until then; after that this call returns 401 — log in again.

In Try it: first run Log in with your API key. The token and tenantId are then filled in here for you. Fill in your other IDs, then open completionUrl from the response and pay it with a phone or account you control — the prompt or SMS is real.

Headers#

Authorizationstringrequired
Set in Credentials →

Paste headerValue from Log in — the whole value, including Bearer .

Path#

tenantIdintegerrequired

Your tenant ID — returned as tenantId by Log in.

organisationIdintegerrequired

Your organisation ID — merchant portal → Profile → Company.

Body#

New externalUniqueId
…

Paste it into externalUniqueId in Try it. Click New ID before every new payment.

amountnumberrequiredDefaults to 150

Amount in ETB, at most 2 decimals.

currencystringrequiredDefaults to ETB

Always ETB.

typestringrequiredDefaults to GLOBAL_PAYMENT_LINK

Must be GLOBAL_PAYMENT_LINK for Create one-time link.

externalUniqueIdstringrequired

Your own unique ID for this payment. Use a new one every time — letters and digits only, at least 6 characters. Get one from the New ID box above.

destinationWalletIdintegerrequired

The wallet that receives the money — merchant portal → avatar menu → Profile → Company → Wallet ID.

landingUrlstringDefaults to https://your-domain.et/payment-done

Where the payer's browser goes after paying.

additionalFieldsobject[]required

The link's HMACKey and callback URL. Each item is { "id": "…", "value": "…" }.

Response#

paymentIdinteger

Use it with Get a payment.

statusstring

PENDING until the customer pays the link.

completionUrlstring

The link to send to the payer — by SMS, Telegram, email or as a button. They open it and pay with any method.

paymentTypestring

Always LINK for a payment link.

walletIdinteger

The wallet that receives the money — the destinationWalletId you sent.

additionalFieldsobject[]

Echoes back your HMACKey and callbackUrl.

The response contains your HMACKey. Keep the response on your server — send only completionUrl to the payer, never the whole response.

Then wait for your callback and confirm with Get a payment. Deliver only when status is SUCCESSFUL.

Create an HMACKey#

Every link needs an HMACKey in additionalFields. Click New key to make one, then Copy it — or Use it to put it straight into Try it. Store it on your server with your API key, and reuse it for your links.

New HMACKey
…

A random 256-bit key, base64 — the same kind the merchant portal makes. Made in your browser, never sent anywhere. Paste it as the HMACKey value in additionalFields, and keep it secret like your API key.