Zoorya Pay Developers

Payment links

How a one-time link works, how externalUniqueId links it to your order, and what landingUrl means.

A payment link is the payment page Zoorya Pay creates when you call Create one-time link. This page explains how it links to your order, what to send to the customer, and what happens when the customer comes back to your landingUrl.

completionUrl — the link for the customer#

The response's completionUrl is the page where the customer pays. Redirect the browser to it, or send it by SMS, Telegram or email. The customer opens it and pays with any method.

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

Best practice: create the link at the moment the customer clicks Pay, not when the order is first created.

externalUniqueId — one per payment#

externalUniqueId is your own ID for the payment. It comes back in the webhook, so you can find your order.

  • Use a new one for every link — reusing one is rejected.
  • Letters and digits only, at least 6 characters.
  • Keep it, and the paymentId from the response, against your order.

landingUrl is not proof of payment#

After paying, the customer's browser goes to your landingUrl. Use this page to show a message to the customer. Do not use it to release goods — anyone can open that URL. Always confirm with Get a payment on your server.

callbackUrl and HMACKey#

For links, both go in additionalFields, not at the top level:

json
"additionalFields": [
  { "id": "HMACKey", "value": "your-hmac-key-from-the-merchant-portal" },
  { "id": "callbackUrl", "value": "https://your-domain.et/webhooks/zoorya" }
]

Create an HMACKey on the Create one-time link page, or use the one in the merchant portal under Payment links → HMACKey. Zoorya Pay POSTs the final result to callbackUrl — see Webhook shape.