Payments in other currencies

Tpay allows you to present and settle payments in currencies other than PLN. Currently, this is available only for card payments – other payment methods do not yet support currencies.

Before you start

Make sure that:

• You have API authorization data.
• You handle transaction notifications.
• Card payments are enabled.

Cards – payments settled in local currency

For card payments, we distinguish several currency-related solutions. They differ in who decides the currency the card is charged in, and in which currency the merchant receives the funds.

Payment with any card in any currency (conversion by the card issuer)

The payer can pay by card in any currency, regardless of the currency in which the payment was presented. This is a standard card payment mechanism, independent of Tpay and of the acquirer – it applies to every card and every acquirer.

The conversion is performed by the card issuer (the payer's bank), and the amount charged to the payer's card is converted into that card's currency. The merchant always receives the payment in the currency in which the transaction was created.

With this solution, the payer cannot be certain of the exact amount charged to the card – the card issuer sets the conversion rate. However, an approximate amount is easy for the payer to work out based on current exchange rates.

Example

The payment was presented in the amount of 100 PLN, and the payer pays with a card issued in EUR:

• the payer sees the amount due in the gateway: 100 PLN,
• completes the payment for 100 PLN,
• sees in the card statement a payment of 100 PLN, along with the amount actually charged to the card in EUR (e.g. 25 EUR),
• the merchant receives the payment in PLN.

DCC (Dynamic Currency Conversion)

DCC is a service that converts the transaction amount "on the fly" into the payer's card currency, when the payment currency differs from the card's currency. Unlike conversion by the card issuer, the conversion happens already at the payment stage, and the payer can choose the charge currency. With this solution, the payer sees the exact payment amount in their own currency before deciding to pay.

Using DCC does not differ, for the integrator, from a standard card payment – you do not need to change or add anything in your integration. The only difference is visible to the payer: between filling out the card form and the start of payment processing (3DS authentication), they will be shown additional screens on which they choose the charge currency.

Example

The payment was presented in the amount of 100 PLN, and the payer pays with a card issued in EUR:

• the payer sees the amount due in the gateway: 100 PLN,
• after entering the card details, the system checks whether DCC is possible – if so, the payer is presented with a choice of charge currency: 100 PLN or e.g. 25 EUR,
• the payer completes the payment in the chosen currency,
• if they chose 100 PLN – the card statement will show a payment of 100 PLN, along with the amount charged to the card in EUR (e.g. 25 EUR),
• if they chose 25 EUR – the card statement will show a payment of 25 EUR,
• the merchant always receives the payment in the currency in which the transaction was created (in this example, PLN).

Limitations

• DCC only works when paying by card number – in practice, it will not work for most Apple Pay, Google Pay, and Click to Pay payments, which are made using a wallet token.
• DCC is not available for recurring payments.

Cards – payment settled in any currency (multi-currency)

Multi-currency is the ability to present and settle a card transaction in a currency other than PLN – without the need to use conversion by the card issuer or DCC. The merchant receives the funds directly in the currency in which the transaction was created, or another currency agreed with the acquirer.

Examples

The payment was presented in the amount of 100 EUR, and the payer pays with a card issued in EUR:

• the payer sees the amount due in the gateway: 100 EUR,
• completes the payment for 100 EUR,
• sees in the card statement a payment of 100 EUR,
• the merchant receives the payment in EUR.

The payment was presented in the amount of 100 EUR, and the payer pays with a card issued in PLN:

• the payer sees the amount due in the gateway: 100 EUR,
• completes the payment for 100 EUR,
• sees in the card statement a payment of 100 EUR, along with the amount charged to the card in PLN (e.g. 450 PLN – the conversion is performed on the payer's card issuer's side),
• the merchant receives the payment in EUR.

Before you start – requirements

To use multi-currency payments:

• Your MID with Worldline must have currency support activated – report this need to your Tpay account manager during onboarding.
• Tpay will configure the selected transaction currencies on your profile, in line with your arrangements with Worldline.
• A merchant ID configured for currency payments should have only card channels enabled. If another payment method is enabled on such a MID, payments made using that method will – for security reasons – be declined.
• Currency payments – in currencies other than PLN – require a separate Tpay merchant ID for each domain, and for each settlement currency with DCC enabled. In other cases, a single Tpay merchant ID is enough. A solution allowing you to use currencies and PLN under a single Tpay merchant ID is in preparation.

Available transaction currencies

The following transaction currencies are available: EUR, USD, as well as ALL, AMD, AUD, AZN, BAM, BRL, CAD, CHF, CNY, CZK, DKK, GBP, GEL, HUF, INR, ISK, JPY, KZT, MDD, MKD, MXN, NOK, RON, RSD, SEK, SGD, TRY, UAH, ZAR.

If you need to accept payments in a currency that is not on the list above, report this need to your Tpay account manager – extending the list of transaction currencies is possible.

Settlement currencies

Under the agreement with Worldline, the merchant specifies the currencies in which they want to accept payments, and the currencies in which they want to receive payouts. Settlement is possible:

• with conversion – e.g. payments in USD, EUR, and GBP, with payout in one common currency, e.g. EUR,
• without conversion (1:1) – the payout is made in the same currency in which the payment was accepted, e.g. payment in USD → payout in USD.

Available settlement currencies include: EUR, USD, GBP, CHF, DKK, HUF, NOK, SEK.

Creating a transaction in a currency

Create card payments in a currency using the standard transaction creation endpoint, additionally specifying the currency field with a currency code compliant with ISO 4217, and pay.groupId: 103 (the payment group for cards).

To create a card transaction in a currency, send a POST request to the endpoint:

https://api.tpay.com/transactions

Specify the following parameters in the request:

* Fields required.

The basic request body should look like this:

{
  "amount": 100,
  "currency": "EUR",
  "description": "Test card payment in EUR",
  "payer": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "pay": {
    "groupId": 103
  }
}

After sending the request, you will receive a TransactionCreated schema in the response.

The key response parameters are:

Example response:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "title": "TR-CWM-CNYHA6X",
  "posId": "ps_e4dkPVDEm4Jg7267",
  "status": "pending",
  "date": {
    "creation": "2024-06-06 21:31:35",
    "realization": null
  },
  "amount": 100,
  "currency": "EUR",
  "description": "Test card payment in EUR",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-CNYHA6X&uid=01HZQGHZP5P3P7YV8A4BRVDX17"
}

The rest of the process – redirecting the payer, 3D Secure authentication, and handling the notification – works the same way as for a standard card transaction.

Supported payment methods

Payments in any currency can be made using: card, Apple Pay, Google Pay.

Limitations of the current solution

• Currency transactions can currently only be created via the API – the payment link generator does not yet support currencies.
• Transactions in currencies outside the list configured for a given MID will be declined.
• A MID configured for card currencies should have only card channels active – other payment methods on such a MID will be declined.
• Click to Pay payments do not currently support currencies.

Handle notification

We will notify you of the transaction status via transaction posting notifications. The notification includes a currency field with the transaction currency.