Skip to main content

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.

warning

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 the merchant wallet.

The deposit flow using Paysafe provided 3DS follows below.

Deposit with a cardDeposit with a cardDeposit with a cardDeposit with a card

There is an option to use externally provided 3DS for card payment authorization.

Deposit with a cardDeposit with a cardDeposit with a cardDeposit with a card

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:

DailyWeeklyMonthly
5,000 EUR7,500 EUR25,000 EUR

Rapid Transfer Deposit Steps

Deposit with RapidTransferDeposit with RapidTransferDeposit with RapidTransferDeposit with RapidTransfer
  1. Customer selects 'Rapid Transfer' as the payment type from the Merchant's website

  2. (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

    Request

    {
    "rapidTransferBanks": [
    {
    "id": "1000203",
    "name": "Natwest UK",
    "isAccountRequiredBeforeInitialization": true,
    "country": "GB"
    }
    ]
    }
  3. 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).

  4. Merchant calls Paysafe to create a Payment Handle and Paysafe responds with a Redirect URL

    POST https://api2.paysafe.com/paymenthub/v1/paymenthandles

    Request

    {
    "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"
    }
  5. Merchant redirects the Customer

  6. Customer authenticates banking details and confirms the deposit operation

  7. Customer is redirected back to the Merchant or Merchant recieves a PaymentHandle webhook that is PAYABLE

    POST https://<merchant callback URL>
    Payment Handle webhook
    {
    "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"
    }
    }
    warning

    A redirect may not always occur as it is dependant on the Customer, browser and connection. The webhook should be used as a failsafe to complete the payment to avoid reconcilliation issues.

  8. Merchant looks up the status of the payment handle

    GET https://api2.paysafe.com/paymenthub/v1/paymenthandles/{paymenthandleid}

    Response

    {
    "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"
    }
    tip

    Only required if webhook is not received

  9. 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

    Request

    {
    "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": "CREDIT",
    "paymentType": "RAPID_TRANSFER",
    "status": "COMPLETED",
    "merchantRefNum": "merchantRefNum-123"
    }
    ]
    }
    },
    "txnTime": "2018-12-11T16:33:49Z"
    }
  10. Merchant recieves a TransactionUpdateWebhook 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>
    Account update webhook
    {
    "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": "CREDIT",
    "paymentType": "RAPID_TRANSFER",
    "description": "Transaction description.",
    "status": "COMPLETED",
    }
    }
  11. 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.

    info

    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
Get account information
[{
"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

Bank transfer depositBank transfer depositBank transfer depositBank transfer deposit
  1. Merchant must show vIBAN details and Paysafe as account holder upon bank transfer payment option on Merchant website

  2. Customer initiates bank transfer from their bank to their vIBAN

  3. Paysafe performs vIBAN and name match when deposit is received in Paysafe partner bank

  4. The transaction amount will be credited to the customer wallet

  5. Where applicable, the merchant deposit fee amount will be debited from the customer wallet

    info

    Customers can only be charged a pre-defined fixed fee for bank transfer deposits.

  6. Merchant recieves a TransactionUpdateWebhook when funds are deposited in the wallet

    POST https://<merchant callback URL>
    Transaction update webhook
    {
    "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"
    }
    }