Send a payout

Create a beneficiary, initialize a payout, and confirm the result from payout history.

Before you start

• Generate a Client Secret Key in your Starks dashboard.
• Review Authentication so your x_starks_api_key header and payout signature are ready.
• Gather the beneficiary details you need before you create the payout.

1. Read payout metadata

Use Get payout metadata to confirm the available currencies, payment channels, and providers for payouts.

Read this first so the values you send later match the current payout configuration.

2. Optional: Verify bank details

1. Call Get list of banks to retrieve supported bank codes.
2. Call Bank account enquiry to validate the account number and bank code.
3. Use the verified details when you create the beneficiary.

3. Create the beneficiary

Use Create beneficiary to add the payout recipient to your organization.

Store the returned beneficiary reference so you can use it when you initialize the payout.

4. Initialize the payout

Use Initialize payout to start the transfer to the beneficiary.

This endpoint states that it requires a request signature in addition to your standard authentication header. Sign the exact JSON body you send so the API can verify it. This endpoint states that it requires a request signature in addition to your x_starks_api_key header. Sign the exact JSON body you send with the same secret key so the API can verify it.

5. Confirm the outcome

Use Get payout history to review the status of initialized payouts.

Check this endpoint after submission so your application can confirm whether the payout was accepted and how it progresses over time.

Optional: Work with balances and bulk payouts

• Use Get payout balances when you need the current payout balances for your organization.
• Use Initialize bulk payout when you need to send several payouts in one request.

Optional: Common mistakes

• Initializing a payout before you create the beneficiary record.
• Sending payout values without first checking Get payout metadata.
• Generating the payout signature from a different JSON body than the one you actually send.