Avarda Checkout Adapter

Overview

Avarda Checkout Adapter is a payment adapter for Avarda Checkout 3.0. Read more on Avarda Checkout 3.0 docs

Environments

There are two environments that you can use.

Configuration

You start by adding a configuration for the Avarda Checkout Adapter in Norce Checkout Admin.

Create payment

To get the data required in order to embed the Avarda Checkout, a call to the Avarda Checkout Adapter has to be made (see request below). The Avarda Checkout Adapter will create a payment on the order and initialize the Checkout Setup in Avarda using the configured settings.

The response contains the following data:

• paymentId, the Norce Orders paymentId, is used in combination with the orderId to uniquely identify the payment as well as in requests to the Avarda Checkout Adapter.
• purchaseJwt, token generated from Avarda that is used to embed the Avarda Checkout, that it uses to communicate with Avarda.
• javascriptUrl, contains the URL to the configured Avarda environment to use when embedding the Avarda Checkout javascript.
• styles, a JSON object containing custom CSS styling that can be used to override the Avarda Checkouts default styling.

Example request:

POST /api/checkout/v1/{order_id}/payments

Example response:

{
    "paymentId":"pfloMHwnSFxLDtaQYTVSeSKaLBx",
    "purchaseJwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJDaGVja291dCIsImp0aSI6IjZjZDg5Yzg2LWZiMmItNDI0NC05NjU3LTVjNTgxZTYyNzJhYyIsIlB1cmNoYXNlSWQiOiI4YjRhNGQ2NTAyMDI0NjRiODc3ZTIwMmFkMmFhNjU4ZCIsImV4cCI6MTY5OTQ1MzI0OX0.svJcXUXYYOtnrUlezx0HTu-Rn2NAHBr2UnLyZxsqcnM",
    "javascriptUrl":"https://stage.checkout-cdn.avarda.com/cdn/static/js/main.js",
    "styles":{}
}

The Avarda Checkout Adapter will also update your Norce order with the Avarda payment details. The payments[].id property represents the paymentId from the JSON response received when initializing the Avarda Checkout payment session and the payments[].orderId represents the Norce order identifier.

Example data from the Norce order object:

{
    // ...
  "payments": [
        {
            "id": "pmlzoZWcBpspiKelTciapXQMcLf",
            "adapterId": "avarda_checkout_adapter",
            "name": "avarda_checkout_adapter",
            "merchant": "norce-checkout-demo",
            "channel": "avarda",
            "currency": "SEK",
            "type": "default",
            "orderId": "oIbEMMqo",
            "amount": 30,
            "upperLimitAmount": 2147483647,
            "state": "reserved",
            "reference": "f7d29d52cdf549a3b68f1d0d1b0843ab",
            "attributes": {
                "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJDaGVja291dCIsImp0aSI6IjkzM2VmNGM1LWE4ZjktNDgxMC1iZDk3LWVkZmY0NDY2MWE2ZCIsIlB1cmNoYXNlSWQiOiJmN2QyOWQ1MmNkZjU0OWEzYjY4ZjFkMGQxYjA4NDNhYiIsImV4cCI6MTY5OTQ1NDYxNH0.aF7kEGS3lu8cpeLECnZbX3prl2MFgjAFGGvv3TM7RdM",
                "clientId": "400832f8-2125-4717-b1ad-1759064876ba",
                "paymentName": "DirectInvoice"
            },
            "actions": []
        }
    ]
    // ...
}

Update payment

When a user updates their selected payment method in the Avarda Checkout, a JavaScript callback will be executed, no action needs to be taken on this callback since information about the payment method is saved to the Norce orders payment when completing the payment.

Update customer

When a user updates their billing or shipping address in the Avarda Checkout, a JavaScript callback will be executed where a request to the Avarda Checkout Adapter should be made. The adapter updates the Norce orders customer information with the latest data which it retrieves from Avardas API.

Example request:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/customer-update

Example data from the Norce order object:

  // ...
  "customer": {
    "billing": {
      "type": "person",
      "givenName": "Gunbritt",
      "familyName": "Bodén",
      "streetAddress": "Borgmästarplan 3",
      "streetAddress2": "",
      "postalCode": "80266",
      "city": "Gävle",
      "country": "SE",
      "phone": "+46763045000",
      "email": "gunbritt-test@norce.io",
      "nationalIdentificationNumber": ""
    },
    "shipping": {
      "type": "person",
      "givenName": "Gunbritt",
      "familyName": "Bodén",
      "streetAddress": "Borgmästarplan 3",
      "streetAddress2": "",
      "postalCode": "80266",
      "city": "Gävle",
      "country": "SE",
      "phone": "+46763045000",
      "email": "gunbritt-test@norce.io",
      "nationalIdentificationNumber": ""
    },
    "type": "person"
  }
  // ...

Update shipping option

When a user changes the shipping option in the Avarda Checkout, a JavaScript callback will be executed where a request to the Avarda Checkout Adapter should be made. The adapter updates the Norce orders shipping information and costs with the latest data and which it retrieves from Avardas API.

Example request:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-option-update

Example data from the Norce order object:

  // ...
  "shippings": [
    {
      "id": "sYmwDSQGBdmcragyzqpqznaXyJH",
      "merchant": "norce-checkout-demo",
      "channel": "avarda",
      "state": "intent",
      "reference": "31853a39-e0dd-473c-a698-509c7de935f0",
      "orderId": "oIbEMMqo",
      "adapterId": "avarda_checkout_adapter",
      "name": "Early Bird Standard",
      "total": {
        "includingVat": 20,
        "excludingVat": 20
      },
      "vatRate": 0,
      "deliveryDetails": {
        "carrier": "Early Bird",
        "class": "",
        "product": {
          "reference": "earlybird-std",
          "name": "Early Bird Standard"
        }
      },
      "addons": [],
      "attributes": {
        "shippingData": "omitted from example"
      }
    }
  ]
  // ...

Validate payment

When a user clicks on "Complete payment" in the Avarda Checkout UI a beforeSubmit callback is executed which should call the validate endpoint on the Avarda Checkout adapter.

If the validation is successful a call to the Avarda Checkout Adapters process endpoint should be made, the process endpoint checks so that the order has not changed since the validate call and updates consents, billing and shipping address and the Norce order and payment state. We will then continue with the submit.

If the validation failed a non 200 response will be returned with a message including error details that can be displayed in the Avarda Checkout UI. The submit will be aborted in this case.

Example request:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/validate

Example response for non successful validation:

[{"code": "error-code", "adapterId": "avarda-checkout-adapter"}]

Example request:

POST /api/checkout/v1/callback/orders/{order_id}/{order_id}/payments/{payment_id}/process

Completed payment

When the payment has been completed in Avarda a completedPurchase callback will be executed which should call the notification endpoint on the Avarda Checkout Adapter. The Avarda Checkout Adapter then updates the payment with the "final" payment details from Avarda and updates the payment state.

Example request:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/notification