Payments

A payment represents one attempt to charge a customer. An invoice may have multiple payments (a failure followed by a retry).

Object

{
  "id": "pay_…",
  "object": "payment",
  "invoice_id": "inv_…",
  "customer_id": "cus_…",
  "payment_method_id": "pm_…",
  "provider": "stripe",
  "provider_id": "pi_…",
  "status": "succeeded",
  "amount":   "115.67",
  "currency": "USD",
  "amount_settled": "115.67",
  "settlement_currency": "USD",
  "fx_rate": null,
  "captured_at":  "2026-05-06T00:01:23Z",
  "settled_at":   "2026-05-08T18:00:00Z",
  "next_action":  null,
  "last_error":   null,
  "refunds": [],
  "metadata": {},
  "created_at": "2026-05-06T00:01:00Z",
  "updated_at": "2026-05-06T00:01:23Z"
}

Status

pending, processing, requires_action, succeeded, failed, canceled, refunded, partially_refunded, charged_back.

See Status reference for the FSM.

Endpoints

Method	Path	What
POST	/v1/invoices/{id}/pay	Initiate or retry a payment.
GET	/v1/payments/{id}	Retrieve.
POST	/v1/payments/{id}/cancel	Cancel a pending / requires_action payment.
POST	/v1/payments/{id}/refunds	Refund (full or partial).
GET	/v1/payments/{id}/action-url	Get a hosted-action URL when status: requires_action.
GET	/v1/payments	List + filter.

next_action

Populated when status: requires_action. Two shapes:

{ "type": "redirect_to_url", "url": "https://hooks.paylera.io/3ds/…" }

{
  "type": "use_provider_sdk",
  "provider": "stripe",
  "payment_intent_client_secret": "pi_…_secret_…"
}

See Handle 3DS / SCA.

last_error

Populated when status: failed. Stable shape:

{
  "code": "card_declined",
  "decline_code": "insufficient_funds",
  "provider_message": "Your card has insufficient funds.",
  "user_message": "Your card was declined.",
  "is_retriable": true,
  "retriable_after": "2026-05-09T00:00:00Z"
}

is_retriable: true means the dunning engine will retry; you don’t need to. false means the customer must update their method.

Refunds

POST /v1/payments/{id}/refunds
{ "amount": "25.00", "reason": "order_change" }

Refunds against a payment cannot exceed the payment’s amount. Each refund creates a refund object linked to the payment.

Webhook events

payment.created, payment.requires_action, payment.action_completed, payment.processing, payment.succeeded, payment.failed, payment.canceled, payment.settled, payment.charged_back, payment.dispute_won, payment.dispute_lost.