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

# Web SDK v5 headless integration

> Use the Web SDK v5 `api()` and `query()` methods to update or delete stored instruments and read session configuration from the client.

## API Methods

The Payrails SDK provides REST API methods through the `api()` function for making calls to payrails backend directly from the client.

### `api`

| Parameter | Type | Description |
| - | - | - |
| `config` | `ApiConfig<TReq> & { operation: TOperation }` | Configuration object containing operation details |

**Returns:** `Promise<Operations[TOperation]['responseType']>`

### Available Operations

| Operation | Method | Description | Required Parameters |
| :- | :- | :- | :- |
| `deleteInstrument` | DELETE | Deletes a stored payment instrument | `resourceId` |
| `updateInstrument` | PATCH | Updates properties of an existing payment instrument | `resourceId`, `body` |

#### Delete Payment Instrument

```typescript theme={null}
const result = await payrails.api({
  operation: "deleteInstrument",
  resourceId: "instrument_id_here",
});
```

**Response:** `DeleteInstrumentResponse`

| Field | Type | Description |
| - | - | - |
| `success` | `boolean` | Indicates if the deletion was successful |

#### Update Payment Instrument

```typescript theme={null}
const result = await payrails.api({
  operation: "updateInstrument",
  resourceId: "instrument_id_here",
  body: {
    status: "enabled",
    default: true,
    merchantReference: "your_reference",
    networkTransactionReference: "network_ref",
  },
});
```

**Request Body Fields:**

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `status` | `'enabled'`\| `'disabled'` | No | Enable or disable the instrument |
| `networkTransactionReference` | `string` | No | Network transaction reference |
| `merchantReference` | `string` | No | Merchant reference identifier |
| `paymentMethod` | `'applepay'` \|`'card'`\|`'googlepay'`\|`'paypal'` | No | Payment Method Type |
| `default` | `boolean` | No | Set as default payment instrument |

**Response Fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Unique instrument identifier |
| `createdAt` | `string` | Creation timestamp |
| `holderId` | `string` | Holder identifier |
| `paymentMethod` | `PAYMENT_METHOD_CODES` | Payment method type |
| `status` | `PAYMENT_INSTRUMENT_STATUS` | Current status |
| `data` | `INSTRUMENT_OBJECT` | Payment method specific data |

## Query Methods

The query system allows you to retrieve configuration data and SDK state information without making external API calls.

### `query`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `key` | `K extends keyof ConfigurationQueryTypes` | Yes | The configuration key to query |
| `params` | `Record<string, any>` | No | Optional parameters for specific queries |

**Returns:** `ConfigurationQueryTypes[K]['returnType'] | null`

### Available Query Keys

| Query Key | Parameters | Return Type | Description |
| :- | :- | :- | :- |
| `holderReference` | | `string` | Retrieves the holder reference for the current session |
| `amount` | | `PayrailsAmount` | Gets the current payment amount configuration |
| `executionId` | | `string`\|`undefined` | Retrieves the current workflow execution ID |
| `binLookup` | | `Links`\|`undefined` | Gets the BIN lookup service endpoint |
| `instrumentDelete` | | `Links`\|`undefined` | Gets the instrument deletion endpoint |
| `instrumentUpdate` | | `Links`\|`undefined` | Gets the instrument update endpoint |
| `paymentMethodConfig` | `paymentMethodCode: PAYMENT_METHOD_CODES.CODE \| 'all' \| 'redirect'` | `StorablePaymentCompositionOption`\| `StorablePaymentCompositionOption[]`\|`undefined` | Retrieves configuration for a specific payment method |
| `paymentMethodInstruments` | `paymentMethodCode: string` | `StoredPaymentInstrument<CardMetadata`\|`PayPalMetadata[]`\|`undefined` | Gets stored instruments for a specific payment method |

### Query Examples

#### Basic Configuration Queries

```typescript theme={null}
// Get holder reference
const holderRef = payrails.query("holderReference");

// Get current amount
const amount = payrails.query("amount");

// Get execution ID
const executionId = payrails.query("executionId");
```

#### Link Queries

```typescript theme={null}
// Get API endpoints
const binLookupLink = payrails.query("binLookup");
const deleteLink = payrails.query("instrumentDelete");
const updateLink = payrails.query("instrumentUpdate");
```

#### Payment Method Queries

```typescript theme={null}
// Get payment method configuration
const cardConfig = payrails.query("paymentMethodConfig", {
  paymentMethodCode: "card",
});

// Get payment method config for all available payment methods
const cardConfig = payrails.query("paymentMethodConfig", {
  paymentMethodCode: "all",
});

// Get payment method config for all redirect type payment methods
const cardConfig = payrails.query("paymentMethodConfig", {
  paymentMethodCode: "redirect",
});

// Get stored instruments for a payment method
const cardInstruments = payrails.query("paymentMethodInstruments", {
  paymentMethodCode: "card",
});
```

## Error Handling

All API methods may throw `PayrailsError` exceptions. It's recommended to wrap API calls in try-catch blocks:

```typescript theme={null}
try {
  const result = await payrails.api({
    operation: "deleteInstrument",
    resourceId: "instrument_id",
  });
  console.log("Instrument deleted successfully:", result.success);
} catch (error) {
  if (error instanceof PayrailsError) {
    console.error("Payrails API error:", error.message);
    // Handle specific error codes
  } else {
    console.error("Unexpected error:", error);
  }
}
```

Query methods return `null` instead of throwing errors when data is not found:

```typescript theme={null}
const amount = payrails.query("amount");
if (amount === null) {
  console.log("Amount not configured");
} else {
  console.log("Current amount:", amount);
}
```

## Examples

### Complete Instrument Management Example

```typescript theme={null}
// Initialize Payrails client
const payrails = Payrails.init(initResponse, options);

// Query for stored card instruments
const cardInstruments = payrails.query("paymentMethodInstruments", {
  paymentMethodCode: "card",
});

if (cardInstruments && cardInstruments.length > 0) {
  const instrument = cardInstruments[0];

  // Update the instrument
  try {
    const updatedInstrument = await payrails.api({
      operation: "updateInstrument",
      resourceId: instrument.id,
      body: {
        status: "enabled",
        default: true,
      },
    });

    console.log("Instrument updated:", updatedInstrument);
  } catch (error) {
    console.error("Failed to update instrument:", error);
  }
}
```

## Integration Notes

| Aspect | Description |
| - | - |
| **Authentication** | All API calls are automatically authenticated using the SDK's internal token management |
| **Resource IDs** | When working with payment instruments, ensure you have the correct `resourceId` from previous queries or operations |
| **Error Handling** | Always implement proper error handling for API calls, as network issues or invalid requests can cause exceptions |
| **Query Performance** | Query methods are fast local operations that don't make network requests, making them suitable for frequent calls |
| **Parameter Validation** | Some queries require specific parameters (like `paymentMethodCode`). Missing required parameters will result in `null` returns with warning logs |

## Best Practices

| Practice | Recommendation |
| - | - |
| **Cache Query Results** | For frequently accessed configuration data, consider caching query results to improve performance |
| **Handle Null Returns** | Always check for `null` returns from query methods before using the data |
| **Use TypeScript** | Use the provided TypeScript types for better development experience and error prevention |
| **Error Recovery** | Implement appropriate error recovery strategies for failed API operations |
| **Logging** | Monitor API usage and errors through your application logging system for better debugging and maintenance |


## Related topics

- [Web SDK v5 Elements](https://docs.payrails.com/docs/sdks/web-v5-legacy/elements.md)
- [Web SDK v5 Drop-in](https://docs.payrails.com/docs/sdks/web-v5-legacy/drop-in.md)
- [Web SDK v5 Secure Fields](https://docs.payrails.com/docs/sdks/web-v5-legacy/secure-fields.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.