Charge an invoice

Most invoices are paid automatically when they finalise — Paylera uses the customer’s default payment method. Sometimes you need to drive the payment yourself.

Automatic charging

When an invoice transitions from draft → open, Paylera schedules a payment using the configured method (subscription default, falling back to customer default). You don’t need to call anything. The payment goes through its FSM and emits the corresponding events.

Manual charge

For ad-hoc invoices (or to retry after a failure):

POST /v1/invoices/{id}/pay
Idempotency-Key: <uuid>
{ "payment_method_id": "pm_…" }

If payment_method_id is omitted, the invoice’s default applies.

The response includes the resulting payment_id and its current status:

{
  "payment_id": "pay_…",
  "status": "succeeded",
  "amount": "115.67",
  "currency": "USD"
}

If the payment is requires_action, the response also includes a next_action field — see Handle 3DS / SCA.

Charge against a wallet

POST /v1/invoices/{id}/pay
{ "source": "wallet" }

Settles the invoice from the customer’s wallet in the matching currency. Fails with wallet.insufficient_funds if the balance is below amount_due.

To pay partially from the wallet and the rest from a card:

POST /v1/invoices/{id}/pay
{
  "splits": [
    { "source": "wallet", "amount": "50.00" },
    { "source": "payment_method", "payment_method_id": "pm_…" }
  ]
}

Charge against a customer balance only

To apply a customer’s wallet balance without taking a card payment for the rest, set partial: true:

POST /v1/invoices/{id}/pay
{ "source": "wallet", "partial": true }

The wallet covers what it can; the invoice transitions to partially_paid if there’s a remainder.

Retrying a failed payment

If the original payment is failed and the invoice is still open:

POST /v1/invoices/{id}/pay
{ "payment_method_id": "pm_new_…" }

Each retry creates a new payment object linked to the same invoice. The invoice carries payments: [pay_1, pay_2, …] — you can see the attempt history.

Marking uncollectible

After dunning gives up, you may want to mark the invoice as bad debt:

POST /v1/invoices/{id}/mark-uncollectible
{ "reason": "customer_unreachable" }

This transitions the invoice to uncollectible, halts dunning, and posts the appropriate ledger entry (write-off). It does not cancel the subscription — that’s a separate decision.

Voiding an unpaid invoice

If the invoice is open and no payment has succeeded against it:

POST /v1/invoices/{id}/void
{ "reason": "billing_error" }

The invoice transitions to void. Cannot be reopened. Issue a replacement if needed.

What you’ll never need to do

• Compute the charge yourself. The invoice carries amount_due; use it.
• Touch the provider. Paylera calls Stripe / PayPal / Adyen on your behalf.
• Manage 3DS state. The next_action is structured; redirect the customer to the URL or render the challenge — the rest is automatic.

Webhook events

Event	When
payment.created	A new payment attempt started.
payment.requires_action	3DS / SCA required; see next_action.
payment.succeeded	Payment captured.
payment.failed	Payment failed; reason in last_error.
invoice.paid	Invoice fully paid.
invoice.payment_failed	A payment attempt against this invoice failed.