Charge an invoice (create transaction)

post

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

Charges a stored payment method against an accounting invoice for the organization associated with the authenticated API key (off-session AR collection). The charge is attempted once against the supplied paymentMethodId. 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 amount to charge the invoice open balance. Credit memos are not applied. If the invoice has installments, you still choose the amount; installment rows are not closed.

Card charges are usually final on this response. Bank charges may return queued then pending — save data.id and poll GET /v2/transactions. See the Charge an invoice guide.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

invoiceId

string

required

length between 1 and 200

The accounting system invoice ID (e.g. the QuickBooks Id, Xero InvoiceID, or Business Central id). This is the value exposed as id on the invoice object.

paymentMethodId

string

required

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

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

amount

number

≤ 999999.99

Optional charge amount. Omit to charge the invoice open balance. Must be > 0, ≤ open balance, max 999999.99, up to 2 decimal places.

sendReceipt

boolean

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

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 invoice, no open balance, payment method not usable for this invoice, 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), or invoice already being charged.

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.