Changelog

📘

Recipient nationality and date_of_birth

POST /recipients and PATCH /recipients/{identifier} now accept two optional fields: nationality, a three-letter ISO 3166-1 alpha-3 country code (for example ARE, GBR), and date_of_birth, in YYYY-MM-DD format. Both are returned on every recipient response (GET /recipients, GET /recipients/{identifier}, and the create/update responses), and are null when not supplied. Supplying them upfront means we no longer need to request beneficiary details separately before processing a payout. A date_of_birth in the future or a nationality that is not a valid alpha-3 code returns 422 VALIDATION_ERROR.

17/09/26

📘

Recipient Balances

We've added a new endpoint, GET /recipients/{identifier}/balances, which returns a recipient's real-time ledger balance. Recipients accumulate balance from payouts_share splits on payments, and the balance is deducted when a payout is issued to them.

06/08/26

📘

charge.* Webhook Events Renamed to payment.*

We've renamed the charge.* webhook events to payment.* (payment.failed, payment.succeeded, payment.refund_initiated, payment.refunded, payment.refund_failed, payment.card_verified, payment.authorized, payment.voided). The charge.* names are kept as legacy aliases — both are dispatched for the same event, so existing subscriptions keep working unchanged. New integrations should subscribe to payment.*.

06/08/26

📘

Recipients Moved to an Unscoped Path

The Recipients endpoints are now documented at the unscoped /recipients path instead of /accounts/recipients: GET /recipients, POST /recipients, GET /recipients/{identifier}, PATCH /recipients/{identifier}, and DELETE /recipients/{identifier}. The old /accounts/recipients routes still work for backward compatibility, but /recipients is the one to use going forward. No request or response fields changed.

06/08/26

📘

"Transactions" Renamed to "Payments"

To match Mamo dashboard terminology, we've renamed the "Transactions" category to "Payments" and updated the wording across GET /payments, POST /payments (MIT), GET /payments/{paymentId}, and the refund/capture/reverse endpoints to consistently say "payment" instead of "charge"/"transaction". No request or response fields changed.

27/07/26

📘

Fixed Incorrect Request URLs Across All Endpoints

We've fixed a bug affecting nearly every endpoint in these docs where the displayed request URL incorrectly repeated the resource path (e.g. .../subscriptions/subscriptions instead of .../subscriptions). No request or response fields changed, only the documented URLs.

27/07/26

📘

Renamed Charges to Payments, Disbursements to Payouts

We've renamed the /charges endpoints to /payments (GET /payments, GET /payments/{paymentId}, POST /payments/{paymentId}/refunds, POST /payments/{paymentId}/captures, POST /payments/{paymentId}/reverses), and the /disbursements endpoints to /payouts (GET /payouts, POST /payouts, GET /payouts/{payoutId}). Path parameters chargeId and disbursementId are now paymentId and payoutId respectively. Request and response fields are unchanged — only the URLs and path parameter names.

27/07/26

📘

Fixed Incorrect Payouts & IBAN Validation URLs

We've fixed a bug where the displayed request URL for several endpoints incorrectly repeated part of the path (e.g. .../disbursements/disbursements instead of .../disbursements). This affected POST /disbursements, GET /disbursements, GET /disbursements/{disbursementId}, POST /international_payouts, and GET /iban/validate — no request or response fields changed, only the documented URLs.

23/07/26

📘

Refund Breakdown on Transaction Details

The GET /charges/{chargeId} response now includes a refunds array with a breakdown of each individual refund issued against the charge (id, amount, amount_currency, billing_amount, billing_amount_currency). We've also added settlement_fee, settlement_vat, payment_link_id, payment_link_url, external_id, max_refund_amount, and card expiry (card_expiry_month, card_expiry_year) and card_id fields to the response.

23/07/26

📘

Phone Number for Prefilled Customer Details

We've added a new field called phone_number to the POST /links and PATCH /links/{linkId} endpoints. Along with email, it will pre-populate the customer details step at checkout, and is returned in the prefilled_customer object in the response.

20/07/26

📘

List Disbursements

We've added a new endpoint, GET /disbursements, which returns a paginated list of all disbursements (payouts) issued by the business — previously you could only fetch a single disbursement by ID via GET /disbursements/{disbursementId}.

20/07/26

📘

International Payouts

We've added a new endpoint, POST /international_payouts, to initiate an international payout to an existing recipient created via the Create Recipient API. The destination currency, corridor, and FX rate are determined automatically from the recipient's bank details, and the endpoint requires an Idempotency-Key header to safely retry requests.

17/07/26

📘

IBAN Validation

We've added a new endpoint, GET /iban/validate, which validates a UAE IBAN and returns the bank it belongs to. This is useful for verifying a recipient's bank details before creating them with the Create Recipient API.

17/07/26

📘

Payout to a Saved Recipient

We've added a new field called recipient_id to the POST /disbursements endpoint. When provided, the disbursement uses the bank details already saved against that recipient, so you no longer need to pass raw bank details (first_name_or_business_name, last_name, account) on every payout.

17/07/26

📘

Recipient ID Field

The Create Recipient response now also returns an id field. The existing identifier field is kept for backward compatibility, but new integrations should use id.

17/07/26

📘

Change Customer Subscription

We've added a new endpoint, PATCH /subscriptions/{subscriptionId}/subscribers/{subscriberId}/change_customer_subscription, which upgrades a subscriber to a target subscription without requiring the customer to re-enter their card details. The difference between plans is prorated and charged automatically before the subscriber is moved onto the new subscription.

14/07/26

📘

Create Subscription API

We've added a new endpoint, POST /subscriptions, which lets you create a subscription's billing schedule (frequency, interval, start/end date) independently of a payment link. Pass the returned identifier as the new subscription_id field on the Create Payment Link or Update Payment Link APIs to attach it — the previous inline subscription object is still supported for backward compatibility.

14/07/26

📘

Subscription Terminology Update

We've updated our API docs to consistently use "subscription" instead of "recurring payment" throughout, including renaming the Cancel Recurring Payment endpoint to Cancel Subscription. This is a documentation/terminology change only — no request or response fields were affected.

07/07/26

📘

Invoices API

We've added a new endpoint, POST /invoices, to create and send an invoice to a customer via email. You can configure the amount, currency, customer details, VAT, processing fees, and an external ID, and the response includes a hosted payment_url for the customer to pay the invoice.

20/04/26

📘

Account Balances

We've added a new endpoint, GET /finances, which returns the balances of your business's different Mamo accounts (main wallet, debit, cashback, etc.) along with each account's currency and type.

16/04/26

📘

Subscriptions Available to All Merchants

Subscription payment links (the subscription object on the Create Payment Link API) no longer require the Premium Business Plan and are now available to all merchants.

16/04/26

📘

Partner Cards

We've added a full Partner Cards API for issuing and managing virtual cards for your business partners: POST /partner_cards to create a card, GET /partner_cards and GET /partner_cards/{identifier} to list and view cards, PATCH /partner_cards/{identifier} to update a card's spending limit, PATCH /partner_cards/{identifier}/cancel to cancel a card, and GET /partner_cards/{identifier}/transactions to fetch a card's transaction history.

16/04/26

📘

Update Expense & New Webhook Events

We've added a PATCH /expenses/{expenseId} endpoint to update an expense's description, invoice number, and status. We've also added 4 new webhook events — expense.create, expense.update, card_transaction.create, and card_transaction.update — that you can subscribe to via the Register Webhook API.

16/04/26

📘

Hold and Charge Later for Merchant Initiated Transactions

We've added a new field called hold_and_charge_later to the POST /charges (Merchant Initiated Transaction) endpoint. This allows you to place a payment on hold and capture it later using the Capture API, the same way this was already possible for payment links.

16/04/26

📘

Card Transactions, Expenses & Receipts

We've added new endpoints to track card spend: GET /cards/transactions and GET /cards/transactions/{transactionId} return card transactions along with their associated expense details, and GET /expenses/receipts / GET /expenses/receipts/{identifier} return uploaded receipt files for an expense.

16/04/26

📘

Terms and Conditions for Payment Links

We've added a new field called terms_and_conditions_url to the POST /link endpoint. If provided, the customer will be required to accept your terms and conditions before proceeding to payment.

16/04/26

📘

Custom Data and External ID for Merchant Initiated Transactions

We've added 2 new fields called custom_data and external_id to the POST /charge endpoint. This allows you to send custom objects and your own ID to associate with the charge.

13/08/24

📘

Receipt for Merchant Initiated Transactions

We've added a new field called send_customer_receipt to the POST /charge endpoint to enable or disable automated receipts after each charge using a saved card.

24/07/24

📘

Hold Funds and Charge Later

We've added a new field named hold_and_charge_later to the POST /link endpoint. This functionality allows you to hold funds on a card and then capture the payment later using the Capture API.

23/04/24

📘

Payment Link Rules

We've added a new rule field to the POST /link endpoint. This field allows users to define business rules for the payment link, such as restricting accepted card types based on their BIN numbers.

14/03/24

📘

Virtual Corporate Cards

We've introduced a new API for creating Virtual Corporate Cards, single-use cards designed to streamline corporate expenses such as travel and accommodations.

28/02/24

📘

Payout Shares & Recipients

We've introduced a new field called payout_share to the POST /link endpoint. This feature automates splitting a portion of the payment to a recipient you create using the Create Recipient API.

We've also added functionalities to delete, retrieve, and update recipients you've created.

20/02/24