Charge a deposit / prepayment

post

https://api.benjipays.com/v2/transactions/prepayments

Charges a stored payment method with no invoice (unallocated deposit / prepayment) for the organization associated with the authenticated API key. The charge is attempted once against the supplied paymentMethodId. Accounting posts an unallocated payment; apply it to invoices later in QuickBooks / Xero / Business Central.

Xero organizations must send revenueAccountId (the prepayment line account). QuickBooks and Business Central must omit it. The bank account still comes from the gateway.

HTTP 200 means the charge was attempted — read data and meta.effects (a decline is still 200). Setup failures return RFC 7807. Requires organizations:transactions:create and a required Idempotency-Key header.

Omit currency to use the organization home currency. Card charges are usually final on this response. Bank charges may return queued then pending — save data.id and poll GET /v2/transactions.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

paymentMethodId

string

required

^[0-9a-fA-F]{24}$

Stored payment method id to charge. Must belong to this organization and a gateway that supports the charge currency. Pending-verification methods return 400 and cannot be charged.

amount

number

required

≤ 999999.99

Charge amount. Must be > 0, max 999999.99, up to 2 decimal places.

currency

string

^[A-Za-z]{3}$

Charge currency (ISO 4217). Omit to use the organization home currency. For Xero organizations, must be the home currency.

sendReceipt

boolean

Whether to send a receipt email after a successful charge. Omit or true sends a receipt. false skips it.

revenueAccountId

string

length between 1 and 100

Xero only. Account id for the prepayment line (revenue, prepayment, liability, or current asset). Required when the organization is Xero. Do not send it for QuickBooks or Business Central. This is not the gateway bank account.

Headers

X-Request-ID

uuid

Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.

X-Correlation-ID

uuid

Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.

Idempotency-Key

string

required

length between 1 and 255

^[a-zA-Z0-9]+$

Required client-supplied key that makes retries safe for this endpoint. Scoped per actor; cached for 24 hours. Replays return the cached response with X-Idempotency-Replayed: true. Same key with a different body returns 409. Missing key returns 400. In-flight duplicates return 429 with Retry-After. See the Idempotency section in the API overview.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Charge attempted. Inspect meta.effects for charge/accounting/receipt outcomes. Declines and other soft failures still return 200.

400Bad request — missing/invalid Idempotency-Key, body validation failed (type …/validation-error), and/or charge setup failed (invalid payment method, unsupported currency, pending verification, etc.). Soft declines return 200 with meta.effects.charge.status=failed.

401Unauthorized

403Forbidden — missing required OAuth scope (organizations:transactions:create), insufficient live mapping permission on the API key owner (e.g. companyAdmin), and/or free trial ended without billing enabled. Scope, mapping, and billing state are independent gates; see response detail.

404Organization not found

409Idempotency key conflict (same key, different body).

429Too Many Requests (rate limit or idempotency in-flight)

503Idempotency protection is temporarily unavailable, so the charge was not attempted. Retry the same request with the same Idempotency-Key after Retry-After seconds.