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

# Lookup payment options

> Call the lookup endpoint to resolve which payment methods and instruments to present, from the rules you set in the Payrails Portal.

## Introduction

[Payment Options](/docs/overview/payment-options) are the payment methods and instruments available to a customer in a given context. You configure rules for their availability in the Payrails Portal and then use the lookup endpoint to synchronously determine and present the right payment options to customers on the client side.

## Steps

### 1. Get the execution ID

For your request to the lookup endpoint, you’ll need the ID of the workflow execution. You can find the ID in the response to the creation of this workflow execution, with the key `id`

### 2. Make a POST request

Make a `POST` request to the [Lookup payment options](/reference/lookupaction) endpoint, where `executionId` is the ID from the previous step.

In your request, include:

* `amount.value`: The decimal amount of the major currency unit, in any precision
* `amount.currency`: ISO 3-letter currency code

For example:

```json theme={null}
{
  "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"]
  }
}
```

For the complete request schema, refer to the [Lookup payment options](/reference/lookupaction) API reference.

<Note>
  The payment options available to a customer vary according to context. If the context changes during checkout (for example, the total amount changes), look up the payment options again and refresh the results to ensure the payment methods and instruments displayed to your consumer remain accurate.
</Note>

### 3. Receive the lookup response

If the lookup was successfully executed, you’ll find the following in the response:

* `actionId`: The unique identifier for this capture execution
* `data.paymentCompositionOptions`: This is the list of payment methods and payment instruments that can be used to complete the execution.
* `links`: Links to the next possible actions that can be taken

For example:

```json theme={null}
{
  "name": "lookup",
  "actionId": "1aa0ef20-36cb-4485-b60e-0526c3699014",
  "executedAt": "2022-02-03T14:38:40.557Z",
  "data": {
    "paymentCompositionOptions": [
      {
        "paymentMethodCode": "card",
        "integrationType": "api",
        "description": "Card.",
        "paymentInstruments": [
          {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "card",
            "description": "Personal card.",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "data": {
              "network": "visa",
              "bin": "411111",
              "suffix": "1111",
              "expiryMonth": "10",
              "expiryYear": "2026",
              "holderName": "John Doe"
            },
            "meta": {
              "communityCode": "GAP",
              "userKey": "9890124569"
            }
          }
        ]
      }
    ]
  },
  "links": {
    "execution": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016",
    "authorize": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/authorize"
    }
  }
}
```

<Note>
  By default, the `paymentInstruments` list inside each of the payment methods returned includes only the ones with status `Created` or `Enabled` for the Holder that created the execution. This means that any inactive, expired, or blocked instrument will be excluded to avoid payment rejections.

  To query all the instruments for that holder regardless of their current state, use the [List Instruments API](/reference/listinstruments).
</Note>

For the complete response schema, refer to the [Lookup payment options](/reference/lookupaction) API reference.


## Related topics

- [Lookup payment options](/reference/lookupaction.md)
- [Payment Options](/docs/overview/payment-options.md)
- [iDEAL](/docs/orchestration/payment-methods/ideal.md)