Skip to main content
This guide walks through sending a payment to a worker outside of the regular payroll cycle—a bonus, reimbursement, or invoice payment.

​
Prerequisites

​
Create a payment

To send funds, create a payment specifying the worker, amount, and currency: 
curl -X POST https://api.plane.com/v1/payments \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "worker": "wr_abc123",
    "amount": "2500.00",
    "currency": "USD",
    "note": "March design work",
    "reference": "INV-2024-042"
  }'
Response
{
  "id": "pt_ogdEjSnSqNYxtW1sd3pC3hFX"
}
When you omit the date field, Plane schedules the payment for the soonest available date. You can also specify a future date to schedule the payment in advance.

​
Payment options

You can customize several aspects of the payment:
ParameterDescription
accountSend to a specific bank account. Omit to use the worker’s preferred account for the given currency.
dateSchedule for a specific date. Omit for the soonest available date.
referenceA reference visible to the worker (e.g., an invoice number). Plane generates one if omitted.
noteA memo included with the payment, which may appear on the worker’s bank statement.
periodAssociate the payment with a date range (e.g., a service period).
metadataAttach arbitrary key-value data for your own tracking.

​
Check payment status

After creating a payment, retrieve it to see its current status: 
curl https://api.plane.com/v1/payments/pt_ogdEjSnSqNYxtW1sd3pC3hFX \
  -u "YOUR_API_KEY:"

​
Track payment lifecycle with webhooks

Set up webhooks to get notified as the payment progresses:
  • payment.created—the payment was created and is pending
  • payment.updated—the payment status changed (e.g., processing, completed)
This is more efficient than polling the API, especially when you are sending multiple payments.

​
Cancel a payment

If a payment has not been processed yet, you can cancel it:
cURL
curl -X POST https://api.plane.com/v1/payments/pt_ogdEjSnSqNYxtW1sd3pC3hFX/cancel \
  -u "YOUR_API_KEY:"
You can only cancel a payment before it has been processed. Once funds are in transit, the payment cannot be cancelled.

​
Next steps

Payment requests

Let workers submit payment requests for approval.

Payments API

Full reference for the payments resource.