# Payment with Quote
source: https://developer.mastercard.com/cross-border-services/documentation/use-cases/payment-with-quote/index.md

A quote locks the Mastercard FX Rate and amounts for a single Payment before you submit it. When you submit the Payment, it uses the amounts and rate from the quote, so the Sender knows exactly what they'll pay and what the Recipient will receive.

Use a quote when the Sender needs to see the exact cost and amount the Recipient will receive before confirming the Payment.

The pricing model that you follow will help determine the type of the API call that you will use, the content you will send inside the API call, and the timing of when FX rates are retrieved. Learn more about the [pricing model](https://developer.mastercard.com/cross-border-services/documentation/use-cases/pricing-model/index.md).
Note: A quote is valid for one Payment only.

This page covers four flows:

* Forward Payment with fees included
* Forward Payment with fees not included
* Reverse Payment
* Payment with quote confirmation

## 1. Forward Payment (fees included) {#1-forward-payment-fees-included}

The Sender specifies how much they want to send, including any fees. The API calculates how much the Recipient will receive, in the Recipient Currency.

### Preconditions {#preconditions}

* The corridor from the Sender Currency to the Recipient Currency is supported under your program configuration.

### Example sequence: Customer Managed Sender Pricing (CMSP) {#example-sequence-customer-managed-sender-pricing-cmsp}

Diagram send-fwd-with-quote-fees-cmsp-sequence

### Example sequence: Mastercard Managed Sender Pricing (MMSP) {#example-sequence-mastercard-managed-sender-pricing-mmsp}

In MMSP, Mastercard applies your configured markup and calculates the quote on your behalf.
Diagram send-fwd-with-quote-fees-mmsp-sequence

### Understanding this flow {#understanding-this-flow}

**Quote API** (steps 2-3 in MMSP, steps 4-5 in CMSP): Calculates the exact amount the Sender pays and the Recipient receives before the Payment is submitted.

* In the CMSP model, you apply your own markup on top of the Mastercard FX Rate.
* In MMSP, Mastercard applies your configured markup.

Either way, the Quote API returns a proposal ID that captures the agreed terms.

The quote gives the Sender upfront visibility of the total cost and the exact amount the Recipient will receive. It protects both parties from FX rate movement between the time the Sender approves the Payment and the time it is processed.

API Reference: `GET /send/v1/partners/{partner-id}/crossborder/quotes`

**Payment API** (steps 6-8): Submits the Payment using the proposal ID. The Payment inherits everything from the quote (amounts, currencies, Mastercard FX Rate), ensuring the Sender's approved terms are honored.

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:

* How much the Recipient will receive (Sender Amount × FX rate)
* How much the Sender is charged in total (Sender Amount + fees)

Fees are added on top of the Sender Amount, so the full Sender Amount is converted and delivered to the Recipient. Use this flow when the Sender wants to guarantee a specific amount reaches the Recipient.

### Preconditions {#preconditions-1}

* The corridor from the Sender Currency to the Recipient Currency is supported under your program configuration.

### Example sequence: Customer Managed Sender Pricing (CMSP) {#example-sequence-customer-managed-sender-pricing-cmsp-1}

Diagram send-fwd-with-quote-wo-fees-cmsp-sequence

### Example sequence: Mastercard Managed Sender Pricing (MMSP) {#example-sequence-mastercard-managed-sender-pricing-mmsp-1}

Diagram send-fwd-with-quote-wo-fees-mmsp-sequence

### Understanding this flow {#understanding-this-flow-1}

The API sequence is the same as the fees-included flow - Quote API followed by Payment API - but the calculation differs:

* The Quote API returns the total amount charged to the Sender (Sender Amount + fees) and the amount delivered to the Recipient (Sender Amount × Mastercard FX Rate).


API Reference: `GET /send/v1/partners/{partner-id}/crossborder/quotes`

* Fees are added on top of the Sender Amount rather than deducted from it, so the full Sender Amount is converted and delivered.

## 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.

Use this flow when the Recipient needs a specific amount, for example paying a bill for exactly 5,000 PHP.

### Preconditions {#preconditions-2}

* The corridor from the Sender Currency to the Recipient Currency is supported under your program configuration.

### Example sequence: Customer Managed Sender Pricing (CMSP) {#example-sequence-customer-managed-sender-pricing-cmsp-2}

Diagram send-rvs-with-quote-cmsp-sequence

### Example sequence: Mastercard Managed Sender Pricing (MMSP) {#example-sequence-mastercard-managed-sender-pricing-mmsp-2}

Diagram send-rvs-with-quote-mmsp-sequence

### Understanding this flow {#understanding-this-flow-2}

The API sequence is the same as the forward flows - Quote API followed by Payment API - but the direction of calculation is reversed:

* The Sender specifies the amount the Recipient should receive (for example, 5,000 PHP).
* The Quote API calculates the required Sender Amount by dividing the Recipient Credited Amount by the Mastercard FX Rate and adding fees.


API Reference: `GET /send/v1/partners/{partner-id}/crossborder/quotes`

* The Payment API submits the Payment using the proposal ID, so the Recipient receives the exact quoted amount.


API Reference: `GET /send/v1/partners/{partner-id}/crossborder/payment`

## 4. Payment with quote confirmation {#4-payment-with-quote-confirmation}

If you opt in to the Quote Confirmation Service, the Quote API response includes a `confirmationExpiryTime`. You must confirm the quote within that window before submitting the Payment.

Use this flow when your program requires explicit quote confirmation before Payment submission, or when you want a longer window between calculating the quote and submitting the Payment.

### Preconditions {#preconditions-3}

* You have opted in to the Quote Confirmation Service.
* The confirmation is submitted within the `confirmationExpiryTime` returned in the quote response.

### Example sequence: confirm quote {#example-sequence-confirm-quote}

Diagram send-confirm-quote-request

### Example sequence: cancel confirmed quote {#example-sequence-cancel-confirmed-quote}

Diagram send-cancel-quote-request Note: If you opt in to the Expired Rate Service, you can confirm the quote after the `confirmationExpiryTime` has passed. Mastercard returns a new quote in the response, which you then confirm. Up to three attempts are permitted before the confirmation is declined.

### Understanding this flow {#understanding-this-flow-3}

**Quote API** (step 4): Calculates the Mastercard FX Rate and amounts, same as other quote-based flows. Also returns a `confirmationExpiryTime` that tells you how long you have to confirm.

API Reference: `GET /send/v1/partners/{partner-id}/crossborder/quotes`

**Quote Confirmation API** (step 6): Confirms your acceptance of the quoted terms before the `confirmationExpiryTime`. This is a binding commitment and reserves the funds required to settle the Payment.

API Reference: `GET /send/partners/{partner_id}/crossborder/quotes/confirmations`

**Payment API** (step 8): Submits the Payment using the confirmed proposal ID.

API Reference: `GET /send/v1/partners/{partner-id}/crossborder/payment`

**Cancel Confirmed Quote API** (step 8 in the cancel flow): Cancels a confirmed quote if you decide not to proceed. This releases the quote and any reserved funds.

API Reference: `GET /send/partners/{partner_id}/crossborder/quotes/cancellations`

## Related APIs {#related-apis}

The following APIs are available for all quote-based 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.
* [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.
* [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.

## 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.