Your first payment

This page takes you through one complete test payment in about five minutes: your server logs in, creates a payment link, you pay it with test money, and your server confirms it. It is the same flow your live integration will use.

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

1. 1

   Log in

   Send your API key. Paste the whole key into ZOORYA_API_KEY — the command splits it for you.

   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 (the token, it starts with Bearer ) and tenantId from the response. The token works for about 15 minutes.

2. 2

   Create a payment link

   Ask Zoorya Pay for a payment link for this order: the amount, your own unique ID (externalUniqueId) and the wallet that receives the money.

   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": "firsttest001",
       "destinationWalletId": WALLET_ID,
       "landingUrl": "https://example.com/done",
       "additionalFields": [
         { "id": "HMACKey", "value": "YOUR_HMAC_KEY" },
         { "id": "callbackUrl", "value": "https://example.com/webhooks/zoorya" }
       ]
     }'

   You get back the payment, with its link:

   json

   {
     "paymentId": 4581646,
     "status": "PENDING",
     "completionUrl": "https://sandbox.eclipse.et/t/abc12",
     "paymentType": "LINK"
   }

3. 3

   Pay

   Open completionUrl in a browser. Pick a method, for example telebirr, and finish the payment with a phone you control. When it is done, the browser goes to your landingUrl.

4. 4

   Confirm from your server

   The browser's word is not proof — anyone can open your landingUrl. Ask Zoorya Pay from your server whether the order is really paid:

   bash

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

   json

   {
     "paymentId": 4581646,
     "status": "SUCCESSFUL",
     "amount": 10,
     "currency": "ETB",
     "externalUniqueId": "firsttest001"
   }

   status: "SUCCESSFUL" with the right amount means the payment is confirmed.

5. 5

   See it in the portal

   Open Transactions in the sandbox portal. The payment is there.

Next#