> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Payment sessions, channels, and the payment lifecycle.

A payment is created automatically when an order is placed. The `/payments/sessions` endpoints are administrative operations and require a Bearer token plus access to the order's shop.

## Lifecycle

<Steps>
  <Step title="Session">
    `POST /orders` creates an order and a payment session at the chosen provider. The response contains a `redirectUrl` to the payment page.
  </Step>

  <Step title="Payment at the provider">
    The customer pays. The provider processes the transaction on its side.
  </Step>

  <Step title="Webhook">
    The provider sends a notification to `POST /payments/webhooks/{provider}/{shopId}/{webhookSecret}`. The API verifies the signature and updates the order status. See [Webhooks](/en/guides/webhooks).
  </Step>
</Steps>

## Payment channels

The method and channel are passed in a single field, separated by a colon:

```json theme={null}
{ "paymentMethodName": "imojeTransfer:blik" }
```

Channel names and behavior depend on the adapter and the services enabled on the merchant account. Use values returned for the configured method; omitting a channel generally leaves selection to the provider. Do not assume that `blik`, `card`, or `pbl` is supported by every provider.

## Session lifetime

| Payment type              | Session TTL |
| ------------------------- | ----------- |
| Instant (BLIK, card, SMS) | 30 minutes  |
| Traditional transfer      | 14 days     |

Expired sessions are marked and cleaned up periodically. Check status with `GET /orders/payment-status/{orderId}`; it requires a Bearer token for a user who can access the shop. Buyers use the trimmed public status endpoint with the secret capability token returned at order creation.

## Retrying a payment

If a payment failed or expired, an authenticated shop member can create a new session for that order:

```bash theme={null}
curl -X POST https://api.itemshop.dev/api/v2/orders/retry-payment/<orderId> \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodName": "imojeTransfer:card" }'
```

## Free orders

When a discount reduces the amount to zero, the order bypasses the payment gateway and enters plugin fulfillment. The response contains `free: true`, the current status, a `statusToken`, and the status-page URL. Delivery may wait for plugin connectivity or for the player to be online when the product requires it.

<Card title="Payment providers" icon="building-columns" href="/en/guides/payment-providers">
  The list of supported providers and their configuration.
</Card>