> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Payment Status > Reference the payment lifecycle statuses used across Payrails flows. Once an operation of a specific [Operation Type](/docs/resources/payments/operation-types) was executed, and we interpreted its [Result Code](/docs/resources/payments/operation-results), we are ready to change the status of the actual payment. In case the operation we executed on the payment wasn't successful, the status of the payment shouldn't be changed. However, if the result of the operation is `Unknown`, we must change the status of the payment to `Unknown` and act fast to solve the situation so that we are able to either move the payment back to the previous status or to the new one. In case the payment status is `Failed`, there will be more information about the reason in the operation result field. You can find more information on the [Result Codes](/docs/resources/payments/operation-results) page. | Code | Description | | - | - | | Created | Initial state. Payment is created but not yet executed. | | Pending | An action is pending, either on the user, the provider, or us. | | Unknown | There was a problem that left the payment in an unknown state. This situation should be resolved as soon as possible. | | Failed | The payment failed because of a reason specified in another field. | | Expired | The payment was waiting for an action for too long. Time should be configured per merchant. | | Preauthorized | The payment was preauthorized successfully by the provider. Needs a subsequent Capture operation to move the funds. | | Authorized | The payment was authorized successfully by the provider. | | Canceled | Two-step payment was canceled (or voided) successfully by the provider. | | Captured | Two-step payment was captured successfully in the provider. | | Settled | Whenever a provider informed us that the payment is settled. Not all providers have a notification for this, so this status may be skipped. | | Refunded | The payment was successfully refunded by the provider. This status is only present if there was a full refund. For partial refunds, the status remains as it was before but refunds are found in the operation list. | | Chargeback | Payment has a chargeback from the user. | | ChargebackReversed | The payment was chargebacked, but we managed to reverse it after a dispute. | The following is the state machine that illustrates how a payment status can evolve with time after many operations happen to it. Payment state machine: a payment starts as Created and moves through Pending and Authorized to Captured, then optionally Refunded; it can instead end as Failed, Expired, or Canceled, and any state can move to and from Unknown ## Related topics - [Payments](/docs/resources/payments/index.md) - [Triggers](/docs/orchestration/workflow-studio/triggers.md) - [Refund a payment](/docs/orchestration/payment-acceptance/refund-a-payment.md)