Getting Started with Starks

Send your first authenticated Starks API request and use the workflow guides that match your integration.

Before you send a request

• Generate a Client Secret Key in your Starks dashboard under Developers → API Keys.
• Set your client secret as an environment variable: export STARKS_CLIENT_SECRET="your-client-secret".
• Choose the base URL for the environment you are using.

1. Choose your environment

Use the sandbox URL while you test. Switch to the production URL only when you are ready to send live traffic.

2. Add the standard headers

All requests in the current docs use JSON. Send these headers with each request:

• x_starks_api_key: <your-secret-key>
• Content-Type: application/json

If you call Initialize payout, also add the signature header documented on that endpoint. Use the same secret key from your dashboard to generate that signature.

3. Make your first request

Use Get list of banks as a read-only first call.

export BASE_URL="https://api.starksdevelop.com/"

curl --request GET "${BASE_URL}v1/pay/banks/all" \
  --header "x_starks_api_key: ${STARKS_CLIENT_SECRET}" \
  --header "Content-Type: application/json"

Expected result:

• Success: 200 OK with a JSON response containing the available banks.
• Authentication error: verify that your secret key is valid and the x_starks_api_key header is present.
• Environment error: verify that your BASE_URL matches the environment your key belongs to.

4. Choose the workflow you need

1. Use Accept a payment if you want to create a payin payment link and track the transaction.
2. Use Send a payout if you want to create a beneficiary and transfer funds out.
3. Use Create a currency conversion if you need exchange-rate lookup and conversion history.
4. Use Track settlements if you need to reconcile pending and completed settlement activity.

Optional: Verify bank details before a payout

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

Optional: Troubleshoot common setup issues

• 401 or 403: Recheck your secret key and confirm that you are sending it in the x_starks_api_key header.
• Request succeeds in one environment but fails in another: make sure your base URL matches your key.
• Payout signature errors: sign the exact JSON request body you send with the same secret key you pass in x_starks_api_key, and compare it against the requirements on Initialize payout.