# How payments work

> The Payment and PaymentSession objects, payment statuses, and which integration to pick.

Source: https://docs.borga.is/payments

Two objects drive every one-off payment:

- A **Payment** is the money: an `amount`, a `currency`, a `status`, and the outcome details (card brand, last four digits, failure reason, refunded amount). Its id starts with `pay_`.
- A **PaymentSession** is the checkout that collects it: which payment methods are offered, where to send the payer afterwards, the language, and whether it is hosted or embedded. Its id starts with `ps_`.

Creating a session with an `amount` creates the payment for you. That is the normal path. You can also create a payment first and attach a session to it with `payment`, for example to keep one payment id across a retried checkout.

## Lifecycle

```
POST /v1/payment_sessions  →  Payment: created, Session: open
payer completes checkout    →  Payment: succeeded | failed, Session: complete
24 hours pass unpaid        →  Session: expired
POST /v1/refunds            →  Payment: refunded_amount grows, then status refunded
```

### Payment status

| Status | Meaning |
| --- | --- |
| `created` | Awaiting the payer. Also the state of a bank invoice until the bank confirms payment. |
| `processing` | Authorised, awaiting final confirmation from the processor. Brief for cards. |
| `succeeded` | Charged. Fulfil the order. |
| `failed` | Declined or authentication failed. `failure_reason` says why. The payer can try again in the same session. |
| `canceled` | Cancelled before completion. |
| `refunded` | Fully refunded. Partial refunds keep `succeeded` and increase `refunded_amount`. |

### Session status

| Status | Meaning |
| --- | --- |
| `open` | The payer can still pay. Sessions live for 24 hours. |
| `complete` | A payment attempt finished, or a bank invoice was issued. |
| `expired` | Nobody paid within 24 hours. Create a new session. |

## Amounts and currencies

Amounts are integers in the currency's smallest unit, paired with an ISO 4217 `currency`. Icelandic króna has no minor unit in circulation, so `1990` is 1.990 kr. Euro and the other currencies use cents: `1990` is €19.90. Supported currencies: _(Currencies table: see the HTML page)_

Amounts must be at least 1 and at most 2,000,000,000.

## Hosted or embedded?

| | Hosted | Embedded |
| --- | --- | --- |
| Where the payer pays | `checkout.borga.is` | A modal on your page, loaded by borga.js |
| Integration | One server call and a redirect | Server call plus a few lines of browser code |
| Payment methods | Cards, wallets, bank invoice | Cards and wallets |
| Needs a publishable key | No | Yes |
| Best for | Most shops, invoices, links you send by email | Checkouts that must not leave the page |

Both use the same session object and the same webhooks. Start with [hosted checkout](/payments/hosted-checkout); switch to [embedded](/payments/embedded-checkout) if you need it.

## Fulfilment: webhooks, not redirects

The redirect back to your `return_url` tells you the payer finished the checkout UI, nothing more. A bank invoice is paid days later, a slow 3-D Secure flow may still be settling, and a payer can close the tab before the redirect. Fulfil from the `payment.succeeded` webhook and use the return page only to show status. See [Webhooks](/webhooks).

## Saving cards and subscriptions

A session can ask Borga to save the card for later (`save_payment_method: true`) or start a subscription when it succeeds (`subscription`). Both attach the card to a Customer as a PaymentMethod. See [Saved cards](/payments/saved-cards) and [Subscriptions](/billing/subscriptions).

## Invoices

When a payment succeeds and you have an accounting provider connected, Borga books a paid sales invoice there and links it to the payment as an Invoice object. Refunds produce credit notes. See [Invoicing](/billing/invoicing).