# Carded Rate API (Compliant with Payment Services Directive for EU customers)
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-carded-rate-api/index.md
Carded Rate is offered, **for configured service corridors** , as an opt-in functionality to obtain the FX rates for the currency pairs that you, as the Customer support, for a valid period of time.
Please see [Payment with Carded Rate](https://developer.mastercard.com/cross-border-services/documentation/use-cases/payment-with-carded-rate/index.md) for more information on usage of the carded rates.
The two options available to obtain the carded rates are as follows:
1. FX Rate Pull API: This is a Pull API that you may send a request to obtain Carded Rate, and
2. FX Rate Push Notification: This is a push notification where Mastercard would send the notifications as and when the rates are available.
This page describes the details on both the options available for obtaining the carded rates.
Note: Prior to using these API/ Notification, you must opt-in for this service by contacting your Mastercard representative.
## Environment Domains {#environment-domains}
### FX Rate Pull {#fx-rate-pull}
* Sandbox
* MTF
* Production
```Sandbox
Sandbox testing is unavailable for Carded Rate APIs.
```
```MTF
https://mtf.api.xbs.mastercard.eu/send/v1/partners/{partner-id}/crossborder/rates
```
```Production
https://api.xbs.mastercard.eu/send/v1/partners/{partner-id}/crossborder/rates
```
### FX Rate Push {#fx-rate-push}
* This is a push Notification and webhook endpoint will need to be provided by you for Mastercard to send the FX Rates.
Note:
* Contact your mastercard representative for mTLS push notification mastercard public certificate. This certificate needs to be trusted by the receiving application. Also, please share the server certificate chain for validation (via KMP portal), if those are accepted on mastercard infrastructure.
* Once done, FX rates can be sent by Mastercard to the other party.
* During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production).
## API {#api}
[**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-eu-swagger.yaml)
Alternatively, here is a tabular view of the request/ response parameter:
[Carded_Rate_Specifications.pdf](https://static.developer.mastercard.com/content/cross-border-services/uploads/Carded_Rate_Specifications.pdf) (264KB)
### FX Rate Pull {#fx-rate-pull-1}
[**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-eu-swagger.yaml)
The FX Rate Pull API will require you to create a scheduler, **for configured service corridors**, that will call this API based on the refresh times per currency pair provided by Cross-Border Services.
API Reference: `GET /send/v1/partners/{partner-id}/crossborder/rates`
* **Formats supported** : XML/ JSON
* **HTTP Version**: 1.0/ 1.1
* **Required HTTP header parameters** :
content-type : Format of the inbound content being submitted. example: application/json
content-length: Length of the inbound content body in octets.
Accept: Format of the expected response must be provided in this header field. Example - application/json
### FX Rate Push {#fx-rate-push}
[**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-webhook-swagger.yaml)
The FX Rate Push, once coded to, will provide the ability for Cross-Border Services to push all FX rates, **for configured service corridors**, to the Customer that are refreshing at the time of the push without any requests by the Customer. Depending on the number and FX refresh schedules of the rates, the Customer should expect to receive multiple pushes a day.
API Reference: `POST /callbackpath`
Tip: It is a Cross-Border Services best practice for any customer who codes to the Push API to also code to the Pull API so that the pull API can be used as a backup in case FX rates are not received for any reason.
* **Formats supported** : JSON
* **HTTP Version**: 1.0/ 1.1
* **Required HTTP header parameters** :
content-type : Format of the inbound content being submitted. example: application/json
content-length: Length of the inbound content body in octets.
## API Convention {#api-convention}
Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines.
## Payload Encryption {#payload-encryption}
All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by Mastercard.
For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md)
## Sandbox Testing {#sandbox-testing}
Sandbox Testing is unavailable for Carded Rate APIs.
## Sample Requests {#sample-requests}
### FX Rate Pull {#fx-rate-pull}
No Request body
### FX Rate Push {#fx-rate-push}
* XML
* JSON
```XML
BANK
BEL_MCSXB1HS5fd
single
MXN
INR
2020-04-02T15:07:00Z
2020-04-02T16:07:00Z
3ciq8g5gkkike1a5hkhi3hgvkd
3.239881
EMEA
BANK
BEL_MCSXB1HS5fd
single
MXN
THB
2020-04-02T15:07:00Z
2020-04-02T16:07:00Z
3t1ia5kupk0ud1sl0yow12x9pq
1.395389
EMEA
```
```JSON
{
"rates": [
{
"type": "single",
"use": "CMSP",
"from_currency_code": "MXN",
"to_currency_code": "INR",
"valid_from": "2020-04-02T15:07:00Z",
"valid_to": "2020-04-02T16:07:00Z",
"tier_identifier_rate": "",
"account_type": "BANK",
"partner_id": "BEL_MCSXB1HS5fd",
"tiers": [
{
"from_amount": "",
"rate_id": "3ciq8g5gkkike1a5hkhi3hgvkd",
"ask_rate": "",
"mid_rate": "",
"bid_rate": "3.239881"
}
],
"card_segment_name": "EMEA"
},
{
"type": "single",
"use": "CMSP",
"from_currency_code": "MXN",
"to_currency_code": "THB",
"valid_from": "2020-04-02T15:07:00Z",
"valid_to": "2020-04-02T16:07:00Z",
"tier_identifier_rate": "",
"account_type": "BANK",
"partner_id": "BEL_MCSXB1HS5fd",
"tiers": [
{
"from_amount": "",
"rate_id": "3t1ia5kupk0ud1sl0yow12x9pq",
"ask_rate": "",
"mid_rate": "",
"bid_rate": "1.395389"
}
],
"card_segment_name": "EMEA"
}
],
"event_ref": "ref_u0lVpKKZ0Evx0UExr05VuD8frOFw",
"event_type": "CARDFX_PUB"
}
```
## Sample Responses {#sample-responses}
### FX Rate Pull {#fx-rate-pull-1}
* XML
* JSON
```XML
BANK
BEL_MCSXB1HS5fd
single
MXN
INR
2020-04-02T15:07:00Z
2020-04-02T16:07:00Z
3ciq8g5gkkike1a5hkhi3hgvkd
3.239881
EMEA
```
```JSON
{
"rates": {
"rate": [
{
"type": "single",
"use": "CMSP",
"from_currency_code": "MXN",
"to_currency_code": "INR",
"valid_from": "2020-04-02T15:07:00Z",
"valid_to": "2020-04-02T16:07:00Z",
"tier_identifier_rate": "",
"account_type": "BANK",
"partner_id": "BEL_MCSXB1HS5fd",
"tiers": {
"tier": [
{
"from_amount": "",
"rate_id": "3ciq8g5gkkike1a5hkhi3hgvkd",
"ask_rate": "",
"mid_rate": "",
"bid_rate": "3.239881"
}
]
},
"card_segment_name": "EMEA"
},
{
"type": "single",
"use": "CMSP",
"from_currency_code": "MXN",
"to_currency_code": "THB",
"valid_from": "2020-04-02T15:07:00Z",
"valid_to": "2020-04-02T16:07:00Z",
"tier_identifier_rate": "",
"account_type": "BANK",
"partner_id": "BEL_MCSXB1HS5fd",
"tiers": {
"tier": [
{
"from_amount": "",
"rate_id": "3t1ia5kupk0ud1sl0yow12x9pq",
"ask_rate": "",
"mid_rate": "",
"bid_rate": "1.395389"
}
],
"card_segment_name": "EMEA"
}
}
],
"event_ref": "ref_u0lVpKKZ0Evx0UExr05VuD8frOFw",
"event_type": "CARDFX_PUB"
}
}
```
### FX Rate Push {#fx-rate-push-1}
No Response body
## Error Codes {#error-codes}
Please refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md).
For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md).
## Push Notification Configuration Details {#push-notification-configuration-details}
For more information on configuring a push notification, please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/push-notifications-details/index.md).