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

# Tokenize cards with Secure Fields

> Collect card data in Payrails-hosted iframe fields and exchange it for a token, keeping cardholder data out of your own front end.

Tokenization is the process of collecting sensitive payment information and returning a short-term, single-use token that represents this information. There are many ways of tokenizing card data, in this page we will look into tokenization with our Secure Fields SDK. For more about tokenization and Payrails Token Vault, read this [guide](/docs/overview/vault) first.

'Secure Fields' is a highly customizable payment form, which allows customers to enter their payment details directly on your checkout page or in your app. We collect and process this sensitive information directly and exchange it for a secure token. You can then use this token to request a payment, without having to process or store any sensitive information yourself.

<img className="float-left mr-4 mb-1 mt-0 rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-1.png?fit=max&auto=format&n=knNnlxc2J__TB9tW&q=85&s=47365ddeeadfb69956f1bf2cc614b179" width="304" alt="Tokenize cards with secure fields 1" data-path="images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-1.png" />

Secure Fields uses iframes for handling payment information, so you remain PCI-compliant. Your customer inputs their card details directly into our iframes, and then we send you a token representing those details, so you can request a payment.

<Note>
  Secure Fields are useful to tokenize cards and keep the PCI scope away. They do not intervene in the payment acceptance process. If you wish an end-to-end payment acceptance solution for your clients in which you can manage dynamic payment options, alternative payment methods or redirection easily, look into our Payrails Drop-in solution.
</Note>

## How it works

1. Inject secured input fields inside iFrames into your HTML containers
2. Customize the look and feel of your input fields with CSS
3. Control the input fields behavior via Javascript

Go here for a detailed [technical implementation guide](/docs/orchestration/checkout-sdks/web-v5-legacy/secure-fields).

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-2.png?fit=max&auto=format&n=knNnlxc2J__TB9tW&q=85&s=ec2010aa9df34640ee500c08c73c8c9b" width="100%" alt="Tokenize cards with secure fields 2" data-path="images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-2.png" />

<Note>
  To make sure your frontend can communicate securely with Payrails, you must first fetch configurations **from your server side application**.
</Note>

Here's a simple tokenization flow with the surface covered by the SDK colored in blue:

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-3.png?fit=max&auto=format&n=knNnlxc2J__TB9tW&q=85&s=695b5abbebe778aab3661888f8536e93" width="80%" alt="Tokenize cards with secure fields 3" data-path="images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-3.png" />

After the SDK is initialized, you can leverage the SDK features to customize the user experience:

* Custom field validation and errors
* Subscribe and react to events happening inside the form
* Customize the style with JSS
* Save your tokenized card and get a payment instrument id for future references

The Secure Fields are available for Web and React Native applications.

## (Optional) Update card security code during authorization request

In case you want to re-send the security code of the card after the initial tokenization of a card, you need to send instrumentId and encryptedCardDetails in the authorize request.

### Use secure fields for encrypting card security code

```javascript theme={null}
//Step 1
const container = payrailsClient.collectContainer({
  containerType: 'COLLECT'
});

//Step 2
const field = container.createCollectElement({
  placeholder: "CVV",
  label: "cvv",
  type: ElementType.CVV,
});

// Step 3
field.mount("#cvv"); //assumes there is a div with id="#cardNumber" in the webpage

// Step 4
const encryptedCardData = await container.collect(); 
```

Pass this data along with instrumentId to the authorize request.  Here is what payment composition object will look like for the authorize action -

```javascript theme={null}
const paymentCompositionObject = {
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentInstrumentData": {
        "encryptedData": encryptedCardData
      },
      "storeInstrument": false,
      "enrollInstrumentToNetworkOffers": false,
      "paymentInstrumentId": "384279fe-fee4-441d-9836-d2ef663551ad"
    }
  ]
}
```

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-4.png?fit=max&auto=format&n=knNnlxc2J__TB9tW&q=85&s=7c9de1fbf84ef84d1f9959fae00d2842" width="80%" alt="Tokenize cards with secure fields 4" data-path="images/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields-4.png" />

The security code will be updated for the instrument vault token and used for the authorization.


## Related topics

- [How to collect card data with secure fields (collect container)](/docs/orchestration/checkout-sdks/web/guides/how-to-collect-card-data-with-secure-fields-collect-container.md)
- [Secure Fields](/docs/orchestration/checkout-sdks/web-v5-legacy/secure-fields.md)
- [Tokenize Cards via SDK](/docs/token-vault/tokenize-payment-instruments/index.md)