Payouts

API Reference: Payouts

A Payout is a payment made from Hokodo to your bank account. It is comprised of a number of Payout Items, which are scheduled following post sale events such as Captures or Refunds.

The Payout date is defined according to your commercial agreement with Hokodo. With most of our merchants, we schedule Payouts for the Thursday of the week following the post sale event to which the Payout Item relates, but some of our merchants require more regular Payouts.

On your regular Payout dates, we will make a payment of all scheduled Payout Items that are due up to and including that date, with two cavets:

1. we may subtract the Withheld Amount, which is the amount that we need to withold from Payouts in order to maintain your minimum balance, and is shown as min_balance[withheld_amount] in the API response.
2. we may add Payout Adjustments, shown as adjustments in the API response.

These two caveats are discussed in more detail later in this page.

Which merchants tend to use this API endpoint?

The Payouts API is typically integrated by marketplaces who have automated processes to pay the suppliers on their platform as soon as the money is received by the marketplace.

If this is your use case, ask your Customer Success Manager to configure webhooks to notify you of Payouts being paid. The payload will include the Payout Items as below, so you can route funds to Sellers through your Payouts PSP.

Payout Items

One Payout Item is created for each post-sale event that occurs.

• When a Capture post sale event occurs, a corresponding "fulfilment" Payout Item is scheduled that will increase the balance we owe you. The value of the Payout Item is the Captured amount less merchant fees.
• Conversely, when a Refund event occurs, we will schedule a "return" Payout Item that effectively reduces the magnitude of your next Payout.
• When a Clawback event is initiated by Hokodo, we will schedule an e.g. "credit_clawback" Payout Item, which reduces the magnitude of your next Payout.

In summary, Post Sale events have Payout Item types as follows:

Post sale event	Payout Item Type
Capture	fulfilment
Refund	return
Credit Clawback	credit_clawback
Fraud Clawback	fraud_clawback
Misdirected Payment Clawback	misdirected_payment_clawback
Other Clawback	other_clawback

Upload Invoices to recieve payouts

You must upload an Order Document of type Invoice in order to receive Payout Items. If you do not, Payout Items will be suspended and have status awaiting_document. They will not be included in payouts until an Invoice order document is uploaded.

How to see whether a Payout Item is paid out or scheduled to be

If the Payout Item has been paid out, in the list of items, the payout and actual_payout_date fields will both be populated, and the status will be paid.

  "items": [
    {
      "id": "poitm-yQKxbtCg9aTS5JYnsRVA9B",
      "type": "fulfilment",  
      "payout": "po-yQKxbtCg9aTS5JYnsRVA9B", 
      "status": "paid",
      "actual_payout_date": "2022-01-01",
      "amount": 1100,
      "fees": 100,
      "deferred_payment": "defpay-aaaaCg9aTS5JYnsRVbbbb",
      "order": "order-aaaaaaCg9aTS5JYnsRbbbb",
      ... some fields omitted for brevity.
    },
        {
      "id": "poitm-aaaxbtCg9aTS5JYnsRVA9B",
      "type": "credit_clawback",  
      "payout": "po-yQKxbtCg9aTS5JYnsRVA9B", 
      "status": "paid",
      "actual_payout_date": "2022-01-01",
      "amount": -300,
      "fees": 0,
      ... some fields omitted for brevity.
    },
    ...
  ]

To aid reconciliation, each Payout Item has IDs for the order and deferred payment that it belongs to.

On the other hand, if the Payout Item is to be paid out in a future Payout, then said fields will be null and the status of the Payout Item will be scheduled.

  "items": [
    {
      "id": "poitm-yQKxbtCg9aTS5JYnsRVA9B",
      "type": "fulfilment",  
      "payout": null, 
      "status": "scheduled",
      "actual_payout_date": null,
      "amount": 1100,
      "fees": 100,
      ... some fields omitted for brevity.
    },
    ...
  ]

Minimum Balance

In addition to Payout Items and Adjustments, the other factor that can affect the amount that we pay out to you is whether or not we need to hold a minimum balance on your account.

In most cases, Hokodo maintains a minimum balance of money that is owed to Hokodo by buyers as a risk management safeguard required by the credit facility behind our lending. This is often comprised of:

• a fixed amount (eg. €1000)
• and a relative amount (eg. 10% of Deferred Payments that are yet to be settled to Hokodo).

To maintain that minimum balance, we will withhold one or more Deferred Payments from Payouts until the minimum balance is reached.

How we choose which Payout Items to withold

• We use a first-in-first-out methodology when withholding Payout Items. In other words, we will withhold the earliest-scheduled Payout Item and keep withholding later Payout Items until the minimum balance condition is satisfied.
• We do not withhold partial Payout Items. Consequently, if the Payout Item amount that satisfies the minimum balance is relatively large, it can seem like the withheld balance is large compared to the minimum balance. In most cases this problem will resolve itself in the short term, but if it causes a problem for you, please contact your Customer Success Manager who may be able to advance the difference between the withheld amount and the minimum balance.

How to see which Payout Items have been withheld

You can see which Payout Items have been withheld as the earliest_payout_date will be in the past, a Payout exists since then, and yet the Payout Item status will remain as scheduled.

Adjustments

Adjustments are added when the amount we need to pay out to your account differs from simply the sum of the Payout Items that are scheduled.

For example, we might agree with you that it is appropriate for us to advance money that is scheduled for a later Payout, or is being withheld due to the minimum balance constraints (explained below.) Or, we may have arranged with you that:

• credit limit review fees
• FX fees
• or any top up to reach our monthly minimum fees

should come out of Payouts. These details will all be arranged with you as part of your commercial agreement with Hokodo.

The full range of adjustments are listed in the API Reference: Payout Object.