Send a payment

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

Prerequisites

A Plane API key (set up authentication)
An active worker to pay (see Onboard a contractor)
The worker must have a bank account configured in Plane

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"
  }'

const response = await fetch("https://api.plane.com/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer YOUR_API_KEY`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    worker: "wr_abc123",
    amount: "2500.00",
    currency: "USD",
    note: "March design work",
    reference: "INV-2024-042",
  }),
});

const { id } = await response.json();
console.log("Payment created:", id);

import requests

response = requests.post(
    "https://api.plane.com/v1/payments",
    auth=("YOUR_API_KEY", ""),
    json={
        "worker": "wr_abc123",
        "amount": "2500.00",
        "currency": "USD",
        "note": "March design work",
        "reference": "INV-2024-042",
    },
)

payment = response.json()
print("Payment created:", payment["id"])

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:

Parameter	Description
`account`	Send to a specific bank account. Omit to use the worker’s preferred account for the given currency.
`date`	Schedule for a specific date. Omit for the soonest available date.
`reference`	A reference visible to the worker (e.g., an invoice number). Plane generates one if omitted.
`note`	A memo included with the payment, which may appear on the worker’s bank statement.
`period`	Associate the payment with a date range (e.g., a service period).
`metadata`	Attach 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:"

const response = await fetch(
  "https://api.plane.com/v1/payments/pt_ogdEjSnSqNYxtW1sd3pC3hFX",
  {
    headers: { Authorization: `Bearer YOUR_API_KEY` },
  }
);

const payment = await response.json();
console.log("Status:", payment.status);

import requests

response = requests.get(
    "https://api.plane.com/v1/payments/pt_ogdEjSnSqNYxtW1sd3pC3hFX",
    auth=("YOUR_API_KEY", ""),
)

payment = response.json()
print("Status:", payment["status"])

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.

Getting Started

CLI

Workers

Payments

Prerequisites

Create a payment

Payment options

Check payment status

Track payment lifecycle with webhooks

Cancel a payment

Next steps

Payment requests

Payments API

​Prerequisites

​Create a payment

​Payment options

​Check payment status

​Track payment lifecycle with webhooks

​Cancel a payment

​Next steps

Payment requests

Payments API

Prerequisites

Create a payment

Payment options

Check payment status

Track payment lifecycle with webhooks

Cancel a payment

Next steps