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

1. Session

   POST /orders creates an order and a payment session at the chosen provider. The response contains a redirectUrl to the payment page.

2. Payment at the provider

   The customer pays. The provider processes the transaction on its side.

3. 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.

Payment channels

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

{ "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:

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.

Payment providers

The list of supported providers and their configuration.