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

# Create a workflow execution

> Create an execution of the payment-acceptance workflow through the Payrails API, the first call in every payment.

## Introduction

All operations in Payrails are defined and executed with customized [Workflows](/docs/overview/workflows), which are lists of steps to be performed in sequence. The `payment-acceptance` workflow, for example, is a list of steps for accepting payments, and you must create an execution of this workflow via the Payrails API before initiating a payment.

After creating an execution, you can [Lookup payment options](/reference/lookupaction) to present to your customer.

## Steps

### 1. Make a POST request

Make a `POST` request to the [Create a workflow execution](/reference/createexecution) endpoint.

In your request, make sure to include:

* `merchantReference`: The merchant-provided reference for the execution. This is commonly the identifier of the order in the merchant’s system.

The subsequent actions (refer to Step 3 below) of starting a payment session or looking up payment options can also be included in your request at this time, as part of the `initialActions`.

For example:

```json theme={null}
{
  "initialActions": [
    {
      "action": "lookup",
      "method": "POST",
      "body": {
        "amount": {
          "value": "12.50",
          "currency": "EUR"
        },
        "meta": {
          "country": {
            "code": "DE"
          },
          "customer": {
            "reference": "customer123",
            "country": {
              "code": "DE"
            }
          },
          "clientContext": {
            "osType": "ios",
            "language": "de-DE"
          },
          "allowedPaymentMethods": ["card", "klarna"]
        }
      }
    }
  ],
  "merchantReference": "order_3573894940903",
  "holderReference": "1231905323475",
  "meta": {
    "order": {
      "reference": "order_3573894940903"
    },
    "customer": {
      "reference": "1231905323475",
      "country": {
        "code": "DE"
      }
    },
    "clientContext": {
      "ipAddress": "217.110.239.132",
      "osType": "ios",
      "origin": "https://example.com"
    },
    "allowNative3DS": false
  }
}
```

For the complete request schema, refer to the [Create an execution](/reference/createexecution) API reference.

### 2. Receive response

The API response for creating an execution will include the following:

* `id`: The unique identifier for this execution
* `status`: Business-case dependent set of status tags of this execution.

For the complete response schema, refer to the [Create an execution](/reference/createexecution) API reference.

### 3. Continue with the payment lifecycle

Once you’ve created a workflow execution, you can proceed with the payment in two ways:

* If you know the payment method and/or instrument that should be used (because you included the lookup into the `initialActions` or because it is set by your configurations (e.g. default set by customer):
  * [Authorize a payment](/reference/authorizeaction) with the selected payment method and instrument.
* [Lookup payment options](/reference/lookupaction)
  * This is for cases in which you’ll present payment options to your customer based on rules you’ve configured in the Payrails Portal, and authorize the payment after they’ve selected a payment option and provided an instrument.
* Important: if you have meta fields specified in **Payment options** configuration in the portal, they must be included in the request.

After performing an authorization, you’ll be able to **capture**, **cancel**, **refund**, or **confirm** the payment.


## Related topics

- [Create an execution](/reference/createexecution.md)
- [Billing](/docs/use-cases/billing-use-cases.md)
- [Apple Pay](/docs/orchestration/payment-methods/apple-pay.md)