Currency Handling

Introduction
(In Development)
Paysafe Embedded Wallets solution supports customers to hold balances in different currencies.
Note! Multiple currency support is contract specific feature. Contact Paysafe for more details.
For holding the balance for each currency, the customer needs to have a dedicated wallet account in the corresponding currency. Each account handles the balance for a specific currency. It is important to take into account the account currency when doing wallet operations.
- Deposit currency and the deposit account currency must be the same
- Withdrawal currency and the withdrawal amount currency be the same
- Transfers currency and the source account currency must be the same
Currency Setup During Onboarding
At least one accounts
parameter specifying account currency is required during customer onboarding.
For enabling more than one currency, the required currencies need to be passed in the list of desired accounts during onboarding.
Requesting virtual IBAN is allowed only for specific currencies depending on the customer's country.
Contact Paysafe for details on supported virtual IBAN currencies for specific countries.
POST https://api.paysafe.com/digitalwallets/v1/wallets
{
"customer": {
"firstName": "John",
"lastName": "Doe",
"title": "Mr",
"email": "john.doe@example.com",
"mobile": "+443452555151",
"address1": "23 Four Str",
"city": "London",
"zip": "E17 033",
"countryCode": "GB",
"birthDate": "1999-08-24",
"registrationIp": "115.148.82.143",
"nationality": "GB",
"externalId": "d6f475fe-57c9-4865-9316-0c3b8e8128d4",
"kyc": {
"status": "COMPLETED",
"idVerification": {
"status": "COMPLETED",
"date": "2021-03-12T13:27:41Z",
"electronicallyVerified": true,
"vendor": "Vendor"
},
"addressVerification": {
"status": "COMPLETED",
"date": "2021-03-12T13:27:41Z",
"documentUrls": [
"https://documents.com/document1.png",
"https://documents.com/document2.png"
]
},
"faceMatch": {
"status": "COMPLETED",
"date": "2021-07-21T13:27:41Z",
"electronicallyVerified": true,
"vendor": "Vendor"
},
"EDD": {
"status": "COMPLETED",
"date": "2021-03-12T13:27:41Z",
"electronicallyVerified": true,
"vendor": "Vendor",
"documentUrls": [
"https://documents.com/document1.png",
"https://documents.com/document2.png"
]
},
"addressVerificationDocumentsReceived": [
"BANK_STATEMENT",
"CREDIT_CARD",
"TAX_RETURN",
"PENSION_DOCUMENT",
"PHONE_BILL",
"UNKNOWN_DOC"
],
"pep": {
"status": "MATCH",
"lastScreenDate": "2021-07-19T13:35:41Z",
"reason": "Matched"
},
"sanctions": {
"status": "NO_MATCH",
"lastScreenDate": "2021-07-19T13:35:41Z",
"reason": "Incorrect data"
}
}
},
"accounts": [{
"currencyCode": "GBP",
"hasIban": true
}, {
"currencyCode": "EUR",
"hasIban": false
}],
"risk": {
"customerRiskRating": 1,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"termsAndConditionsAccepted": true,
"deviceInfo": {
"threatMetrixSessionId": "a71a475b-1956-4814-9c92-7faa8226b218",
"threatMetrixData": "true_ip=87%2e120%2e141%2e75&true_ip_assert_history=NEGATIVE_HISTORY&true_ip_attributes=_CHALLENGED&true_ip_attributes=_CHALLENGE_PASSED&true_ip_attributes=_TRUSTED&true_ip_attributes=_TRUSTED_CONF&...",
"appType": "WEB_APP"
},
"customerIp": "73.82.192.17"
}
Additional Currencies
Additional currency support can be added to an existing customer by creating an account for the desired currency.
POST https://api.paysafe.com/digitalwallets/v1/accounts
{
"customerId": "5435323362",
"currencyCode": "GBP",
"hasIban": true
}
To get the account for specific currency use accounts
API.
The currency
and customerId
query parameters can be used to get the account for the specific currency of a customer.
GET https://api.paysafe.com/digitalwallets/v1/accounts?customerId=12345¤cy=GBP
[
{
"id": "509876034",
"customerId": "5435323362",
"currencyCode": "GBP",
"totalBalance": 55000,
"availableBalance": 50000,
"iban": "NL74ABNA1231242344",
"creationTime": "2019-08-24T14:15:22Z",
"hasIban": true,
"bic": "ABNANL2A"
}
]
Deposit Currency Conversion
The deposit currency and deposit account currency must match. If an account in the deposit currency does not exist, the deposit will fail.
Currency conversion might happen outside of the wallet with the following instrument specifics:
- CARD deposit - Requested deposit amount and currency is requested from the card provider. Any currency conversion (if applicable) and additional fees are applied to customer funding amounts outside of the embedded wallet.
- RAPID TRANSFER deposit - The bank account currency must match the deposit currency.
- BANK TRANSFER deposit - Deposit currency will match the IBAN currency. Currency conversion will happen at the BANK level.
Withdrawals Currency Conversion
The requested withdrawal amount must be present in the customer account matching the withdrawal currency.
Depending on the used instrument currency conversion might happen:
- bank account withdrawal - if the requested withdrawal currency matches а currency supported by Paysafe banking partners no FX will be applied by Paysafe. If no outbound channel matching the requested currency is available, the withdrawal will fail. Currency conversion and fees might additionally apply at receiving bank level.
- credit card withdrawal - the requested amount and currency is passed over to the card provider. Currency conversion and fees might additionally apply at receiving bank level.
Obtaining Exchange Rate Quote
For predictable currency conversion, embedded wallets offer exchange rate quote services. The service allows merchants to implement predictable currency exchanges for their customers in the following scenarios:
- Currency exchange between customer accounts
- Currency exchange during peer-to-peer transfers (when sender and recipient currencies do not match)
To obtain an exchange rate quote you should call the exchange rate API.
For quote creation, the important parameters are:
- sourceCurrency - source conversion currency
- targetCurrency - target conversion currency
- sender - the customer id requesting the conversion. Rates might differ for a different type of customers.
- recipient - the recipient of the exchange. Optional for local currency exchanges.
Example:
POST https://api.paysafe.com/digitalwallets/v1/fxrate
{
"sourceCurrency": "EUR",
"targetCurrency": "GBP",
"sender": "6755433",
"recipient": "328738"
}
Response:
{
"id": "404679be-ccbf-4528-b880-e14cc5041753",
"sourceCurrency": "EUR",
"targetCurrency": "GBP",
"timestamp": 1663076670,
"expiration": 1663066046,
"fxRate": 0.87,
"sender": "6755433",
"recipient": "328738"
}
The response would contain the suggested Paysafe exchange rate for the operation in fxRate
field,
valid for the time outlined in expiration
.
Merchants can use the quote for the preview of exchange operations and must pass the quote id
as a parameter during exchange operations
if they want to leverage the rate offered.
Local Currency Conversion
Currency exchange between two currencies inside a customer account is provided as an internal transfer. You will need the two accounts between which the exchange will happen:
sender.customerId
andrecipient.customerId
have the id of the customer performing the exchangereason
isCURRENCY_EXCHANGE
sender.accountId
is the source customer account holding the exchange amountrecipient.accountId
is the target account for the exchange operationfxQuote
is valid (non-expired) exchange rate quotefxQuote.sender
must be the same assender.customerId
fxQuote.recipient
must be the same asrecipient.customerId
- Both accounts's currencies must match the quote currencies
- If
fxQuote
is not passed, a new quote will be automatically obtained and used for the exchange merchantRefNum
- unique client-side identifier associated with the transferfee
- is merchant fee in source currency taken from the amount before conversion
The transfer is executed asynchronously, you can poll for status using merchantRefNum
parameter
or wait for webhook for the status of the transaction.
POST https://api.paysafe.com/digitalwallets/v1/transfers
{
"amount": 1000,
"fee": 100,
"currencyCode": "EUR",
"sender": {
"accountId": "5014567344",
"customerId": "500014306996"
},
"recipient": {
"accountId": "5014567345",
"customerId": "500014306996"
},
"merchantRefNum": "5040452805",
"customerIp": "192.168.0.1",
"risk": {
"customerRiskRating": 0,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"reason": "CURRENCY_EXCHANGE",
"fxQuote": "7b28ce27-c036-498c-91a7-5cc87a2e59d3"
}
Response:
{
"amount": 1000,
"fee": 100,
"currencyCode": "EUR",
"sender": {
"accountId": "5014567344",
"customerId": "500014306996"
},
"recipient": {
"accountId": "5014567345",
"customerId": "500014306996"
},
"merchantRefNum": "5040452805",
"customerIp": "192.168.0.1",
"risk": {
"customerRiskRating": 0,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"reason": "CURRENCY_EXCHANGE",
"status": "PENDING",
"fxQuote": "7b28ce27-c036-498c-91a7-5cc87a2e59d3"
}
Transfers Currency Conversion
Currency exchange during transfers between customers happens when the sender and recipient accounts have different currencies.
You will need the two accounts between which the exchange will happen:
sender.customerId
andrecipient.customerId
have the id of the customers performing the exchangesender.accountId
is the source customer account holding the exchange amountreason
isPEER_TRANSFER
recipient.accountId
is the target account for the exchange operationfxQuote
is valid (non expired) exchange rate quotefxQuote.sender
must be the same assender.customerId
fxQuote.recipient
must be the same asrecipient.customerId
- Both accounts currencies must match the quote currencies
- If
fxQuote
is not passed, a new quote will be automatically obtained and used for the exchange merchantRefNum
- unique client-side identifier associated with the transferfee
- is merchant fee in source currency taken from the amount before conversion
POST https://api.paysafe.com/digitalwallets/v1/transfers
{
"amount": 1000,
"fee": 100,
"currencyCode": "EUR",
"sender": {
"accountId": "5014567344",
"customerId": "500014306996"
},
"recipient": {
"accountId": "5014567345",
"customerId": "500014306997"
},
"merchantRefNum": "5040452805",
"customerIp": "192.168.0.1",
"risk": {
"customerRiskRating": 0,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"reason": "PEER_TRANSFER",
"fxQuote": "7b28ce27-c036-498c-91a7-5cc87a2e59d3"
}
Response:
{
"amount": 1000,
"fee": 100,
"currencyCode": "EUR",
"sender": {
"accountId": "5014567344",
"customerId": "500014306996"
},
"recipient": {
"accountId": "5014567345",
"customerId": "500014306996"
},
"merchantRefNum": "5040452805",
"customerIp": "192.168.0.1",
"risk": {
"customerRiskRating": 0,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"reason": "PEER_TRANSFER",
"status": "PENDING",
"fxQuote": "7b28ce27-c036-498c-91a7-5cc87a2e59d3"
}
Transfer status tracking
To get the transfer status the merchant applications should use Web Hooks or can poll for status using the merchantRefNum
.
GET https://api.paysafe.com/digitalwallets/v1/transfers?merchantRefNum=5040452805
[{
"amount": 1000,
"fee": 100,
"currencyCode": "EUR",
"sender": {
"accountId": "5014567344",
"customerId": "500014306996"
},
"recipient": {
"accountId": "5014567345",
"customerId": "500014306996"
},
"
"merchantRefNum": "5040452805",
"reason": "PEER_TRANSFER",
"status": "COMPLETED",
"fxQuote": "7b28ce27-c036-498c-91a7-5cc87a2e59d3"
}]
Transaction Currency Conversion Information
For transactions, where currency conversion is performed, additional fxAmount
property
will be present in the Transaction
object.
The fxAmount
allow to get information for currency exchange during the transaction.
It fxAmont.currency
contains the recipient currency for TRANSFER_OUT
transactions and the sender currency for TRANSFER_IN
transactions.
The fxAmount
object will contain:
amount
- contains the recipient converted ammount forTRANSFER_OUT
transactions and sender amount for forTRANSFER_IN
transactions.rate
- currency conversion ratecurrency
- the recipient currency forTRANSFER_OUT
and sender currency forTRANSFER_IN
transactions.
The merchant fee is taken from the sender amount before the currency conversion.
Example of the transaction containing exchange where:
- 10 GBP are sent from customer
5435323362
to customer5435323363
- 1 GBP is sent to the merchant account as merchant fees
- Customer
5435323363
receiving account is inEUR
so an exchange rate of1.15
is applied to match the target account currency - The exchanged amount is evident in
fxAmount
field inTRANSFER_IN
andTRANSFER_OUT
transactions
GET https://api.paysafe.com/digitalwallets/v1/transactions?merchantRefNum=5040452805
{
"transactions": [
{
"id": "5040057610",
"slipId": "5009964049",
"customerId": "5435323362",
"accountId": "5014567344",
"type": "TRANSFER_OUT",
"amount": 900,
"currencyCode": "GBP",
"fee": 100,
"creationTime": "2021-07-15T17:54:12Z",
"lastChangeDate": "2021-07-15T17:54:12Z",
"direction": "DEBIT",
"instrumentId": "1100000000000009",
"paymentType": "TRANSFER",
"status": "COMPLETED",
"merchantRefNum": "5040452805",
"fxAmount": {
"amount" : 1035,
"rate" : 1.15,
"currency": "EUR"
}
},
{
"id": "5040057612",
"slipId": "5009964049",
"customerId": "5435323363",
"accountId": "5014567344",
"type": "TRANSFER_IN",
"amount": 1035,
"currencyCode": "EUR",
"fee": 0,
"creationTime": "2021-07-15T17:54:12Z",
"lastChangeDate": "2021-07-15T17:54:12Z",
"direction": "CREDIT",
"paymentType": "TRANSFER",
"status": "COMPLETED",
"merchantRefNum": "5040452805",
"fxAmount": {
"amount" : 900,
"rate" : 1.15,
"currency": "GBP"
}
},
{
"id": "5040057611",
"slipId": "5009964049",
"customerId": "5435323362",
"accountId": "5014567344",
"type": "MERCHANT_FEE",
"amount": 100,
"currencyCode": "GBP",
"creationTime": "2021-07-15T17:54:12Z",
"lastChangeDate": "2021-07-15T17:54:12Z",
"direction": "DEBIT",
"instrumentId": "1100000000000009",
"fee": 0,
"paymentType": "TRANSFER",
"status": "COMPLETED",
"merchantRefNum": "5040452805"
},
{
"id": "5040057613",
"slipId": "5009964049",
"customerId": "6666666",
"accountId": "222222",
"type": "MERCHANT_FEE",
"amount": 100,
"currencyCode": "GBP",
"creationTime": "2021-07-15T17:54:12Z",
"lastChangeDate": "2021-07-15T17:54:12Z",
"direction": "CREDIT",
"fee": 0,
"paymentType": "TRANSFER",
"status": "COMPLETED",
"merchantRefNum": "5040452805"
}
],
"meta": {
"numberOfRecords": 4,
"limit": 4,
"page": 1
}
}