POST/v1/billing/top-ups

Request a top-up

Creates a pending top-up for a prepaid or trial organisation and returns the payment with the instructions of the payment provider (bank transfer with a reference under the manual provider). The balance is credited once the payment is registered as received.

Scope billing.manage

Body

amountCentsintegerrequiredmin 500max 100000000

Returns

3 fields of the 201 answer

paymentobjectrequired

17 fields

idstringrequired

kindenumrequired

TOP_UPINVOICE_PAYMENT

providerstringrequired

statusenumrequired

PENDINGCOMPLETEDCANCELLED

amountCentsintegerrequired

currencystringrequired

methodenum or nullrequired

BANK_TRANSFEROTHER

referencestringrequired

externalReferencestring or nullrequired

paidAtdate-time or nullrequired

invoiceIdstring or nullrequired

ledgerEntryIdstring or nullrequired

notesstring or nullrequired

requestedByTypeenumrequired

USERAPI_KEYADMINSYSTEM

completedAtdate-time or nullrequired

cancelledAtdate-time or nullrequired

createdAtdate-timerequired

instructionsobject or nullrequired

8 fields

methodstringrequired

beneficiarystringrequired

ibanstringrequired

bicstring or nullrequired

amountCentsintegerrequired

currencystringrequired

referencestringrequired

notestringrequired

redirectUrlstring or nullrequired

Responses

201Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.billing.topUp({ body: { amountCents: 1250, }, });

{ "payment": { "id": "pay_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "kind": "TOP_UP", "provider": "Example", "status": "COMPLETED", "amountCents": 1250, "currency": "EUR", "method": "BANK_TRANSFER", "reference": "PB-2026-0001", "externalReference": "Example", "paidAt": "2026-10-16T09:14:02.000Z", "invoiceId": "inv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "ledgerEntryId": "led_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "notes": "Example", "requestedByType": "USER", "completedAt": "2026-10-16T09:14:02.000Z", "cancelledAt": "2026-10-16T09:14:02.000Z", "createdAt": "2026-10-16T09:14:02.000Z" }, "instructions": { "method": "BANK_TRANSFER", "beneficiary": "Example", "iban": "NL91ABNA0417164300", "bic": "Example", "amountCents": 1250, "currency": "EUR", "reference": "PB-2026-0001", "note": "Example" }, "redirectUrl": "https://example.com/r/Fq3ZtR8w" }

{ "type": "https://docs.postbuddy.nl/errors/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Validation failed", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "errors": [ { "field": "recipient.postalCode", "code": "invalid_string", "message": "Invalid postal code" } ] }