# Payment with Carded Rate source: https://developer.mastercard.com/cross-border-services/documentation/use-cases/payment-with-carded-rate/index.md Carded rates are pre-published Mastercard FX Rates that you can reuse across multiple Payments while they're valid. Unlike a quote, which is for one Payment only, a carded rate can support many Payments as long as its rate ID is still valid. Carded rates are useful when you want to display rates to Senders in an app or website before they start a Payment. For example, you might show today's exchange rates and let the Sender build a Payment based on what they see. Each carded rate includes the Mastercard FX Rate, a unique rate ID, effective time and validity window. Carded rates can be delivered in one of two ways: * **API**: FX Rate Pull (you request rates) or FX Rate Push (Mastercard notifies you when rates are available) * **File**: Mastercard delivers rates by file transfer The carded rate service is opt-in. Ask your Mastercard Representative for more information about opting in and choosing the delivery method that works for you. Carded rates are mainly used in the Customer Managed Sender Pricing (CMSP) model, where you retrieve Mastercard FX Rates, apply your own markup and present pricing to the Sender. Learn more about the [pricing model](https://developer.mastercard.com/cross-border-services/documentation/use-cases/pricing-model/index.md). Note: Unlike a single quote, a carded rate once obtained can be used across multiple Payments as long as the rate ID is valid. This page covers three flows: * Forward Payment with fees included * Forward Payment with fees not included * Reverse Payment ## 1. Forward Payment (fees included) {#1-forward-payment-fees-included} The Sender specifies the amount they want to send, including any fees. The API calculates how much the Recipient will receive using the carded rate. ### Preconditions {#preconditions} * You have opted in to the carded rate service. * You have retrieved a valid carded rate ID for the currency pair via FX Rate Pull, FX Rate Push or file delivery. * The carded rate is still within its validity window when you submit the Payment. ### Example sequence {#example-sequence} Diagram send-fwd-with-carded-rate-fees-sequence Note: The example uses FX Rate Pull. You can also obtain a carded rate using FX Rate Push or file delivery. ### Understanding this flow {#understanding-this-flow} **FX Rate Pull / FX Rate Push API** (steps 1-2): Retrieves pre-published carded rates for the currency pairs you support. Each response includes a unique rate ID, the Mastercard FX Rate, effective time and validity window. Unlike a quote, which is generated for a single Payment, a carded rate can be reused across multiple Payments while its rate ID is valid. API Reference: `GET /send/v1/partners/{partner-id}/crossborder/rates` API Reference: `POST /carded-rate-callbackpath` **Payment API** (step 6): Submits the Payment. Include the carded rate ID in the request so Mastercard applies the correct rate. Mastercard validates the rate ID is still within its validity window before processing. API Reference: `GET /send/v1/partners/{partner-id}/crossborder/payment` ## 2. Forward Payment (fees not included) {#2-forward-payment-fees-not-included} The Sender specifies how much they want to send. The API calculates two things using the carded rate: * How much the Recipient will receive (Sender Amount × carded rate) * How much the Sender is charged in total (Sender Amount + fees) ### Preconditions {#preconditions-1} * You have opted in to the carded rate service. * You have retrieved a valid carded rate ID before submitting the Payment. ### Example sequence {#example-sequence-1} Diagram send-fwd-with-carded-rate-wo-fees-sequence ### Understanding this flow {#understanding-this-flow-1} The API sequence is the same as the fees-included flow - FX Rate Pull/Push followed by Payment API - but the calculation differs: * Fees are added on top of the Sender Amount rather than deducted from it. * The full Sender Amount is converted and delivered to the Recipient, and the Sender is charged the Sender Amount plus fees. API Reference: `GET /send/v1/partners/{partner-id}/crossborder/rates` API Reference: `POST /carded-rate-callbackpath` API Reference: `GET /send/v1/partners/{partner-id}/crossborder/payment` ## 3. Reverse Payment {#3-reverse-payment} The Sender specifies how much the Recipient should receive rather than how much to send. The API calculates the total amount charged to the Sender using the carded rate. Use this flow when the Recipient needs a specific amount - for example, paying a bill for exactly 5,000 PHP. ### Preconditions {#preconditions-2} * You have opted in to the carded rate service. * You have retrieved a valid carded rate ID before submitting the Payment. ### Example sequence {#example-sequence-2} Diagram send-rvs-with-carded-rate-sequence ### Understanding this flow {#understanding-this-flow-2} The API sequence is the same as the forward flows - FX Rate Pull/Push followed by Payment API - but the direction of calculation is reversed: * The Sender specifies the amount the Recipient should receive. * The API calculates the required Sender Amount by dividing the Recipient Credited Amount by the carded rate and adding fees. API Reference: `GET /send/v1/partners/{partner-id}/crossborder/rates` API Reference: `POST /carded-rate-callbackpath` API Reference: `GET /send/v1/partners/{partner-id}/crossborder/payment` ## Check your account balance {#check-your-account-balance} If you use the Prefunding Settlement Model or Collateral Settlement Model, you can use the Balance API to check your settlement account balances. You can retrieve balances for all your accounts, or for a specific account using its account ID. API Reference: `GET /send/partners/{partner_id}/crossborder/accounts` API Reference: `GET /send/partners/{partner_id}/crossborder/accounts/{account_id}` ## Related APIs {#related-apis} The following APIs are available for all carded rate flows: * [Retrieve Payment API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/transaction-apis/retrieve-payment-api/index.md): After submission, use this to check the current status of the Payment. API Reference: `GET /send/v1/partners/{partner-id}/crossborder/{payment-id}` * [Status Change API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/transaction-apis/status-change-api/index.md): Checks the status of the Payment. Opt in to receive near real-time status updates via push notification when the Payment's status changes. API Reference: `POST /send/partners/{partner_id}/crossborder/webhooks` * [Cancel Payment API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/transaction-apis/cancel-payment-api/index.md): Cancels a Payment that's still in PENDING status. API Reference: `GET /send/v1/partners/{partner-id}/crossborder/{payment-id}/cancel` ## Error resolution {#error-resolution} For details on errors returned by the service, see the [Response Codes and Error Codes](https://developer.mastercard.com/cross-border-services/documentation/code-and-formats/index.md) section.