Deposits
Introduction
Deposit operation allows customers of Paysafe Embedded Wallet to load funds into their embedded wallet accounts. The supported deposit methods are:
- Debit ot Credit card
- Bank transfer using Virtual IBAN
- Rapid Transfer
Embedded wallet leverages Paysafe Payments API for deposits, withdrawals and refunds.
Not all payment methods provided by Payments API are supported in Paysafe Embedded Wallet. For reference of supported deposit methods use Paysafe Embedded Wallet documentation.
Deposit corresponds to PAYMENT transaction type in Payments API.
All operations associated with Embedded Wallet account require additional wallet property to be present.
The wallet parameter contains the information for the wallet customer and account associated with the transaction.
Card Deposit
Card deposits support using 3Ds provided by Paysafe, as well as externally provided 3DS authentication.
-
Regular customers can deposit with Visa and Mastercard credit and debit cards in EUR and GBP. Merchant have to manage the user experience and can use either Paysafe integrated 3DS solution or with any other 3DS provider directly. Once card payment is processed successfully, the customers wallet balance will be increased with the deposit amount. Merchant can apply a fee to the customer’s card deposits. The fee is transferred to predefined merchant account.
-
Customers must choose the deposit amount and must provide their card details at merchants website or mobile app.
-
Merchant should send a payment request to Paysafe including deposit amount, currency, card details, customer ID and customer fee.
-
Paysafe will process the card payment for deposit amount and any fees with the provider.
-
Paysafe will increase the customer’s wallet balance with the deposit amount and customer fee.
-
Paysafe will debit customer’s wallet with the fees and credit customer fee to Merchant merchant wallet.
The deposit flow using Paysafe provided 3DS follows below.
There is an option to use externally provided 3DS for card payment authorization.
Rapid Transfer Deposit
Paysafe offers deposits, with instant bank transfer solution Rapid Transfer.
The real-time bank transfer solution is suitable for the smaller basket size transfers. Rapid Transfer payments are normally instant however a small percentage of high risk transactions may have delayed processing for several business days.
-
Transaction limits for Rapid Transfer
Daily Weekly Monthly 5,000 EUR 7,500 EUR 25,000 EUR
Rapid Transfer Deposit Steps
-
Customer selects 'Rapid Transfer' as the payment type from the Merchant's website
-
(Optional) Merchant calls Paysafe to retrieve a list of available banks and displays to Customer
GET
https://api2.paysafe.com/digitalwallet/v1/rapidtransferbanks?country=GB{ "rapidTransferBanks": [ { "id": "1000203", "name": "Natwest UK", "isAccountRequiredBeforeInitialization": true, "country": "GB" } ] }
-
Merchant must collect customer’s bank account details (IBAN and SWIFT code for euro payments and sort code and account number for payments in GBP).
-
Merchant calls Paysafe to create a Payment Handle and Paysafe responds with a Redirect URL
POST
https://api2.paysafe.com/paymenthub/v1/paymenthandles{ "merchantRefNum": "merchantRefNum-124", "transactionType": "PAYMENT", "rapidTransfer" : { "sepa": { "accountHolderName": "John Doe", "bic": "ABNANL2APIP", "iban": "DE89370400440532013000" } }, "paymentType": "RAPID_TRANSFER", "amount": 3000, "currencyCode": "EUR", "customerIp": "73.82.192.17", "billingDetails": { "street": "71 Cherry Court ", "city": "Southhampton", "zip": "SO53 5PD", "country": "GB" }, "wallet":{ "customerId" : "GGG", }, "returnLinks": [{ "rel": "on_completed", "href": "https://US_commerce_site/payment/return/success", "method": "GET" }, { "rel": "on_failed", "href": "https://US_commerce_site/payment/return/failed", "method": "GET" } ] }Response
{ "id": "372b5ee7-6360-4403-b444-164f8f1d2709", "amount": 3000, "merchantRefNum": "merchantRefNum-124", "action": "REDIRECT", "currencyCode": "EUR", "usage": "SINGLE_USE", "status": "INITIATED", "paymentType": "RAPID_TRANSFER", "executionMode": "SYNCHRONOUS", "customerIp": "73.82.192.17", "paymentHandleToken": "SCyGZDlUuZ9zxjyd", "billingDetails": { "street": "71 Cherry Court ", "city": "Southhampton", "zip": "SO53 5PD", "country": "GB" }, "rapidTransfer" : { "sepa": { "accountHolderName": "John Doe", "bic": "ABNANL2APIP", "lastDigits": "00" } }, "wallet":{ "customerId" : "GGG", "slipId" : "100753" }, "returnLinks": [{ "rel": "on_completed", "href": "https://US_commerce_site/payment/return/success", "method": "GET" }, { "rel": "on_failed", "href": "https://US_commerce_site/payment/return/failed", "method": "GET" } ], "links": [{ "rel": "redirect_payment", "href": "http://api.paysafe.com/rapidtransfer/redirect/372b5ee7-6360-4403-b444-164f8f1d2709", "method": "GET" }], "timeToLiveSeconds": 899, "transactionType": "PAYMENT" }
-
Merchant redirects the Customer
-
Customer authenticates banking details and confirms the deposit operation
-
Customer is redirected back to the Merchant or Merchant recieves a PaymentHandle webhook that is PAYABLE
POST
https://<merchant callback URL>{ "resourceId": "3aeb9c63-6386-46a3-9f8e-f452e722228a", "eventDate": "2021-07-15T17:54:12Z", "eventType": "PAYMENT_HANDLE_PAYABLE", "payload": { "id": "372b5ee7-6360-4403-b444-164f8f1d2709", "amount": 3000, "merchantRefNum": "merchantRefNum-124", "action": "NONE", "currencyCode": "EUR", "usage": "SINGLE_USE", "status": "PAYABLE", "paymentType": "RAPID_TRANSFER", "executionMode": "SYNCHRONOUS", "customerIp": "73.82.192.17", "paymentHandleToken": "SCyGZDlUuZ9zxjyd", "billingDetails": { "street": "71 Cherry Court ", "city": "Southhampton", "zip": "SO53 5PD", "country": "GB" }, "rapidTransfer": { "sepa": { "accountHolderName": "John Doe", "bic": "ABNANL2APIP", "lastDigits": "00" } }, "wallet": { "customerId": "GGG", "slipId": "100753" }, "returnLinks": [ { "rel": "on_completed", "href": "https://US_commerce_site/payment/return/success", "method": "GET" }, { "rel": "on_failed", "href": "https://US_commerce_site/payment/return/failed", "method": "GET" } ], "links": [ { "rel": "redirect_payment", "href": "http://api.paysafe.com/rapidtransfer/redirect/372b5ee7-6360-4403-b444-164f8f1d2709", "method": "GET" } ], "timeToLiveSeconds": 899, "transactionType": "PAYMENT" } }
NOTE A redirect may not always occur as it is depenant on the Customer, browser and connection. The webhook shold be used as a failsafe to complete the payment to avoid reconcilliation issues.
-
Merchant looks up the status of the payment handle
NOTE Only required if webhook not recieved
GET
https://api2.paysafe.com/paymenthub/v1/paymenthandles/{paymenthandleid}{ "id": "372b5ee7-6360-4403-b444-164f8f1d2709", "amount": 3000, "merchantRefNum": "merchantRefNum-124", "action": "NONE", "currencyCode": "EUR", "usage": "SINGLE_USE", "status": "PAYABLE", "paymentType": "RAPID_TRANSFER", "executionMode": "SYNCHRONOUS", "customerIp": "73.82.192.17", "paymentHandleToken": "SCyGZDlUuZ9zxjyd", "billingDetails": { "street": "71 Cherry Court ", "city": "Southhampton", "zip": "SO53 5PD", "country": "GB" }, "rapidTransfer" : { "sepa": { "accountHolderName": "John Doe", "bic": "ABNANL2APIP", "lastDigits": "00" } }, "wallet":{ "customerId" : "GGG", "slipId" : "100753" }, "returnLinks": [{ "rel": "on_completed", "href": "https://US_commerce_site/payment/return/success", "method": "GET" }, { "rel": "on_failed", "href": "https://US_commerce_site/payment/return/failed", "method": "GET" } ], "links": [{ "rel": "redirect_payment", "href": "http://api.paysafe.com/rapidtransfer/redirect/372b5ee7-6360-4403-b444-164f8f1d2709", "method": "GET" }], "timeToLiveSeconds": 899, "transactionType": "PAYMENT" }
-
Merchant finalizes the payment by POST-ing a payment
NOTE After the Customer is redirected to Rapid Transfer and Payment Handle becomes PAYABLE, the Customer might authorize the payment, regardless of whether the Payment is posted by the Merchant. That is why POST-ing Payment for PAYABLE handle is important, so the Deposit status can be tracked.
POST
https://api2.paysafe.com/paymenthub/v1/payments{ "merchantRefNum": "merchantRefNum-123", "amount": 3000, "currencyCode": "EUR", "paymentHandleToken": "SCyGZDlUuZ9zxjyd", "description": "Consumer Purchase", "customerIp": "73.82.192.17" }Response
{ "id": "3aeb9c63-6386-46a3-9f8e-f452e722228a", "merchantRefNum": "merchantRefNum-123", "amount": 1000, "currencyCode": "EUR", "paymentHandleToken": "SCyGZDlUuZ9zxjyd", "paymentType": "RAPID_TRANSFER", "rapidTranfer": { "sepa": { "accountHolderName": "John Doe", "bic": "ABNANL2APIP", "lastDigits": "00" } }, "description": "Consumer Purchase", "customerIp": "73.82.192.17", "availableToSettle": 0, "status": "COMPLETED", "wallet": { "customerId": "abc", "slipId": "100753", "customerAccount": { "id": "10021", "transactions": [ { "id": "12321", "type": "DEPOSIT", "amount": 3000, "currencyCode": "EUR", "creationTime": "2021-07-15T17:54:12Z", "direction": "CREDIT", "paymentType": "RAPID_TRANSFER", "status": "COMPLETED", "merchantRefNum": "merchantRefNum-123" }, { "id": "12322", "type": "TRANSFER_OUT", "amount": 3000, "currencyCode": "EUR", "creationTime": "2021-07-15T17:54:12Z", "direction": "DEBIT", "paymentType": "RAPID_TRANSFER", "status": "COMPLETED", "merchantRefNum": "merchantRefNum-123" } ] }, "merchantAccount": { "id": "10022", "transactions": [ { "id": "12323", "type": "TRANSFER_IN", "amount": 3000, "currencyCode": "EUR", "creationTime": "2021-07-15T17:54:12Z", "direction": "CREEDIT", "paymentType": "RAPID_TRANSFER", "status": "COMPLETED", "merchantRefNum": "merchantRefNum-123" } ] } }, "txnTime": "2018-12-11T16:33:49Z" }
-
Merchant recieves a TransactionUpdateWebhоok when funds are deposited in the wallet
NOTE This can occur anytime after the redirect, There shall be both customer and merchant account update webhooks, merchant should filter on the merchant account ID.
POST
https://<merchant callback URL>{ "id": "", "timestamp": "2021-07-15T17:54:12Z", "transaction": { "id": "544232", "merchantRefNum": "merchantRefNum-123", "customerId": "abc", "accountId": "10022", "type": "TRANSFER_IN", "slipId": "100753", "amount": 3000, "currencyCode": "EUR", "creationTime": "2018-12-11T16:33:49Z", "direction": "CREEDIT", "paymentType": "RAPID_TRANSFER", "description": "Transaction description.", "status": "COMPLETED", } }
-
Handling of Delayed confirmation deposits.
Usually after authorizing the payment, the deposit is confirmed within 15 minutes. For specific deposit amounts, country or bank - Rapid Transfer might release the funds only after they are received in Paysafe bank account. In that case the Payment will be in PROCESSING state until the final state is set.
NOTE When Rapid Transfer deposit gets delayed, a final state of the Payment might take up to several days (3-4 days average). Use PROCESSING Payment state as indicator to detect delayed confirmation and notify end users.
Bank Transfer Deposit
Paysafe supports bank transfer deposits using customer assigned vIBANs in Paysafe partner bank. Once offline customer deposit reaches Paysafe partner bank, customer's wallet is funded with the corresponding amount.
Virtual IBAN is assigned to each customer during the onboarding process. You can obtain the vIBAN using Accounts API and passing the customerId as parameter.
GET https://api2.paysafe.com/digitalwallet/v1/accounts?customerId=5435323362
[{
"id": "509876034",
"customerId": "5435323362",
"currencyCode": "GBP",
"totalBalance": 55000,
"availableBalance": 50000,
"iban": "NL74ABNA1231242344",
"creationTime": "2019-08-24T14:15:22Z",
"hasIban": true,
"bic": "ABNANL2A"
}]Bank Transfer Deposit Steps
-
Merchant must show vIBAN details and Paysafe as account holder upon bank transfer payment option on Merchant website
-
Customer initiates bank transfer from their bank to their vIBAN
-
Paysafe performs vIBAN and name match when deposit is received in Paysafe partner bank
-
The transaction amount will be credited to the customer wallet
-
Where applicable, the merchant deposit fee amount will be debited from the customer wallet
Customers can only be charged a pre-defined fixed fee for bank transfer deposits.
-
Merchant recieves a TransactionUpdateWebhok when funds are deposited in the wallet
POST
https://<merchant callback URL>{ "id": "3aeb9c63-6386-46a3-9f8e-f452e722228a", "timestamp": "2021-07-15T17:54:12Z", "transaction": { "id": "544232", "merchantRefNum": "abcd1234", "customerId": "1234", "accountId": "212345", "type": "DEPOSIT", "slipId": "121345", "amount": 1000, "currencyCode": "EUR", "creationTime": "2021-07-15T17:54:12Z", "direction": "CREDIT", "paymentType": "BANK_TRANSFER", "description": "Transaction description.", "status": "COMPLETED" } }