Changelog

Changes to the Monerail API, newest first.

Additions (new endpoints, optional parameters, response fields, event types, error codes) can ship at any time. Changes that may require action on your side are marked Action needed.

2026-10-31 · New countries#

Eight more countries are open in the API, for collections and mobile money payouts: Gabon, Chad, Congo and Central African Republic (XAF), Mali and Niger (XOF), Guinea (GNF) and DR Congo (CDF).

• New currencies: GNF (whole francs) and CDF (in centimes; send multiples of 100). See Amounts and currencies.
• country selects the country when a currency is shared: XAF still defaults to CM, XOF to SN. A country that is not open for the currency returns 400 country_unsupported.
• List operators accepts an optional country query parameter, for example GET /v1/operators?currency=XAF&country=TD.
• Codes generated by the customer: for some operators (Orange Money in Guinea, for example), the customer dials a USSD code to get a payment code. The collection is requires_otp and next_action.ussd_code holds the code to dial; send the payment code with authorize.
• next_action.type: "redirect" with next_action.url may be returned when the customer approves on a payment page.
• New error codes: country_unsupported, bank_transfer_unsupported (bank payouts are not available in these eight countries), test_phone_required (test mode accepts only the test numbers there), otp_not_expected.

2026-10-31#

Security and reliability hardening.

• Action needed. Identity verification: place_of_birth is now required by Submit identity verification. address.postal_code stays optional. Limited to 5 submissions per cardholder per 24 hours. The key’s role is checked before any document is stored.
• Action needed. Collections in NGN now fail with 400 currency_unsupported. Payouts and settlements in NGN still work.
• Action needed. Bank payouts: recipient.bank_code must exactly match a code from List banks. Otherwise: 400 bank_account_invalid.
• Action needed. Single-use cards cannot be funded or withdrawn from (400 card_single_use), and cannot have a spending_limit (400 parameter_invalid). A single-use card can be paid once; it is terminated automatically 30 days after issue.
• Action needed. Read permissions: reading events needs the Owner, Finance or Developer role; reading webhook endpoints needs Owner or Developer. Otherwise: 403 permission_denied.
• Rate limits: 100 requests per 10 seconds per API key, and 10 redeliveries per event per hour. Beyond: 429 rate_limited with Retry-After. See Rate limits.
• Card actions: when the card issuer’s answer is not final, issue, fund, withdraw, freeze, unfreeze and terminate return 202 and the result arrives by webhook. Money returns to the cards balance only once a failure is final.
• Idempotency: if a problem occurs after money was sent to a partner, the API returns 202 with the object instead of a 5xx, and a retry with the same Idempotency-Key replays it.
• Webhook endpoints: URLs with an IP address or user:password@ are refused (400 url_invalid). Deliveries to domains that resolve to private addresses fail with “destination not allowed” and are retried. The signing secret is only in the original 201 response, not in replays.
• Collections: failure_code is now failed or expired; failure_message may give a reason.
• Identity: verification is per business. A person verified by another business is verified again for yours.
• Errors: requests rejected for a reason without its own code return a generic request_invalid message, and 5xx errors a generic message. Partner refusals keep their reason under provider_declined.
• Test helpers: Simulate a card payment accepts status: "declined", which sends card.authorization_declined and charges nothing. Simulate a verification decision accepts a reason.
• Headers: every response carries Strict-Transport-Security and X-Content-Type-Options: nosniff.
• Reference data: List operators and List banks are cached for up to 10 minutes.

2026-10-30#

First release of the Monerail API v1 (Monerail-Version: 2026-10-30).

• Balance, collections (approval on the phone or code), payouts to mobile money and bank accounts, settlements, transactions.
• Cardholders and identity verification, virtual Visa and Mastercard cards for team members, customers and AI agents.
• Webhook endpoints and events, signed with HMAC-SHA256 and retried 8 times over about 42 hours.
• Reference data (operators, banks), test helpers, idempotency keys, cursor pagination.