> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a payment

> Send a one-off payment to a worker using the Plane API.

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](/reference/authentication))
* An active worker to pay (see [Onboard a contractor](/guides/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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "pt_ogdEjSnSqNYxtW1sd3pC3hFX"
}
```

<Note>
  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.
</Note>

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.plane.com/v1/payments/pt_ogdEjSnSqNYxtW1sd3pC3hFX \
    -u "YOUR_API_KEY:"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  import requests

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

  payment = response.json()
  print("Status:", payment["status"])
  ```
</CodeGroup>

## Track payment lifecycle with webhooks

Set up [webhooks](/guides/setting-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:

```bash cURL theme={null}
curl -X POST https://api.plane.com/v1/payments/pt_ogdEjSnSqNYxtW1sd3pC3hFX/cancel \
  -u "YOUR_API_KEY:"
```

<Warning>
  You can only cancel a payment before it has been processed. Once funds are in transit, the payment cannot be cancelled.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Payment requests" icon="envelope-open-dollar" href="/reference/payment-requests/object">
    Let workers submit payment requests for approval.
  </Card>

  <Card title="Payments API" icon="book" href="/reference/payments/object">
    Full reference for the payments resource.
  </Card>
</CardGroup>