Djomy

Capabilities

Gotchas

• ⚠This capability is only used for the direct payment flow (create_payment). Do NOT call it after create_payment_gateway — that flow handles OTP on the Djomy portal itself.
• ⚠The OTP is sent by the mobile operator (Orange Money, MTN MoMo) to the payer's phone. Djomy does not send the OTP — you must collect it from the payer in your UI.
• ⚠The path parameter is called transactionReference in the URL but corresponds to the transactionId returned by create_payment. They refer to the same value.
• ⚠Even after a successful OTP confirmation, call verify_payment to confirm status === 'SUCCESS' before fulfilling the order.
• ⚠Auth requires two steps: (1) compute HMAC-SHA256(clientId, clientSecret) as hex, (2) call POST /v1/auth with header X-API-KEY: clientId:hexSignature to get a Bearer token.
• ⚠Auth requires two steps: (1) compute HMAC-SHA256(clientId, clientSecret) as hex, (2) call POST /v1/auth with header X-API-KEY: clientId:hexSignature to get a Bearer token. Both DJOMY_CLIENT_ID and DJOMY_CLIENT_SECRET env vars are required.
• ⚠For Orange Money (OM) and MTN MoMo (MOMO) direct payments, status returns PENDING immediately. The payer receives an OTP from their operator. You must then call confirm_otp with the transactionId and the OTP to complete the payment.
• ⚠Always verify payment status server-side via verify_payment before fulfilling an order. Never trust only the callback or paymentUrl redirect.
• ⚠The base URL in this spec is the sandbox (https://sandbox-api.djomy.africa). Replace with the production URL for live payments.
• ⚠metadata must be a flat object — no arrays or nested structures. Values can be strings, numbers, or booleans.
• ⚠Auth requires two steps: (1) compute HMAC-SHA256(clientId, clientSecret) as hex, (2) call POST /v1/auth with header X-API-KEY: clientId:hexSignature to get a Bearer token.
• ⚠The gateway flow handles OTP internally — the payer completes everything on the Djomy portal. Do NOT call confirm_otp after this endpoint. Wait for the webhook instead.
• ⚠Redirect the payer to redirectUrl immediately after receiving the response. Do not delay — the link may expire.
• ⚠Always verify payment status server-side via verify_payment before fulfilling an order. The returnUrl redirect is not a proof of payment.
• ⚠If an invalid payment method is passed in allowedPaymentMethods (wrong spelling or unsupported value), Djomy silently falls back to showing all available methods instead of returning an error.
• ⚠Use paymentLinkReference (not reference) to retrieve or track the link. The reference field is deprecated according to the API spec.
• ⚠For UNIQUE links, Djomy automatically deactivates the link after the first successful payment. Do not rely on a second payment going through.
• ⚠sendSms: true requires phoneNumber to be set. If phoneNumber is omitted, the SMS will not be sent and no error is returned.
• ⚠Auth requires two steps: (1) compute HMAC-SHA256(clientId, clientSecret) as hex, (2) call POST /v1/auth with header X-API-KEY: clientId:hexSignature to get a Bearer token.
• ⚠countryCode must be uppercase (GN, SL, LR). The API validates against the pattern ^[A-Z]{2}$ and will reject lowercase values.
• ⚠Pass paymentLinkReference (not reference) as the path parameter. The reference field is deprecated — always use paymentLinkReference returned by create_payment_link.
• ⚠A 404 is returned if the reference does not exist or belongs to a different merchant account. Check that you are using the correct credentials and the correct reference.
• ⚠For UNIQUE links, data.status becomes REVOKED after one successful payment — not PAID. PAID is only set in specific conditions. Use data.numberOfUsage > 0 as the reliable indicator that a UNIQUE link has been used.
• ⚠Auth requires two steps: (1) compute HMAC-SHA256(clientId, clientSecret) as hex, (2) call POST /v1/auth with header X-API-KEY: clientId:hexSignature to get a Bearer token.
• ⚠The base URL in this spec is the sandbox (https://sandbox-api.djomy.africa). Replace with the production URL for live payments.
• ⚠This endpoint requires both the Bearer token (Authorization header) and the X-API-KEY header (clientId:HMAC signature). Omitting either will return 401.
• ⚠Never fulfill an order until data.status === 'SUCCESS'. PENDING means payment is still in progress. CAPTURED means the amount has been collected but may differ from SUCCESS depending on the flow.
• ⚠receivedAmount is what you actually receive after Djomy deducts fees. Use this for your accounting, not paidAmount.
• ⚠The currency field returns non-ISO strings: 'GNF', 'FCFA', 'Dollar', 'Leones'. Map these to ISO 4217 codes (GNF, XOF, USD, SLE) in your system.
• ⚠Auth requires two steps: (1) compute HMAC-SHA256(clientId, clientSecret) as hex, (2) call POST /v1/auth with header X-API-KEY: clientId:hexSignature to get a Bearer token.
• ⚠[MUST TELL USER] Le webhook Djomy ne se déclenche pas automatiquement. Le développeur doit d'abord configurer l'URL de son endpoint dans le dashboard Djomy (espace développeur). Sans cette étape, aucun événement ne sera envoyé, même si le paiement est traité avec succès.
• ⚠[MUST TELL USER] Djomy n'appelle l'URL webhook qu'en HTTPS — les URLs http:// sont silencieusement ignorées. En développement local, le webhook ne se déclenchera jamais sans tunnel HTTPS. Indiquer explicitement à l'utilisateur : lancer `ngrok http 3000`, puis configurer l'URL ngrok dans l'espace développeur Djomy avant de tester.
• ⚠Always verify the webhook signature before processing the event. Compute HMAC-SHA256(rawBody, clientSecret) as hex and compare it to the X-Webhook-Signature header value. Reject any request where they don't match.
• ⚠Never fulfill an order based on the webhook payload alone. Always call verify_payment with the transactionId to confirm status === 'SUCCESS' server-side.
• ⚠Return HTTP 200 immediately, even if your processing is asynchronous. Djomy considers a non-200 response a delivery failure.
• ⚠You receive events for all lifecycle changes (payment.created, payment.pending, payment.success, payment.failed). Only act on payment.success for order fulfillment.