> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/payment_options.md).

# Payment options

Payment options can be associated with an [order](/core-api-reference/orders.md#payment-options) to extend the information Commerce Layer sends to the payment gateway when the payment is created. That information must be provided using the `data` object in a valid JSON format. The `data` key/value pairs will be merged into the root of the payload sent to the gateway and used to create the payment.

{% hint style="info" %}
The provided payment options won't override information we already send to the gateway, only new attributes will be added to the payload. For some gateways — e.g. [Adyen](#adyen) — you can also enrich information sent by default.
{% endhint %}

Payment options are **payment source type-specific** and may vary depending on the payment gateway. Make sure to carefully read the gateway documentation so that you can build the `data` JSON object properly, otherwise the gateway might return an error.

{% hint style="info" %}
For security reasons, payment options can be managed using [integration](/core/api-credentials.md#integration) API credentials only.
{% endhint %}

{% hint style="warning" %}
Remember to associate the payment options to the order before creating the payment source to ensure they are properly injected into the payload we send to the gateway. Similarly, if for any reason the payment source associated with the order should change (e.g. changing the gateway type), make sure to remove the old payment options association or update it to the one requested by the new payment source type, otherwise the gateway might not accept the payment.
{% endhint %}

## Adyen

In addition to adding information not automatically sent to the gateway by the Commerce Layer integration, when specifying payment options for [Adyen](/core-api-reference/adyen_payments.md), you're allowed to enrich some information already provided by default, including:

<table><thead><tr><th width="290">Option</th><th>Usage</th></tr></thead><tbody><tr><td><strong><code>additionalData</code></strong></td><td>Pass an object containing one or more of the <a href="https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData">supported fields</a>.</td></tr><tr><td><strong><code>lineItems</code></strong></td><td>Pass an array of objects, each specifying the ID of the line item for which you want to inject new attributes (e.g. the SKU code — see example below).</td></tr><tr><td><strong><code>shopperInteraction</code></strong></td><td>Pass a value to override the one Commerce Layer would otherwise compute (e.g. force <code>ContAuth</code>, <code>Ecommerce</code>, or <code>Moto</code>).</td></tr><tr><td><strong><code>recurringProcessingModel</code></strong></td><td>Pass a value to override the one Commerce Layer would otherwise compute (e.g. force <code>CardOnFile</code> or <code>Subscription</code>).</td></tr><tr><td><strong><code>storePaymentMethod</code></strong></td><td>Pass <code>true</code>/<code>false</code> to override whether the payment method gets stored (an explicit <code>false</code> is respected).</td></tr><tr><td><strong><code>shopperReference</code></strong></td><td>Pass a value to override the shopper reference Commerce Layer would otherwise send (useful, for example, when an integration — like Oracle Opera OPI Token eCommerce — requires the literal value <code>not_provided</code>).</td></tr></tbody></table>

{% hint style="info" %}
The `shopperInteraction`, `recurringProcessingModel`, `storePaymentMethod`, and `shopperReference` attributes can only be overridden on the payment creation (`authorize`) call — they're not applied when tokenizing a wallet payment method.
{% endhint %}

{% hint style="danger" %}
Overriding `shopperInteraction`, `recurringProcessingModel`, `storePaymentMethod`, or `shopperReference` can alter the standard payment workflow (e.g. forcing `ContAuth` on a non-tokenized payment) and may break downstream 3DS or webhook handling. Only override these if you're confident about how your integration handles the consequences.
{% endhint %}

<pre class="language-json"><code class="lang-json">"data": {
  "type": "payment_options",
  "attributes": {
    "payment_source_type": "adyen_payments",
    "data": {
<strong>      "additionalData": {
</strong>        "airline": {
          "agency_invoice_number": "000567",
          "agency_plan_name": "Ryanair",
          "airline_code": "FR"
        }
      },
<strong>      "lineItems": [
</strong>        {
          "id": "aGKdfVClyj",
          "sku": "SKU000XY"
        },
        {
          "id": "fSXweDxKJq",
          "sku": "SKU000WZ"
        }
      ],
<strong>      "riskData": {
</strong>        "clientData": "y0ur-cl13nt-D4ta",
        "fraudOffset": 2
      }
    }
  },
  "relationships": {
    "order": {
      "data": {
        "type": "orders",
        "id": "ABCRtyUpBa"
      }
    }
  }
}
</code></pre>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/payment_options.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.