Currency Handling
(In Development)
Paysafe digital wallet solution supports customers to hold balances in different currencies.
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.
-
When doing a deposit the deposit account currency must match the deposit amount currency
-
When doing withdrawal the withdrawal amount currency must match the withdrawal account currency
-
When doing transfers the source account currency must match the transfer currency
Setup multiple currencies 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 currency 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"
}
Add additional currency for existing customer
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
}
Getting account for specific currency
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"
}
]
Currency conversion during deposits
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 digital 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.
Currency conversion for withdrawals
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 in digital wallet. 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, digital 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 receiver 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
-
requester - the customer id requesting the conversion. Rates might differ for a different types of customers.
-
receiver - the receiver of the exchange. Optional for local currency exchanges.
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 and recipient.customerId have the id of the customer performing the exchange
-
reason is CURRENCY_EXCHANGE
-
sender.accountId is the source customer account holding the exchange amount
-
recipient.accountId is the target account for the exchange operation
-
fxQuote is valid (non expired) exchange rate quote
-
fxQuote.sender must be the same as sender.customerId
-
fxQuote.recipient must be the same as recipient.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 transfer
-
fee - 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 Web Hook 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"
}
Currency conversion during transfers
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 and recipient.customerId have the id of the customers performing the exchange
-
sender.accountId is the source customer account holding the exchange amount
-
reason is PEER_TRANSFER
-
recipient.accountId is the target account for the exchange operation
-
fxQuote is valid (non expired) exchange rate quote
-
fxQuote.sender must be the same as sender.customerId
-
fxQuote.recipient must be the same as recipient.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 transfer
-
fee - 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"
}
{
"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"
}
Get currency conversion status from Transfer object
To get the transfer status the merchant application should use Web Hooks or can poll for status from Transfer 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",
"customerIp": "192.168.0.1",
"risk": {
"customerRiskRating": 0,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"reason": "PEER_TRANSFER",
"status": "COMPLETED",
"fxQuote": "7b28ce27-c036-498c-91a7-5cc87a2e59d3"
}
Get currency conversion information from transaction history
For transactions, where currency conversion is performed, additional fxAmount property will be present in the Transaction object.
The fxAmount object will contain:
-
amount - converted amount
-
rate - currency conversion rate
-
currency - the conversion currency
The merchant fee is taken from the transfer amount before the FX
Example of the transaction containing exchange where:
-
10 GBP are sent from customer 5435323362 to customer 5435323363
-
1 GBP is sent to merchant account as merchant fees
-
Customer 5435323363 receiving account is in EUR so an exchange rate of 1.15 is applied to match the target account currency
-
The exchanged amount is evident in fxAmount field as in TRANSFER_IN amount in the incoming transaction of the receiving side.
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": "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": "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"
},
{
"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
}
}