Mastercard Cross-Border Services is a service that lets a financial institution send funds to recipients in other countries through a single connection to Mastercard.

Mambu Payments connects you to it. You work with live FX rates, quotes, and payment orders, so you never call Mastercard APIs yourself.

How it works

You, the Originating Institution, send funds on behalf of a sender. You can price the transfer first by reading an FX rate or requesting a quote. You then create a payment order in Mambu Payments. Mambu Payments sends the payment order to Cross-Border Services over a single connection. Mastercard delivers the funds to the receiving system, which holds the recipient's account.

Key concepts

Concept	Definition
Originating Institution	The financial institution, or a provider acting for it, that sends funds through Cross-Border Services on behalf of a sender. In Mambu Payments, this is you.
Pricing model	Who calculates the sender's FX markup and fees. With Customer Managed Sender Pricing (CMSP, also called wholesale), Mastercard provides the FX rate and you add your own markup. With Mastercard Managed Sender Pricing (MMSP, also called retail), Mastercard stores your agreed fees and markups and returns the calculated amounts.
Forward and reverse payments	A forward payment fixes the amount the sender pays and calculates what the recipient receives. A reverse payment fixes the amount the recipient receives and calculates what the sender pays.
Carded rate	An FX rate for a currency pair that Mastercard publishes for a validity period. Carded rates are opt-in. You can reuse one across multiple payments until it expires.
Quote	A price calculation for one transfer: the FX rate, the fees, and the amounts charged and credited. A quote moves no funds. It expires and applies to a single payment.

Use cases

Cross-Border Services groups transfers into four types.

Transfer type	Description	Examples
P2P (person to person)	An individual sends funds to another person.	Send money to family abroad. Contribute to a wedding gift.
P2B (person to business)	An individual pays a business.	Pay for a service.
B2B (business to business)	An institution pays another institution.	Pay suppliers.
B2P (business to person)	A business disburses funds to individuals.	Pay staff wages. Send insurance claim or humanitarian aid payments. Pay sellers on your marketplace.

Mambu Payments derives the transfer type from the holder_type of the originating and destination accounts: individual or legal_entity.

Value proposition

One connection, several payout endpoints. A single integration reaches bank accounts, mobile wallets, cards, and cash agents. Mambu Payments supports bank accounts and wallets as recipient accounts.
Pricing before you send. Quotes and carded rates give you pricing information before you create a payment order, for the customers and corridors that Mastercard enables.
Your choice of pricing model. Use Mastercard FX rates with your own markup, or have Mastercard calculate amounts from your stored fees and markups.
Settlement and reporting. Mastercard provides settlement services and reporting for transactions, settlement, and reconciliation.
One Mambu Payments integration. You use the same payment_order object and webhook events as for your other payment schemes.

How Mastercard maps to Mambu Payments

Each Cross-Border Services feature maps to one Mambu Payments object.

Mastercard	Mambu Payments	Endpoint
Carded rate	Live FX rate	`GET /v1/live_fx_rates`
Quote	`fx_quote`	`POST /v1/fx_quotes`
Payment	`payment_order` with `type` set to `mastercard_crossborder_services`	`POST /v1/payment_orders`

Carded rate to live FX rate

GET /v1/live_fx_rates returns Mastercard carded rates in the Mambu Payments format. Mambu Payments calls the Carded Rate Pull API for you. The endpoint stores nothing and changes nothing at Mastercard. Carded rates are an opt-in Mastercard service for configured corridors.
A live FX rate is not guaranteed. Use it to price a transfer before you create a payment order. To lock a rate, create an fx_quote.
Pass connected_account_id and symbol. Add recipient_instrument_type to filter by recipient account type: bank_account or wallet.

The request below returns the current rate from US dollars to Philippine pesos.

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/live_fx_rates?connected_account_id=634f662d-44f3-4b56-b823-a1442d5beb69&symbol=USD/PHP' \
     --header 'Accept: application/json' \
     --header 'X-API-Key: Your_API_Key'

{
  "records": [
    {
      "connected_account_id": "634f662d-44f3-4b56-b823-a1442d5beb69",
      "symbol": "USD/PHP",
      "bid_price": "56.041243",
      "valid_from": "2026-10-06T08:00:00Z",
      "valid_until": "2026-10-06T09:00:00Z",
      "recipient_instrument_type": "bank_account"
    }
  ]
}

Mastercard rates are one-way. Each record has a bid_price and no offer_price. bid_price is the number of units of the second currency in symbol for one unit of the first. Mambu Payments accepts a pair in either order, such as USD/PHP or PHP/USD, and returns the rate that Mastercard publishes for that direction.

Quote to fx_quote

An fx_quote wraps a Mastercard quote. Mambu Payments creates it through the Quotes API and confirms or cancels it through the Quote Confirmation APIs. The request block holds your input. The response block holds the price, amounts, and fees that Mastercard returns.

Endpoint	Mastercard API	Effect
`POST /v1/fx_quotes`	Quotes API	Creates the `fx_quote` as `received`, or as `rejected` if Mastercard returns an error.
`POST /v1/fx_quotes/{id}/lock`	Quote Confirmation API	Moves the `fx_quote` from `received` to `locked`.
`POST /v1/fx_quotes/{id}/cancel`	Quote Confirmation API	Moves the `fx_quote` from `locked` to `canceled`.
`GET /v1/fx_quotes` and `GET /v1/fx_quotes/{id}`	None	Reads stored quotes.

A quote applies to a single payment order. Most quote fields are immutable. To change a currency or an account, create a new fx_quote.

Payment to payment order

A Mastercard payment is a payment_order with type set to mastercard_crossborder_services. The fx_quote_id and fx fields decide which of the three Mastercard payment options you use.

Mastercard payment option	Mambu Payments
Payment with quote	Set `fx_quote_id` and leave the `fx` block empty. The `fx_quote` must be `locked`.
Payment with carded rate	Set `fx_quote_id` to an `fx_quote` with `type` set to `carded_rate`. Several payment orders can use it until it expires.
Payment without quote or carded rate	Leave `fx_quote_id` empty and fill the `fx` block. Mastercard applies the rate that is valid when you submit the payment order.

When you pass fx_quote_id, the payment order takes its amounts and accounts from the quote. You can't set the same field on both the fx_quote and the payment_order.
In the fx block, list the sender currency first in symbol. Set currency to the currency whose amount you fix. The sender currency makes a forward payment. The recipient currency makes a reverse payment. For a forward payment, set fee_option to included or excluded.
Mambu Payments updates the payment_order status as Mastercard reports progress. Mastercard reports a status and, for pending payments, a stage.