Skip to main content

Payouts

A Payout is a payment that can be attached to a payment-request. Once the payer has paid a payment, funds can be forwarded to the beneficiary in the payout.

Hubpay provides a seamless way to initiate payouts to beneficiaries after receiving payments, allowing you to automate the entire payment flow from collection to disbursement.

How payouts work​

Payouts are initiated after a payment has been received and processed. The payout process involves:

  1. Initiating the payout with beneficiary details, payoutBeneficiaryId, payoutReference, and purpose of payment
  2. Processing the payout through various states (pending_approval, initiated, paid, or failed)
  3. Receiving status updates via webhooks as the payout progresses
  4. Transferring funds to the beneficiary when the payout is paid

Payout lifecycle​

A payout moves through several states during its lifecycle:

StateDescription
Pending ApprovalPayment is awaiting checker approval (only when maker checker is enabled on the account)
InitiatedPayment has been initiated and is being processed
PaidPayment has been successfully completed and funds have been paid to the beneficiary
FailedPayment failed due to error or rejection

Tracking payout status​

You can track the status of a payout using:

Set up webhooks to receive real-time notifications when a payout changes state:

  • v1.collection.payment_request.payment.payout.pending_approval - Payment is awaiting checker approval
  • v1.collection.payment_request.payment.payout.initiated - Payment has been initiated
  • v1.collection.payment_request.payment.payout.paid - Payment has been successfully completed
  • v1.collection.payment_request.payment.payout.failed - Payment failed due to error or rejection

For more details on payout webhook events, see the Payout Events documentation.

Each webhook includes details about the payout, including:

{
  "paymentRequestId": "8a282576-18c0-4c0e-b158-44b92eda1afe",
  "paymentId": "9b393687-29d1-5d1f-c269-55c03fda2bfb",
  "transactionReference": "TX123456789"
}

2. API lookup​

You can also query the API to get the current status of a payout using the Get Payment for Payment Request endpoint.

Maker Checker approval​

If maker checker is enabled on your account, payouts will require approval before they are initiated:

  1. A maker (initiator) creates the payout
  2. The payout enters the "pending_approval" state
  3. A checker (approver) must review and approve the payout through the corporate suite portal (this approval cannot be done through the API)
  4. Once approved, the payout moves to the "initiated" state

If maker checker is not enabled, payouts will move directly to the "initiated" state after creation.