Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Example
  • Additional notes
  • More to read
  1. Placing orders
  2. Payments
  3. Adyen

Adding the payment source

How to add an Adyen payment source to an order

PreviousAdyenNextSending back the payment details

Last updated 2 years ago

Problem

You have a pending order with a selected payment method that is associated with an Adyen payment integration. You want to give your customer the possibility to select one of the payment sources available from that gateway — e.g. a credit card — and use it to process the payment.

Solution

To add an Adyen payment source to an order, you have to create an Adyen payment source object and associate it with the order, as described in the Checkout guide.

Example

1. Get the payment source type

The following request retrieves the attributes of the payment method associated with the order identified by the "qaMAhZkZvd" ID:

curl -g -X GET \
  'http://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd?include=payment_method' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

On success, the API responds with a 200 OK status code, returning the requested order object and the associated payment method:

{
  "data": {
    "id": "qaMAhZkZvd",
    "type": "orders",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd"
    },
    "attributes": {...},
    "relationships": {
      "market": {
        "links": {...}
      },
      "customer": {
        "links": {...}
      },
      "shipping_address": {
        "links": {...}
      },
      "billing_address": {
        "links": {...}
      },
      "available_payment_methods": {
        "links": {...}
      },
      "payment_method": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd/relationships/payment_method",
          "related": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd/payment_method"
        },
      "data": {
        "type": "payment_methods",
        "id": "JMRQlsvxkO"
      }
      },
      "payment_source": {
        "links": {...}
      },
      "line_items": {
        "links": {...}
      },
      "shipments": {
        "links": {...} 
      }
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
    {
      "id": "JMRQlsvxkO",
      "type": "payment_methods",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/payment_methods/JMRQlsvxkO"
      },
      "attributes": {
        "payment_source_type": "adyen_payments",
        "name": "Adyen Payment",
        "disabled_at": null,
        "price_amount_cents": 0,
        "price_amount_float": 0.0,
        "formatted_price_amount": "€0,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "",
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
        "links": {...}
        },
        "payment_gateway": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ]
}

2. Create the payment source and associate it with the order

The following request creates an Adyen payment object and associates it with the order identified by the "qaMAhZkZvd" ID:

curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/adyen_payments' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "adyen_payments",
    "attributes": {},
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "qaMAhZkZvd"
        }
      }
    }
  }
}'

On success, the API responds with a 201 Created status code, returning the created Adyen payment object:

{
  "data": {
    "id": "emdEKhoOMA",
    "type": "adyen_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/adyen_payments/emdEKhoOMA"
    },
    "attributes": {
      "payment_methods": {
        "groups": [
          {
            "name": "Credit Card",
            "types": [
              "visa",
              "mc",
              "amex"
            ]
          }
        ],
        "paymentMethods": [
          {
            "brands": [
              "visa",
              "mc",
              "amex"
            ],
            "details": [
              {
                "key": "encryptedCardNumber",
                "type": "cardToken"
              },
              {
                "key": "encryptedSecurityCode",
                "type": "cardToken"
              },
              {
                "key": "encryptedExpiryMonth",
                "type": "cardToken"
              },
              {
                "key": "encryptedExpiryYear",
                "type": "cardToken"
              },
              {
                "key": "holderName",
                "optional": true,
                "type": "text"
              }
            ],
            "name": "Credit Card",
            "type": "scheme"
          },
          {
            "name": "Online bank transfer.",
            "supportsRecurring": true,
            "type": "directEbanking"
          },
          {
            "name": "Pay later with Klarna.",
            "supportsRecurring": true,
            "type": "klarna"
          },
          {
            "name": "Paysafecard",
            "supportsRecurring": true,
            "type": "paysafecard"
          },
          {
            "details": [
              {
                "key": "bic",
                "type": "text"
              }
            ],
            "name": "GiroPay",
            "supportsRecurring": true,
            "type": "giropay"
          },
          {
            "name": "Slice it with Klarna.",
            "supportsRecurring": true,
            "type": "klarna_account"
          }
        ]
      },
      "payment_request_data": {},
      "payment_request_details": {},
      "payment_response": {},
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/adyen_payments/emdEKhoOMA/relationships/order",
          "related": "https://yourdomain.commercelayer.io/api/adyen_payments/emdEKhoOMA/order"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Additional notes

Available payment methods

Preventing mismatched amount errors

When implementing your checkout flow using Adyen please make sure the lapse of time between the order placement and authorization is as short as possible to prevent the order from being modified in the meantime.

Payment source nullification

If the payment method is associated with the order is changed previously created Adyen's payment sources are nullified and must be recreated. In this case, if the payment has already been authorized, the related authorization is voided and the order's payment status is set back from authorized to paid.

If an Adyen payment is authorized but the related order is not placed yet, the associated payment source cannot be changed. In some special cases (e.g. to give the user the possibility to change previously inserted credit card details) you may want to force the payment source nullification, even if the related payment is already authorized. To do that, you can leverage the _nullify_payment_source attribute of the order and manually trigger the payment source nullification, along with the related authorization void (if any) and payment status reset.

More to read

At the moment of the Adyen payment source creation, Commerce Layer makes a server-to-server request to Adyen to get a list of the available payment methods based on the payment amount and the customer country/device — see for any reference — and returns it in the payment_methods attribute of the Ayden payment object.

The term payment method mentioned here is used to match and has nothing to do with Commerce Layer API concept you'll find elsewhere in the guides.

You can authorize Adyen payments using the _authorize trigger attribute of the order, or wait for Commerce Layer to do it automatically at the moment of the order placement (we strongly recommend following this latter workflow). Remember that you need to (and any other additional information required by specific features such as ) to actually authorize the order. Until you do that the order status is still pending and so the order is still editable (i.e. the customer can add or remove items from the cart, changing its total amount). If this happens the order amount and the succeded authorization amount will differ, resulting in an error.

See our documentation if you need more information on how to , , or .

Adding a payment source
Adyen documentation
Adyen internal naming convention
payment method
retrieve an order
include associations
create
update an Adyen payment
send back the payment details
3DS