C2B Direct

Charge the customer directly — M-Pesa, Dashen, Nib, telebirr, Zemen, EthSwitch — without the payment page.

There are two ways to take a payment with Zoorya Pay:

	Checkout (payment link)	C2B Direct
How it works	You create a one-time link; the customer picks a method on the Zoorya Pay page	Your app asks the customer how they pay, then your server creates the payment directly
Customer leaves your app	Yes	No
Calls	Log in → Create one-time link → Get a payment	Log in → a method, e.g. M-Pesa → Get a payment
Best for	Websites, quick integrations	Mobile apps, POS screens, kiosks — or customers who find the payment page slow

This section is about C2B Direct.

What you need to bring#

Value	What it is	Where to find it
API key	`zp-checkout-…:…`, shown once. Copy it with Copy API key	Merchant portal → Developer → API keys. Lost it? Rotate the key.
tenantId	Your environment's ID	Returned by Log in as `tenantId`
organisationId	Your business's ID	Merchant portal → avatar menu → Profile → Company → Organisation ID
walletId	The wallet that receives the money (`destinationWalletId`)	Merchant portal → avatar menu → Profile → Company → Wallet ID
HMACKey	Key needed only for payment links	Create one, or merchant portal → Payment links → HMACKey (reveal and copy)

The API key, the token and the HMACKey are passwords. Keep them on your server — never in a mobile app, a website or a Git repository.

1
Log in
Send your API key to Log in. You get the token (headerValue) and your tenantId. Send headerValue as the Authorization header of every payment call. The token works for about 15 minutes — reuse it until then, and log in again when it expires.
2
Create the payment
Call the method the customer chose — every method has its own page with Try it. See Payment methods for the list.
3
Get the result
Your callbackUrl receives the payment when it reaches a final status. It is the same object as the create response, with status set to SUCCESSFUL, ERROR_PERM, TIMEOUT or CANCELLED.
4
Confirm before you deliver
Call Get a payment with the paymentId. Deliver only when status is SUCCESSFUL and amount matches your order.

externalUniqueId must be new for every payment — reusing one is rejected. Use letters and digits only. Dashen Bank allows at most 10 characters.
Phone numbers go in 9-digit form: 712345678, not 0712345678 or 251712345678.
Amounts are in ETB, with at most 2 decimals. Send currency: "ETB" with every amount.
Every call sends a real prompt or SMS to a real customer, even in sandbox. Only call it when the customer has just asked to pay.
A callback can be missed or repeated. Always confirm with Get a payment, and never deliver the same order twice.