Liquidity Accounts: A Comprehensive Guide

Introduction

A Liquidity Account is a virtual account that facilitates the receipt of top-ups and payments, and the processing of payouts to your onboarded merchants. This solution offers a seamless banking-as-a-service experience within the Ping ecosystem, integrating smoothly with other payment functionalities.

Prerequisites

To start using Liquidity Accounts at Ping Payments, you need to onboard a physical account that supports the virtual account. This process is straightforward and involves contacting your representative at Ping Payments for setup.

For the sandbox environment, liquidity accounts are backed by fake bank accounts, whereas in production, they are backed by designated physical bank accounts. You can also have multiple backing accounts, for example, to support different currencies.

Approval from Ping is required to use this feature. We need to understand your business case and how you plan to utilize this functionality.

Creating a Liquidity Account

Once you have onboarded with a backing physical account, you can create a Liquidity Account using the following endpoint:

https://docs.pingpayments.com/reference/v1createliquidityaccount

Enabling Bank Top-Ups

Bank top-ups allow the account to be replenished via bank transfer. To enable this feature, include "enable_deposits" in the POST request body when creating a Liquidity Account. The response payload will contain the top-up bank transfer information, referred to as "deposit_information," which includes details like IBAN and a static reference for the virtual account.

Account Ownership

In the POST request payload, you can specify the owner of the account, which can be an individual or an organization. This is done by providing the type, country, and identity number of the entity. In Sweden, for example, this would be the personal identity number for individuals and the organization number for companies.

Example POST Request

POST https://sandbox.pingpayments.com/payments/api/v1/liquidity_accounts

{
  "name": "Kalle Karlsson Software Account",
  "currency": "SEK",
  "enable_deposits": true,
  "account_holder": {
    "name": "Kalle Karlsson Software AB",
    "identity": {
      "country": "SE",
      "identifier": "5550011168",
      "type": "organization"
    }
  }
}

Example Response

{
  "id": "fc7fbfd7-d07c-4129-b0a1-c2c3e9654624",
  "deposit_information": {
    "reference": "a11a44afe6",
    "bank_account": {
      "bic": "ESSESESS",
      "bban": null,
      "iban": "SE9850000000053321072521",
      "bankgiro_number": null
    },
    "deposit_account": null,
    "invoice": null
  }
}

Note: Save the ID reference, as browsing Liquidity Accounts is not currently supported.

Checking Balance

To check the balance of the account, use the saved reference:

GET https://sandbox.pingpayments.com/payments/api/v1/liquidity_accounts?id=fc7fbfd7-d07c-4129-b0a1-c2c3e9654624

Example Response

{
  "id": "fc7fbfd7-d07c-4129-b0a1-c2c3e9654624",
  "balance": 0,
  "currency": "SEK",
  "deposit_information": {
    "reference": "a11a44afe6",
    "bank_account": {
      "bic": "ESSESESS",
      "bban": null,
      "iban": "SE9850000000053321072521",
      "bankgiro_number": null
    },
    "deposit_account": null,
    "invoice": null
  }
}

To simulate a top-up, use the Create Deposit Payment method in Mimic:

POST https://mimic-sandbox.pingpayments.com/api/deposit_payment

{
  "reference_type": "OCR",
  "reference": "a11a44afe6",
  "type": "instant",
  "iban": "SE9850000000053321072521",
  "currency": "SEK",
  "amount": 10000
}

The response code will be 204. Fetch the balance again to see the updated amount.

Making Payments to a Liquidity Account

To make payments to a Liquidity Account, follow the standard Ping Payments API process but use the Liquidity Account ID as the recipient. For example:

Standard Order Items

"order_items": [
    {
      "amount": 10000,
      "merchant_id": "db848cb6-27f6-4500-8fa0-66b2ef1feb57",
      "name": "Donation",
      "vat_rate": 0
    }
  ] 

Liquidity Account Order Items

"order_items": [
    {
      "amount": 10000,
      "liquidity_account_id": "db848cb6-27f6-4500-8fa0-66b2ef1feb57",
      "name": "Donation",
      "vat_rate": 0
    }
  ] 

You can also direct funds to a Liquidity Account through a split-tree, which needs to be configured by Ping Payments. This is useful in scenarios such as withholding VAT funds in a separate account for later payment to the tax agency.

Payouts from a Liquidity Account

Payouts from a Liquidity Account are processed using the same API as other payments. To do this, specify the liquidity_account_id in the provider_method_parameters of the payment request payload. The funds will be moved from the account and processed according to the payout routine to the merchants or other parties involved in the transaction.

By using the Ping Credit provider method, you ensure that funds are efficiently managed and routed through the same streamlined API process for both incoming and outgoing transactions.