Verify DCC eligibility

Browse API reference

POST/fx-ratesgetFxRates

Important: There are restrictions on which merchants can use this method. For more information, go to Dynamic Currency Conversion.

Use this method to check if a card is eligible for Dynamic Currency Conversion (DCC) and to retrieve the conversion rate for a transaction amount. DCC provides a customer with the option to use their card's currency instead of the merchant's currency, for example, in Ireland, an American customer can pay in US dollars instead of Euros.

The request includes the following:

Payment method - Card information, a secure token, or digital wallet.
Transaction information - Amount and currency of the transaction in the merchant's currency.

If the card is eligible for DCC, our gateway returns the transaction amount in the card's currency and a dccOffer object that contains information about the conversion rate. The dccOffer object contains the following fields that you need when you run a sale or unreferenced refund with DCC:

fxAmount
fxCurrency
fxRate
markup
accepted
offerReference

Request body

application/json · required

Field Edit request inputs →

baseAmountintegerint64required
Total amount of the transaction in the merchant’s currency. The value is in the currency’s lowest denomination, for example, cents.
baseCurrencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
channelstringrequired
Channel that the merchant used to receive payment details for the transaction.poswebmoto
operatorstring
Operator who ran the transaction.1–50 chars
paymentMethodobjectrequired
Polymorphic object that contains payment details. The value of the type parameter determines which variant you should use: card Payment card details secureToken Secure token details digitalWallet Digital wallet details
- cardobject
  Object that contains information about the customer’s payment card.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardDetailsobjectrequired
    Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: raw Unencrypted payment data directly from the device. icc Payment data that the device captured from the chip. keyed Payment data that the merchant entered manually. swiped Payment data that the device captured from the magnetic strip.+132 more fields at deeper levels — see the full spec
  - typestringrequired
    Method that the terminal used to take the payment.card
- secureTokenobject
  Object that contains information about the secure token that represents the customer’s payment details.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only if the secure token represents bank account details.checkingsavings
  - secCodestring
    Indicates how the customer authorized the ACH transaction. Send one of the following values: web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction. Note: This field is mandatory when the secure token represents ACH bank account details.webtelccdppd
  - tokenstringrequired
    Unique token that the gateway assigned to the payment details.12–19 chars
  - typestringrequired
    Method that the terminal used to take the payment.secureToken
- digitalWalletobject
  Object that contains information about the payment details in the customer’s digital wallet.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardholderNamestring
    Cardholder’s name.0–50 chars
  - encryptedDatastringrequired
    Encrypted data of the digital wallet.128–20480 chars
  - serviceProviderstringrequired
    Provider of the digital wallet. Send one of the following values: apple For more information about how to integrate with Apple Pay, go to Apple Pay®. google For more information about how to integrate with google Pay, go to Google Pay®.applegoogle
  - typestringrequired
    Method that the terminal used to take the payment.digitalWallet
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars

Responses

Successful request. Returns the currency conversion rate for the transaction.

200 OK · application/json

{
  "baseAmount": 10000,
  "baseCurrency": "EUR",
  "cardInfo": {
    "cardNumber": "453985******7062",
    "type": "MASTERCARD"
  },
  "dccOffer": {
    "fxAmount": 16125,
    "fxCurrency": "JPY",
    "fxCurrencyCode": "392",
    "fxCurrencyExponent": 0,
    "fxRate": 161.2542,
    "markup": 3,
    "offerReference": "3396977e-40b9-4b26-8a3f-c25bc1280ee2",
    "provider": "DCC Provider Inc.",
    "source": "European Central Bank"
  },
  "inquiryResult": {
    "dccOffered": true
  },
  "operator": "Jane",
  "processingTerminalId": "1234001"
}

Response schema · 31 fields

baseAmountintegerint64required
Total amount of the transaction in the local currency. The value is in the currency’s lowest denomination, for example, cents.
baseCurrencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
cardInfoobjectrequired
Object that contains information about the card.
- cardNumberstringrequired
  Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 548010******5929.12–19 chars
- countrystringiso-3166-1
  Country of the issuing bank. The value for the country follows the ISO-3166-1 standard.
- currencystring
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- debitboolean
  Indicates if the card is a debit card.
- healthcareboolean
  Indicates if the card is linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). The value is one of the following: true Card is linked to an FSA or an HSA. false Card isn't linked to an FSA or an HSA.
- surchargingobject
  Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions.
  - allowedbooleanrequired
    Indicates if the merchant can add a surcharge when the customer uses this card.
  - amountintegerint64
    Surcharge amount to add to the transaction. Note: Our gateway returns the surcharge amount only if you include a transaction amount in the request.
  - disclosurestring
    Statement that informs the customer about the surcharge fee.
  - percentagenumberdouble
    Surcharge rate that the merchant configures on their account.≤ 100
- typestringrequired
  Card brand of the card, for example, Visa.
dccOfferobject
Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to Dynamic Currency Conversion.
- acceptedboolean
  Indicates if the cardholder accepted DCC offer.
- fxAmountintegerint64required
  Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents.
- fxCurrencystringrequired
  Currency of the transaction in the card’s currency. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- fxCurrencyCodestring
  Three-digit currency code for the card. This code follows the ISO 4217 standard.3–3 chars
- fxCurrencyExponentintegerint32
  Number of decimal places between the smallest currency unit and a whole currency unit. For example, for GBP, the smallest currency unit is 1p and it is equal to £0.01. If you use GBP, the value for fxCurrencyExponent is 2.
- fxRatenumberdoublerequired
  Foreign exchange rate for the card's currency.
- markupnumberdoublerequired
  Markup percentage rate that the DCC provider applies to the foreign exchange rate.
- markupTextstring
  Supporting text for the markup rate.
- offerReferencestring
  Unique identifier of the DCC offer.
- providerstring
  Name of the DCC provider.
- sourcestring
  Source that the DCC provider used to get the foreign exchange rates.
inquiryResultobjectrequired
Object that indicates if the customer's card is eligible for Dynamic Currency Conversion (DCC).
- causeOfRejectionstring
  Explains why the DCC service did not offer a currency conversion rate to the customer.
- dccOfferedbooleanrequired
  Indicates if the card is eligible for Dynamic Currency Conversion (DCC).
operatorstring
Operator who ran the transaction.0–50 chars
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

check-dcc-eligibility

Verify DCC eligibility

Browse API reference

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer