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 we send to the payment gateway at the moment of the payment creation. 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 properly create the payment itself. 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 the information sent by default).

Payment options are payment source type-specific and may vary based on the different 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 the payment source creation 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 them to the ones 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:

• additionalData — pass an object containing one or more of the supported fields.

• lineItems — pass an array of objects, each of them must specify ID of the line item for which you want to inject new attributes (e.g. the SKU code — see example below).

"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"
      }
    }
  }
}