Create your own adapter

If we're currently not supporting an integration that you need, you can create your own adapter! An adapter does not necessarily need to integrate with an external provider, take the Non-PSP adapter for example, only relying on configuration but providing a powerful feature to the Norce Checkout.

We recommend getting familiar with the current adapters Norce manages and provide a similar experience for your adapter.

Configuration

Provide a schema for your configuration, making sure it follows the Basic configuration. The configuration is accessable to the entire checkout, the basic configuration makes it possible to know exactly where to find the adapter without knowing anything specific about the adapter. The additions to the configuration should contain information required by users of the adapter, like the checkout or information used by the adapter such as how to reach the external provider.

API

The general idea is that paths should reflect the action you're performing in Norce Checkout, and the request and response body should contain what you need to know about Norce Checkout as well as your specific context.

For example, when creating a payment using the Klarna Adapter you use POST: /orders/<orderId>/payments, and the response will contain both the Norce Checkout payment id as well as the htmlSnippet as it appears in the response from Klarna.

If the provider API includes actions that are used by the checkout, the adapter API should include these. An example would be the Adyen adapter, providing an endpoint to start a transaction.

Hooks & Notifications

Adapters are most powerful when they work together, and the tools they use to do that are Hooks & Notifications.

Hooks

The adapter requests to be informed of potential changes and are able to reject them. If they approve the change they are able to provide further changes.

The most used example is a payment adapter interested in changes to cart, where it would need to update the payment to cover the cost of the cart. A payment adapter might also be interested in state changes. If the state is being changed from processing to checkout, in order to change the cart, the payment adapter might want to make sure the payment is still in a good state to be updated and not being processed by the provider.

Notifications

The adapter requests to be inform of changes that have happened. An example would be a payment adapter that wants to update the provider with an order reference, once an external order has been created.

Order state

While some adapters react to order state changes, other adapter might need to drive the change. A checkout payment adapter is in charge of the order state flow. When a customer clicks the buy button, the provider will ask the adapter to validate the order. The quickest way to validate an order is to call the validate action on the order service, but the safest way to validate an order is to change the state to processing. Every adapter that needs to validate the order before being processed should have a hook registered for this change, able to block it if validation fails. The order can now be considered locked for any change, since changing something like the cart items or anything that effects the order total requires the order state to be changed back to checkout. The payment adapter can then block the change if needed, in effect locking it.

The payment provider will also inform the adapter when the customer has completed their part in the checkout, at which point the adapter can change the state to accepted. If the provider has approved the payment and the next step is for the merchant to cancel or capture the payment, we can change the order state to completed.

Payment Transactions

In order for merchants to handle issues with payment providers themselves it's vital for payment adapters to enrich their payment with transactions. Every time you communicate with the external provider you should store relevant request or responses as transactions.

For example, when the adapter creates a resource at the provider, create a transaction with your request and the response we received from the provider.