Overview

Payout is a type of financial records representing fund transfers from merchant's payment processor wallet to a destination account. In most cases, the destination account is merchant's bank account. For companies with marketplace or revenue-sharing business models, the destination account may be a payment processor wallet or bank account owned by non-merchant.

📘

Payout vs Settlement

On Leapfin's platform, Payout is referred to as "Settlement". The data type for Payout is "LeapfinSettlement" and the associated table name is "VW_FT_SETTLEMENT".

It is important to notice that the term "Settlement" is used differently in some payment processor systems. "Settlement" (or "Settle") may refer to a specific status of payment. For example, a payment is authorized, captured, then settled in merchant's wallet. Leapfin includes such settled status as parts of Payment record.

Create a Payout

The following fields are required :

  • objectType: type of financial record. For Payout, the value is "payout".
  • id: unique identifier of this record. This is external id received by Leapfin.
  • amount: amount of money impacted by this record. The value should be non-negative. This is the primary amount of this record.
  • currencyCode: 3-digit ISO code of amount field, e.g. “USD”, "GBP", etc. This is the primary currency of this record
  • date: the date-time of when this payout is created by payment processor.
  • status: the status of the payout. Acceptable values are
    • "paid": the payout is successfully processed.
    • "failed": the payout failed during processing.
    • "pending": the payout is initiated but still being processed.

The following fields are optional but are commonly need for creating journal entries:

  • description: description of the payout.
  • exchangeRates: a list of exchange rates used to calculate currency conversions
    • currencyCode: 3-digit ISO code, e.g. “USD”, "GBP", etc. This is the target currency of this record
    • rate: conversion rate from primary currency to target currency. i.e. amount in primary currency * rate = converted amount in target currency.
  • links: directional relationships pointing from this record to other financial records. Payout is commonly linked to Payment, Refund and Dispute.
    • objectType: type of the target financial record, e.g. "line-item"
    • id: unique identifier of the target financial record
  • customFields: additional fields (i.e. key-value pairs) related to this record

Sample Data

{
    "objectType": "payout",
    "id": "payout_001",
    "amount": 908977.41,
    "currencyCode": "USD",
    "status": "paid",
    "description": "a sample payout object",
    "date": "2021-01-28T18:28:08",
    "exchangeRates": [
      {
        "currencyCode": "EUR",
        "rate": 0.84
      },
      {
        "currencyCode": "GBP",
        "rate": 0.73
      }
    ],
    "links": [
      {
        "objectType": "line-item",
        "id": "lineitem_001"
      },
      {
        "objectType": "line-item",
        "id": "lineitem_002"
      }
    ],
    "customFields": {
      "field1": "value1",
      "field2": "value2"
    }
}

Query a Payout

Payout records are stored in VW_FT_SETTLEMENT table. It can be accessed via Snowflake Data Sharing and Access.

ColumnDescription
LEAPFIN_IDunique identifier created by Leapfin.
DECODED_LEAPFIN_ID_VTdecoded version of LEAPFIN_ID in json format. It contains following values:

- external_code: unique identifier of this record. This is external id received by Leapfin.
- integration_id: unique identifier of the data source. This is internal id created by Leapfin.
- leapfin_data_type: type of financial record, i.e. "LeapfinSettlement"
- leapfin_suffix: additional string to distinguish different financial records when the same external_code is received from the data source.
- raw_data_type: type of raw data record received from the data source.
ORGANIZATION_IDunique identifier of the account. This is internal id created by Leapfin.
DATE_DTthe date of when this payout is created by payment processor.
DESCRIPTIONdescription of the payout.
CURRENCY_CODE3-digit ISO code of amount field, e.g. “USD”, "GBP", etc. This is the primary currency of this record.
AMOUNTamount of money impacted by this record. The value should be non-negative. This is the primary amount of this record.
STATUSthe status of the payout. Acceptable values are:

- "paid": the payout is successfully processed.
- "failed" - the payout failed during processing.
- "pending" - the payout is initiated but still being processed.
EXCHANGE_RATES_VTa list of exchange rates used to calculate currency conversions. Each rate contains following values:

- currencyCode: 3-digit ISO code, e.g. “USD”, "GBP", etc. This is the target currency of this record.
- rate: conversion rate from primary currency to target currency. i.e. amount in primary currency * rate = converted amount in target currency.
CUSTOM_FIELDS_VTadditional fields (i.e. key-value pairs) about the financial record in json format
ACCOUNTING_TRANSACTIONS_VTa list of journal entries associated with this financial record. Each item contains following values:

- date: the date of the journal entry
- entries: a list of journal lines within the journal entry. Each line contains following values:
--- account: unique identifier of the financial account. This is an internal id created by Leapfin (refer to VW_LK_ACCOUNT).
--- amount: amount of money booked towards the account.
--- accountingSide: an indicator of whether the amount is a debt ("dr") or credit ("cr") to the acount.
- comments: additional fields (i.e. key-value pairs) on the journal entry in json format.
CREATED_AT_DTthe date-time when the financial record is created by Leapfin. Value format: "2022-07-14 23:01:26.400"
UPDATED_AT_DTthe date-time when the financial record is last updated by Leapfin. Value format: "2022-09-01 06:09:57.379"