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.

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

Request

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

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

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>

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.

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

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

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",
  }
}

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

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

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

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

Introduction​

Card Deposit​

Rapid Transfer Deposit​

Rapid Transfer Deposit Steps​

Bank Transfer Deposit​

Bank Transfer Deposit Steps​

Introduction

Card Deposit

Rapid Transfer Deposit

Rapid Transfer Deposit Steps

Bank Transfer Deposit

Bank Transfer Deposit Steps