Payment options

The payment option object and the allowed CRUD operations on the related resource endpoint

Payment options can be associated with an order 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.

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 — you can also enrich information sent by default.

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.

For security reasons, payment options can be managed using integration API credentials only.

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.

Adyen

In addition to adding information not automatically sent to the gateway by the Commerce Layer integration, when specifying payment options for Adyen, you're allowed to enrich some information already provided by default, including:

Option	Usage
additionalData	Pass an object containing one or more of the supported fields.
lineItems	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).
shopperInteraction	Pass a value to override the one Commerce Layer would otherwise compute (e.g. force ContAuth, Ecommerce, or Moto).
recurringProcessingModel	Pass a value to override the one Commerce Layer would otherwise compute (e.g. force CardOnFile or Subscription).
storePaymentMethod	Pass true/false to override whether the payment method gets stored (an explicit false is respected).
shopperReference	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 not_provided).

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.

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.

"data": {
  "type": "payment_options",
  "attributes": {
    "payment_source_type": "adyen_payments",
    "data": {
      "additionalData": {
        "airline": {
          "agency_invoice_number": "000567",
          "agency_plan_name": "Ryanair",
          "airline_code": "FR"
        }
      },
      "lineItems": [
        {
          "id": "aGKdfVClyj",
          "sku": "SKU000XY"
        },
        {
          "id": "fSXweDxKJq",
          "sku": "SKU000WZ"
        }
      ],
      "riskData": {
        "clientData": "y0ur-cl13nt-D4ta",
        "fraudOffset": 2
      }
    }
  },
  "relationships": {
    "order": {
      "data": {
        "type": "orders",
        "id": "ABCRtyUpBa"
      }
    }
  }
}