Djomy

confirm_otp

• ⚠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.
• ⚠HTTP 403 "Accès non autorisé à cette transaction" when the transaction does not belong to your account.
• ⚠Only the X-API-KEY header is documented for this endpoint (no Bearer token, unlike create_payment and verify_payment).

create_payment

• ⚠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.
• ⚠metadata must be a flat object — no arrays or nested structures. Values can be strings, numbers, or booleans.
• ⚠[VERY IMPORTANT] Unless the user explicitly requests the direct flow (no redirect, OTP collected in your own UI), always use create_payment_gateway instead. create_payment requires you to know the payment method and payer identifier upfront and to handle OTP confirmation yourself. create_payment_gateway delegates everything to the Djomy portal.
• ⚠A missing or invalid X-API-KEY returns HTTP 401 (documented as "Clé API manquante ou invalide").

create_payment_gateway

• ⚠payerNumber is strictly enforced by the API despite being described as 'used to pre-fill the portal'. Passing an empty string or omitting it returns 400: 'Le numéro de téléphone du payeur est obligatoire.' Always collect the payer's phone number before calling this endpoint.
• ⚠[VERY IMPORTANT] This is the default integration method for Djomy. Unless the user explicitly requests a direct flow with OTP handling in their own UI, always use create_payment_gateway. It delegates payment method selection and OTP handling to the Djomy portal.
• ⚠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.
• ⚠A missing or invalid X-API-KEY returns HTTP 401 (documented as "Clé API manquante ou invalide").

create_payment_link

• ⚠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.
• ⚠countryCode must be uppercase (GN, SL, LR). The API validates against the pattern ^[A-Z]{2}$ and will reject lowercase values.
• ⚠A missing or invalid X-API-KEY returns HTTP 401 (documented as "Clé API manquante ou invalide").

get_payment_link

• ⚠Fill the {reference} path parameter with paymentLinkReference from create_payment_link, not its deprecated `reference` field ("Merci de considérer le champs paymentLinkReference").
• ⚠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.
• ⚠Pass the reference directly as a path segment — do not URL-encode it. The paymentLinkReference format contains only safe characters.
• ⚠A missing or invalid X-API-KEY returns HTTP 401 (documented as "Clé API manquante ou invalide").

verify_payment

• ⚠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.
• ⚠A missing or invalid X-API-KEY returns HTTP 401 (documented as "Clé API manquante ou invalide").

webhook_payment_completed

• ⚠[MUST TELL USER] The Djomy webhook does not fire on its own. The developer must first set their endpoint URL in the Djomy dashboard (developer area). Without this step, no event is sent, even when the payment succeeds.
• ⚠[MUST TELL USER] Djomy only calls the webhook URL over HTTPS — http:// URLs are silently ignored. In local development, the webhook never fires without an HTTPS tunnel. Tell the user explicitly: run `ngrok http 3000`, then set the ngrok URL in the Djomy developer area before testing.
• ⚠Verify X-Webhook-Signature as described in webhook.signature before processing the event; ignore the webhook if it does not match or if the version prefix is not v1.
• ⚠Read the payment from data.payment with a V2 webhook configuration (the default for new configurations), or from data with V1 (merchants integrated before V2). The version is shown in the Djomy developer space — ask the user which one their configuration uses, or handle both.
• ⚠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 every event listed in eventType (payout.* only with a V2 configuration). Only act on payment.success for order fulfillment.