Skip to main content

Changelog

Last updated: 2026-09-26

2026-09-26 — Correction handling and transfer response compatibility​

  • Clarified that a completed pay-in can later receive a correction of the same payment, possibly including a FAILED update before a corrected completion. Reconcile these updates by payment ID; do not treat them as new payments.
  • Mobile-money-transfer responses no longer include a separate transfer reference. Use instructions for customer-facing values and the payment ID or merchant reference to correlate the payment with your order.
  • Clarified that unavailable confirmed balance data does not by itself disable payment processing; the payout response decides whether a request is accepted.

2026-09-25 — Balance, retry, and transfer instruction guidance​

  • Expanded balance examples with authorityState, balance scopeType, currency precision and history filters. Clarified how to use current balances and individual movements for reconciliation.
  • Clarified that unconfirmed balance information does not itself disable payouts, and that a funding comparison includes the applicable payout fee.
  • Documented pay-in retries with the same reference, hosted-page replay limits and recovery of the current attempt by merchant reference.
  • Corrected webhook retry guidance: at most 100 attempts within seven days and a one-hour cap on the delay requested through Retry-After.
  • Clarified how to wait for mobile-money-transfer instructions and distinguish display text from actionable payment details. Use your payment ID or merchant reference to correlate the payment with your order.
  • Added payout error examples that distinguish support-required account conditions, retryable preparation failures and unknown transport outcomes.
  • Explained reference conflicts, bounded retries and later amount corrections on the same payment, with examples for reconciliation.
  • Aligned amount-format and redirect guidance: send integer minor units and confirm payment completion through status reads or verified webhooks.

2026-09-10 — Balance history categories and payment amounts​

  • Documented settlement and accounting-reversal categories in balance history, their effect on available balances, and the difference between recording time and the date of an external transfer.
  • Clarified supported source filters and payment-only correlation fields.
  • Added the distinction between requested amount and recognized gross actualAmount, including payment-ID idempotency and historical-payment guidance.

2026-08-30 — Orange OTP operator contract​

  • Documented the required Orange OTP continuation across BF / XOF, CI / XOF, SN / XOF, ML / XOF, CM / XAF, CF / XAF, GQ / XAF, CD / CDF, and SL / SLE.
  • Clarified that this market list defines the Orange continuation flow, while current account and realm availability still comes from operator discovery.
  • Removed the obsolete four-market and separate-activation wording from linked integration guidance.

2026-08-24 — Expanded Orange OTP continuation to Côte d’Ivoire and Cameroon​

  • Added Côte d’Ivoire (CI / XOF) and Cameroon (CM / XAF) to the configured direct Orange OTP scope in both live and sandbox realms.
  • Continue only when operator discovery returns ORANGE for the current account and realm, then submit the customer-provided token through POST /merchant/api/v1/payins/authorize-otp.
  • The existing 15-minute authorization and payment reconciliation guidance is unchanged.

2026-08-20 — Prepared Live Senegal and Burkina Faso mobile-money OTP​

  • Documented the configured Orange OTP scope for direct live mobile-money pay-ins in Senegal (SN / XOF) and Burkina Faso (BF / XOF).
  • Treat the flow as available only after rollout and only when operator discovery returns ORANGE for the current account and realm.
  • Clarified how customers get or generate the one-time code and preserved the 15-minute authorization window and reconciliation guidance.

2026-08-19 — Nigeria and South Africa mobile-money availability​

  • Mobile money is unavailable for both pay-ins and pay-outs in Nigeria (NG / NGN) and South Africa (ZA / ZAR).
  • Removed the previously listed Airtel and MTN Nigeria operator identities from the consolidated public operator catalog.
  • Integrations should not submit mobile-money requests for these markets and should continue using catalog and matching discovery responses for other request contexts.

2026-08-13 — Expanded mobile-money operator identity catalog​

  • Added public operator identities for Ethiopia, Gabon, and Republic of the Congo to the consolidated identity/planning catalog.
  • Clarified that the catalog defines public identities only; use discovery responses for your request context to determine availability by direction, trafficVertical, merchant, and realm.

2026-08-11 — Sandbox mobile-money OTP​

  • Added the Orange OTP continuation for direct sandbox mobile-money pay-ins in Senegal (SN / XOF) and Burkina Faso (BF / XOF).
  • Documented the existing POST /merchant/api/v1/payins/authorize-otp operation, 15-minute submission window, pending-result reconciliation, and retry guidance.
  • Clarified that a supported explicit trafficVertical is authoritative for the current discovery or payment request; the account classification applies when the field is omitted or unspecified.

2026-08-10 — Merchant integration refresh​

  • Consolidated Live and Sandbox on one Merchant API URL. *_prod_* keys select the live realm and *_test_* keys select the sandbox realm.
  • Added Merchant Portal self-service guidance for API credential rotation and webhook URL configuration.
  • Consolidated the previous account-access setup page into Merchant Portal while preserving its existing documentation URL as a compatibility handoff.
  • Removed roadmap wording so the Portal guide describes only currently available self-service capabilities.
  • Marked countryCode as required for every hosted pay-in, direct pay-in, and payout creation request.
  • Documented payout retries by merchantReference and kept pay-in retry guidance reconciliation-first.
  • Clarified safe handling of mobile-money continuation signals and optional customer-facing messages.
  • Published the complete current public mobile-money operator code/name catalog while keeping discovery authoritative for merchant and realm availability.
  • Expanded the coverage reference with the additional published market and currency contexts.

2026-08-07 — Legacy balances endpoint removed​

  • Removed the legacy v1 balance-read endpoint from the Merchant API.
  • Use GET /merchant/api/v2/balances for current country-scoped balance positions and GET /merchant/api/v2/balances/history for movement history.
  • Legacy raw balance-account fields (accountId, accountType, and amount) are no longer part of the merchant balance contract.
  • There is no one-to-one replacement for accountId or accountType: select a V2 position by currencyCode plus its countryCode market scope. The former single amount also has no universal replacement—use currentMinor for the aggregate position, availableMinor for the available bucket, and payoutAvailableMinor only for an advisory payout pre-check. See Balances for the bucket relationships and migration rules.

2026-07-17 — Merchant API documentation refresh​

This release refreshes the complete Merchant API integration journey while preserving established public documentation URLs.

  • Reorganized navigation around discovery, inbound pay-ins, outbound payouts, operations, reconciliation, and focused API references.
  • Added catalog-first method selection, Mobile Money Transfer guidance, and the complete approved public mobile-money alias/name catalog. Live account and environment availability still comes from discovery.
  • Clarified when hosted mobile money sends mobileMoneyOperator, plus current bank-transfer submethod, voucher, and method-specific request rules.
  • Added detailed Balance V2 position and history documentation, including country scope, bucket relationships, payout pre-checks, filters, ordering, movement correlation, and pagination.
  • Expanded PaymentOrder, failure-reason, lifecycle, payment-read, and late-correction guidance.
  • Corrected webhook acknowledgement/retry semantics and expanded raw-body HMAC signature verification and replay protection guidance.

Existing integrations should recheck Catalog and availability, Choose a payment flow, Balances, and Webhooks against their current request and reconciliation logic.

Earlier updates​

  • 2026-06-13 — Refreshed merchant swagger, clarified H2P Mobile Money operator handling during hosted checkout, and added merchant-reference payment lookup.
  • 2026-05-22 — Added mobileMoneyDetails.voucherPin, the Vouchers guide, refreshed merchant swagger host metadata, and clarified H2H detail validation, webhook idempotency, and late status corrections.
  • 2026-05-04 — Added mobile-money operator coverage and clarified catalog-first operator discovery for pay-ins and pay-outs.
  • 2026-05-02 — Added coverage, mobile-money, and operator-discovery guides for market planning and checkout setup.
  • 2026-05-01 — Added pay-in mobile-money operator discovery and clarified exact operator-code reuse.
  • 2026-04-28 — Added account-name guidance for mobile-money payouts.
  • 2026-04-20 — Clarified catalog discovery, countryCode, validation errors, webhook retries, and Gambia and Malawi mobile-money examples.
  • 2026-04-18 — Added catalog-based market discovery and clarified multi-market currency handling, payout customerSegment, pay-in contact fields, and paymentUrl.
  • 2026-04-11 — Updated pay-in and pay-out request references and countryCode guidance.
  • 2026-04-03 — Clarified Tanzania mobile-money examples, operator discovery, and nested mobile-money validation fields.
  • 2026-04-02 — Added mobileMoneyOperator for H2P pay-ins and mobileMoneyDetails.operator for H2H mobile-money pay-ins.
  • 2026-03-05 — Clarified payment-method coverage, rejected methods, and discovery flow.
  • 2026-03-03 — Added request-context fields, payment-method detail guidance, and webhook idempotency guidance.
  • 2026-02-24 — Corrected query parameter casing, added balances, and clarified webhook acknowledgements, key types, and payment status responses.