For developers · 2.0.0-alpha

Contractor payouts API, straight from your code

Invite workers, send batch payments and react to payment and KYC events from your own product. Contractors get paid into their Ontop Global Account.

Read the docsRequest API access
create-paylistwebhooks
1POST/payment-agent/paylists
2Authorization:Bearer eyJhbGciOi...
3{
4"idempotence_key":"7f3e9a1c0b2d..."
5// 24 contractors, 6 countries, one run
6}
→acceptedprocessing asynchronously
Webhook events
CLIENT_WALLET_TOP_UPBalance ready for the run
PAYMENTPENDING · 24 payments
PAYMENTSUCCESS · 24 of 24 paid
Ontop
Payout received
+$2,400.00
Bogotá, Colombia · example
// how a payout flows

Three calls and a webhook

Your system
01
auth

Authenticate

Get a bearer token and use it on every request.

02
GET /client-wallet/clients/100/wallet

Check your balance

Confirm your balance covers the run before you send it.

03
paylists / create

Create a paylist

Group every payment into one batch that processes asynchronously.

04
webhook: PAYMENT

Get notified

Register your endpoint once with POST /webhooks/clients, then hear about every status change. No polling.

Payouts that ship
with your code.

Approve in your product. Paid in their Global Account.

// endpoints

Everything a payout needs, in one API

Resource
Endpoint
What it does
Auth
POST /login/login/v2
Returns the bearer token for every request
Workers
POST /contract/workers/inviteWorkersBulkLocked
Invites a full roster in one call
Agreements
POST .../agreements/{agreementId}/status
Inactivates an agreement when work ends
Balance
GET /client-wallet/clients/100/wallet · GET /client-wallet/clients/transactions
Confirms funds before a run
Paylists
POST /payment-agent/paylists
Creates a batch, processed asynchronously
Webhooks
POST /webhooks/clients
Subscribes to PAYMENT, KYC and CLIENT_WALLET_TOP_UP
Payment states
PENDINGSUCCESSFAILUREREJECTED

Every payment moves through these states, and each change reaches you as a PAYMENT webhook.

Safe retries

Two fields keep a retry from paying twice

{
"idempotence_key":"7f3e9a1c0b2d4e5f..."1
"payments": [ {
"description":"Invoice 0042, October"2
other payment fields, per the docs
} ]
}
1

One key per paylist

You generate it: 32 characters, unique. A retried request isn't created twice.

2

One description per payment

Same amount, email and description counts as a duplicate.

API or platform? Pick your way in

Use the API if:

  • You pay people from inside your own product.
  • Approvals already live in your tools.
  • You want payout status as events, not emails.
Read the docs →

Use the platform if:

  • You run payouts for a team, not a marketplace.
  • Nobody on the team writes code.
  • One approval per payment run is all you need.
See the platform →
Global Workforce Engine

What you don't have to build

The API hands you the hard parts of paying people abroad, so your sprint goes to your product.

Bank integrations, country by country
→
One paylist call
Your own identity checks
→
KYC events from Ontop
Onboarding contractors one by one
→
Invite a whole roster in one call
“Where's my payment?” tickets
→
Status as webhooks
Both sides of one call

You approve in your product. They get paid.

Your productOctober payouts
Sofía MartínezReady
Lucas JohnsonReady
+22 more contractorsReady
Approve 24 payouts
POST /payment-agent/paylists
Ontop
Payment received
Your October invoice was paid into your Global Account.
now
Ontop
Identity verified
You're all set to get paid.
2d
What your contractor sees
// faq

Questions about the Ontop API

Does Ontop have an API?
Yes. The Ontop API covers workers, your account balance and transactions, paylists and payments, webhooks and agreement inactivation. Documentation lives at developer.getontop.com.
How does authentication work?
You log in with your API credentials to get a bearer token, then send it on every request.
Can I send payments in bulk?
Yes. Paylists group payments into one batch that processes asynchronously. Use a unique 32-character idempotence key per paylist and a distinct description per payment to keep retries safe.
Which webhooks are available?
Payment, KYC and balance top-up events: a payment changes status, a worker completes verification or funds land in your account.
How do I get API access?
Talk to our team and we'll enable API credentials for your company account. The docs include a demo environment for testing.
Do I need the API to use Ontop?
No. You can run hiring, contracts and payments from the Ontop platform without writing code.
How do contractors receive payouts sent through the API?
Into their Ontop Global Account, like any Ontop payout.

Ship payouts in your next sprint

Read the docs, then talk to our team about API access.

Read the docsRequest API access