Payout schedules

As a marketplace, you will have a choice to make when it comes paying your sellers. You can pay your sellers instantly, allowing them to cash out the moment a sale closes. This makes your seller happy, but exposes you to risk should the customer demand a refund. Or you can delay payment to the seller, holding the money long enough to ensure that all parties are satisfied. This reduces your risk, but isn't what your sellers would prefer. Ideally, you would provide your best sellers with the best perks, meaning you'll need to manage a mix of instant and delayed payouts. Formance Ledger makes it easy to do both.

Giving your merchants a great payout experience allows you to stand out from your competitors in building loyalty and a positive brand image among your merchants. Your payout schedule is a key component in creating a stellar merchant experience. There are two extreme stances you can take:

1. Instant payout. You pay your sellers immediately with each sale. Sellers are happy with the fast turnaround. But you take on additional risk: If there is a problem with the order, you might not be able to recoup the costs from the seller, forcing you to take the loss. As a result, this is a payout schedule that you'll want to offer to only your best sellers, sellers with a history of happy customers.

2. Delayed payout. You hold on to the money from each sale for a specified amount of time, say 14 days, before releasing it to the seller. This way, if there is a problem with the purchase, you can quickly issue a refund at no risk to yourself. However, sellers do not prefer this arrangement, and it does lead to a more complicated operations backend. Even so, this is the payout schedule you'll offer to new and untested sellers.

Of course, you can offer tiers of payout schedules, with decreasing delays as sellers prove themselves to be reliable partners.

Instant payouts are the easiest to implement—you simply transfer the balance from each sale directly to the seller. Suppose customer with ID U1234 made a purchase with ID T1234. Among the items in that purchase was one for $4.99 from seller with ID U6789. You can record the payout using Numscript:

send [USD/2 499] (
  source = @user:U1234:transactions:T1234
  destination = @user:U6789:wallet
)

The account @user:U1234:transactions:T1234 is a temporary order account created to track the flow of money from the customer to each seller they bought something from. So, this Numscript specifies a transfer of $4.99 from the temporary order account to the seller's wallet at @user:U6789:wallet.

Delayed payouts require a little more structure. Instead of paying out automatically when a purchase completes, you will pay out to a special pending account. So, supposing the same scenario as above, you can restructure the transaction as such:

send [USD/2 499] (
  source = @user:U1234:transactions:T1234
  destination = @user:U6789:pending
)

What's the difference? The pending account @user:U6789:pending is not available for withdrawals to the seller's bank account. Instead, set up a cron job to periodically check for transactions older than the delay. Let's say your seller is on a 14-day delay. Then every hour you'll check the pending account with the Formance Ledger API:

/ledger/transactions?destination=destination:U6789:pending

This call requests all transactions on the pending account, and will return a a JSON array of all transactions on that account:

You can then scan the results for stale transactions, paging through the API results as needed:

{
  "cursor": {
    "data": [
      {
        "postings": [
          {
            "amount": 499,
            "asset": "USD",
            "destination": "user:U6789:pending",
            "source": "user:U1234:transaction:T1234"
          }
        ],
        "timestamp": "2022-05-23T13:57:08Z"
      },
      ⋮ //and so on
    ]
  }
}

Once you identify a stale transaction, you can flush it from the pending account to the seller's wallet to mark it as available for withdrawal.

send [USD/2 499] (
  source = @user:U6789:pending
  destination = @user:U6789:wallet
)

From here, the seller can request a withdrawal according to their needs and your withdrawal schedule (which can be set independently of the payout schedule).