Integrate

DocsCurrent

Last updated: May 23rd, 2:48am

To integrate FXaaS:

Obtain an exchange rate quote: Use the currency exchange API to retrieve and lock an exchange rate for payment processing.

Create order: Include FXaaS parameters in your payment method’s create order calls. This enables support for local currency payments through the Orders v2 API.

Capture payment: Include FXaaS parameters in the capture order calls.

Handle market moving events.

Test the FXaaS set-up.

Before you integrate

Verify your eligibility to integrate FXaaS.
Review your FXaaS contract. As part of FXaaS onboarding, PayPal enables FXaaS for your account based on the contract. The contract specifies the rate expiration interval, PayPal's rate refresh time, PayPal FX fees, and other relevant terms. For more information about fees, see the merchant fees page.
Complete all mandatory steps to get started. Use the retrieved sandbox app credentials (client ID and Secret) in your code to generate an access token. The access token is a server-side token that helps with app authentication when the app accesses PayPal API resources.

End-to-end workflow

Get exchange rate quote

Use the Currency exchange API to retrieve and lock an exchange rate.

Important: Your FXaaS contract specifies the expiration time, which determines how long the locked exchange rate remains valid after PayPal updates (refreshes) its exchange rate. At the time of payment processing, PayPal applies the locked exchange rate if it is still within the validity period. If the rate is no longer valid, PayPal processes the transaction using the prevailing exchange rate at the time of processing.

To get an exchange rate quote, you can do one of the following:

Place multiple API calls to fetch product-specific quotes.

Place one API call to retrieve the exchange rate between a currency pair, which you can cache and apply to multiple products.

Get a product-specific quote

To retrieve a product-specific quote, in server-side code, call the Quote exchange rates API (/v2/pricing/quote-exchange-rates) and include the following parameters in the request payload:

base_currency: Primary holding currency of the account in which PayPal settles money.

quote_currency: Buyer’s local currency.

base_amount (optional): Product price in base currency. If this parameter is omitted, PayPal returns only the exchange rate and does not calculate the quote_amount.

markup_percent (optional): Markup percentage added to the base exchange rate to include a conversion fee or account for margin adjustments.

Response: When the quote is retrieved successfully, the server-side code receives a 200 OK response. The response payload includes the following parameters:

fx_id: Unique identifier that associates a quoted FX rate with an order.

quote_amount.value: Product price in the buyer's local currency.

exchange_rate: Conversion rate between the base and quote currencies.

expiry_time: UTC timestamp that specifies the validity period of the quoted FX rate.

rate_refresh_time: Fixed daily UTC timestamp that specifies when PayPal updates its exchange rates.

Important:

The retrieved exchange rates are valid for settlement until rate_refresh_time. expiry_time allows for an additional grace period to guarantee the rate even after rate_refresh_time.

The time difference between rate_refresh_time and expiry_time (cut-off period) is set to three hours as a standard. When finalizing the FXaaS contract, you can request a different cut-off period. The request is reviewed and processed on a case-by-case basis.

Request
Response

1curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/pricing/quote-exchange-rates' \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer ACCESS-TOKEN' \
4  -d '{
5    "quote_items": [
6      {
7        "base_currency": "USD",
8        "quote_currency": "GBP",
9        "base_amount": 16.80,
10        "markup_percent": 1
11      }
12    ]
13  }'

Get exchange rate only

To retrieve the exchange rate between two currencies, in server-side code, call the Quote exchange rates API (/v2/pricing/quote-exchange-rates) and include only the following parameters in the request payload:

base_currency: Primary holding currency of the account in which PayPal settles money.

quote_currency: Buyer’s local currency.

Response: When the quote is retrieved successfully, the server-side code receives a 200 OK response. The response payload includes the following parameters:

exchange_rate: Conversion rate between the base and quote currencies.

fx_id: Unique identifier that links a quoted FX rate to an order.

expiry_time: UTC timestamp that defines how long the quoted FX rate remains valid.

rate_refresh_time: Fixed daily UTC timestamp that defines when PayPal refreshes its exchange rates.

Important: The retrieved exchange rate is valid for settlement until rate_refresh_time. expiry_time allows for an additional grace period to guarantee the rate even after rate_refresh_time. The time difference between rate_refresh_time and expiry_time (cut-off period) is set to three hours as a standard. When finalizing the FXaaS contract, you can request a different cut-off period. The request is reviewed and processed on a case-by-case basis.

Request
Response

1curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/pricing/quote-exchange-rates' \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer ACCESS-TOKEN' \
4  -d '{
5    "quote_items": [
6      {
7        "base_currency": "USD",
8        "quote_currency": "GBP"
9      }
10    ]
11  }'

Proceed as follows

Save exchange_rate_quotes[].fx_id and exchange_rate_quotes[].quote_amount{}.

If you only retrieved the exchange rate, use exchange_rate_quotes[].quote_amount.value to calculate product prices in the local currency.

After authenticating the buyer, show the product prices in the local currency.

Upon checkout, call the Orders v2 API using the stored fx_id as payment_instruction.payee_receivable_fx_rate_id.

Use fx_id and create order

When a buyer completes a purchase, use the Orders v2 API to initiate payment processing and create an order in the PayPal system. In server-side code, call the Create order API (v2/checkout/orders) and include the following parameter in the request payload to associate the order with the locked exchange rate:

payment_instruction.payee_receivable_fx_rate_id: Set the value to the fx_id obtained as part of the exchange rate quote.

Important: The locked exchange rate is valid for settlement until rate_refresh_time. expiry_time allows for an additional grace period to guarantee the rate even after rate_refresh_time. If the Create order request does not include the payment_instruction.payee_receivable_fx_rate_id parameter, during payment capture, PayPal does not consider the additional expiry_time. PayPal validates whether the rate_refresh_time window is valid. If not, PayPal processes the transaction using the prevailing exchange rate at the time of the transaction.

Response: When the order is created successfully, the server-side code receives a 200 OK response. The response payload includes the following parameters:

payee_receivable_fx_rate_id: Identifier for the quoted FX rate that PayPal associates with the order and applies during capture if the exchange rate is still valid.

id: Unique identifier that PayPal assigns to the created order.

links[].href (with rel: approve): URL for payment approval.

Request
Response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer ACCESS-TOKEN" \
4-d '{
5  "intent": "CAPTURE",
6  "purchase_units": [
7    {
8      "amount": {
9        "currency_code": "GBP",
10        "value": "13.60"
11      },
12      "payment_instruction": {
13        "payee_receivable_fx_rate_id": "MTFFQy05RjBFLTEyOTlDQTgwLTg3MzMtMzk0ODIwRUEwMTc4"
14      }
15    }
16  ]
17}'

Proceed as follows

Save the id returned in the response. This identifier is required to capture the payment after buyer approval.

Send the buyer to the approval URL to review and approve the payment.

After the buyer approves the payment, call the Orders v2 > Capture payment for an order API.

Capture payment

When a buyer approves the payment for the purchase, use the Orders v2 API to finalize the payment and move money from the buyer to PayPal. In server-side code, call the Capture payment for an order API (v2/checkout/orders/:id/capture). In the request payload, include the id retrieved as part of the create order response as a path parameter. PayPal identifies the order and its associated fx_id using the path parameter. PayPal determines the locked exchange rate based on the fx_id. If the exchange rate is valid, PayPal captures money from the buyer account using the locked exchange rate.

Important:

Capture the completed payment within the FX quote validity window (expiry_time) to ensure the locked rate is applied.

If the Create order request does not include the payment_instruction.payee_receivable_fx_rate_id parameter, during payment capture, PayPal does not consider the additional expiry_time. PayPal validates whether the rate_refresh_time window is valid. If not, PayPal processes the transaction using the prevailing exchange rate at the time of the transaction.

PayPal transaction fee is charged in the buyer (payment) currency.

Response: When the order is created successfully, the server-side code receives a 200 OK response. The response payload includes the following parameters:

payments.captures[].seller_receivable_breakdown.receivable_amount: Final amount the merchant receives in their base currency.

payments.captures[].seller_receivable_breakdown.exchange_rate: Exchange rate PayPal applies to convert the quote currency to your base currency.

payments.captures[].seller_receivable_breakdown.paypal_fee: PayPal’s transaction fee specified in terms of the quote currency.

payments.captures[].id: Unique identifier for the captured payment.

Request
Response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer ACCESS-TOKEN" \
4  -H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"

Proceed as follows

Save payments.captures[].id and payments.captures[].seller_receivable_breakdown.receivable_amount for back-end reporting and reconciliation.

[Special case] Handle market-moving events (Force majeure)

Market-moving events, such as natural disasters or political unrest, can lead to high volatility in currency markets and the FXaaS exchange rate lock guarantee may be suspended. In response to these events, PayPal updates the exchange rates and issues a new fx_id outside the regular refresh cycle.

If such an event occurs after you retrieve an exchange rate quote and before you create an order, the Create an order API call returns a 422 UNPROCESSABLE_ENTITY response to the server-side code with the following response parameters:

issue: Value set to FX_RATE_CHANGE_DUE_TO_MARKET_EVENT indicating that a market-moving event has caused the locked exchange rate to change.

links[].href with rel: new_fx_id: URL to fetch the updated exchange rate quote.

Request
Response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer ACCESS-TOKEN" \
4  -d '{
5    "intent": "CAPTURE",
6    "purchase_units": [
7      {
8        "amount": {
9          "currency_code": "GBP",
10          "value": "13.60"
11        },
12        "payment_instruction": {
13          "payee_receivable_fx_rate_id": "MTFFQy05RjBFLTEyOTlDQTgwLTg3MzMtMzk0ODIwRUEwMTc4"
14        }
15      }
16    ]
17  }'

Proceed as follows

To retrieve the new exchange rate quote, place a GET call to the links[].href URL (the URL with links[].rel set as new_fx_id).

Display the new product prices to buyers.

Upon checkout, call the Orders v2 API using the new fx_id as payment_instruction.payee_receivable_fx_rate_id.

Important: After the API call that returns the HTTP 422 response code, any further Create an order API call with the old fx_id returns a 200 OK response with payee_receivable_fx_rate_id set to the new fx_id. This indicates that during payment capture, PayPal processes payments based on the new updated exchange rate (associated with the new fx_id).

Test FXaaS set-up

Before going live, use your sandbox environment to thoroughly test FXaaS integration. This includes verifying the exchange rates retrieval logic, order creation logic, payment capture logic, and error handling.

After testing, Move your app to production.