Troubleshooting

• Paste the whole API key as copied from the portal. It is split at the first colon: identity before it, password after it.
• Check you are using the right environment: a sandbox key does not work on production, and the reverse.
• The key may be revoked or disabled. Check it in Developer → API keys.
• Lost the API key? Rotate it to get a new one.

The token is missing, wrong or expired — it works for about 15 minutes. Log in again and send the whole headerValue as the Authorization header, including Bearer .

The description in the response says which rule failed. See Error codes. Common causes:

• An externalUniqueId you already used — send a new one for every payment.
• A missing destinationWalletId, type or currency.
• An amount with more than 2 decimals.

Your business is not approved to go live yet, or has no active wallet. Finish production sign-up and wait for the review. See Go live.

The customer has not paid the link, or not approved on their phone or bank yet. Wait for the webhook, and call Get a payment again later.

• For payment links, the callback URL goes in additionalFields (id: "callbackUrl"), not at the top level. For C2B Direct and QR payments it is callbackUrl at the top level. There is no portal setting.
• It must be reachable from the internet. localhost does not work — use a tunnel such as ngrok when testing.
• Production needs https://.
• Reply 2xx quickly.
• Payment links made in the portal send a webhook only if you set a callback URL on the link.
• You can always call Get a payment instead.

Make the QR code from the exact value — qrUrl for telebirr QR, barcode for EthSwitch QR — without adding or trimming anything. Scan telebirr QR with the telebirr app, and EthSwitch QR with a bank app. In Try it, the QR code is drawn for you under the response.