Balance Payments API

Record an external balance payment (cash, cheque, card taken outside Seaty, or bank transfer) against an event, with idempotency so a retried request never records it twice. Requires the write:balance_payments scope.

This is the API's one write operation. It records an external balance payment, money taken outside Seaty (cash on the door, a cheque, a card machine that is not Seaty's, or a bank transfer), against an event. It runs the same validation and sends the same receipt email as recording a payment by hand in the Seaty admin tools.

It does not take card payments or move money. It records that a payment happened elsewhere, so your Seaty figures reflect reality.

Method	Path	Scope
POST	`/v1/events/{id}/balance-payments`	`write:balance_payments`

A key without the write:balance_payments scope receives 403 forbidden.

The request

Send a JSON body and an Idempotency-Key header (required, see below):

curl -X POST "https://developer.seaty.co.uk/v1/events/1024/balance-payments" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d9c2f10-7e8a-4c2b-9a1e-2f6b3c8d5a01" \
  -d '{
    "payee_email": "buyer@example.com",
    "amount": 1500,
    "type_id": 1,
    "notes": "Cash on the door",
    "is_refund": false
  }'

Body field	Type	Required	Description
`payee_email`	string	yes	Email of someone who already has an order on this event.
`amount`	integer	yes	Amount in pence. Always positive: set `is_refund` for a refund.
`type_id`	integer	yes	Payment method: `1` cash, `2` cheque, `3` card (taken outside Seaty), `4` bank transfer.
`notes`	string	no	An optional note stored against the payment.
`is_refund`	boolean	no	`true` to record a refund instead of a payment. Defaults to `false`.
`date_payment_made`	string (date)	no	ISO date the payment was made. Defaults to today.

Two rules it enforces

These are the same safeguards as the admin tools:

The payee must already have an order on the event. You cannot record a payment for an email that has never ordered. If you try, you get 422 unprocessable_entity.
A refund cannot exceed the total ever paid by that payee on the event. An over-refund returns 422 unprocessable_entity.

Idempotency: never charge twice

The Idempotency-Key header is required. Generate a unique value (a UUID is ideal) for each distinct payment you intend to record, and reuse the same key if you have to retry after a timeout or network error.

If a request with a key succeeds, recording the payment, then a retry with the same key returns the original payment again rather than recording a second one.
If a request is still in flight when a duplicate arrives, the duplicate gets 409 conflict (the first is still processing).
A failed request (for example a validation error) does not consume the key, so you can fix the problem and retry with the same key.

Always send a fresh key for a genuinely new payment, and the same key when retrying one.

The response

On success you get back the recorded payment:

{
  "id": 90233,
  "guid": "f1c2...",
  "event_id": 1024,
  "payee_email": "buyer@example.com",
  "amount": 1500,
  "type_id": 1,
  "is_refund": false,
  "date_payment_made": "2026-06-04T00:00:00Z",
  "notes": "Cash on the door"
}

Field	Type	Description
`id`	integer	The new payment's id.
`guid`	string \| null	Its public reference.
`event_id`	integer	The event it was recorded against.
`payee_email`	string \| null	The payee.
`amount`	integer	Amount in pence, always positive.
`type_id`	integer \| null	The payment method code.
`is_refund`	boolean	Whether it was a refund.
`date_payment_made`	string	When the payment was made (ISO 8601).
`notes`	string \| null	Any note recorded.

The payee is also sent the usual Seaty payment receipt email, exactly as if the payment had been recorded by hand.

Recording a refund

Set is_refund to true and keep amount positive:

{
  "payee_email": "buyer@example.com",
  "amount": 500,
  "type_id": 4,
  "is_refund": true,
  "notes": "Refunded by bank transfer"
}

A balance refund does not refund a card payment. To refund money that was taken by card through Seaty, use Cancel Order in the admin tools instead.

Reading payments back

Whatever you record here appears in an order's payments (when it can be linked to a specific order) and contributes to the order's amount_paid / balance. The two halves, recording and reading, are designed to reconcile.

Need help? Email support@seaty.co.uk.