Adding the payment source

How to add a Klarna payment source to an order

Problem

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

Solution

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

Adding a payment source

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": "Klarna 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 a Klarna payment object and associates it with the order identified by the "qaMAhZkZvd" ID:

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

On success, the API responds with a 201 Created status code, returning the created Klarna payment object, along with client_token to be used with the Klarna SDK:

{
  "data": {
    "id": "ertHJlpPTR",
    "type": "klarna_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/klarna_payments/ertHJlpPTR"
    },
    "attributes": {
      "auth_token": null,
      "payment_request_data": {
        "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
        "payment_method_categories": [
          {...}
        ],
        "session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
      },
      "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": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Additional notes

Available payment methods

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

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

Payment source nullification

Klarna payments are synchronous. When a Commerce Layer's klarna_payment is created and associated with an order, Klarna immediately creates a payment intent using the current order's total_amount as the amount to be authorized. If the order is modified before placement its amount and the original intent amount may differ, resulting in an error. To prevent that scenario previously created Klarna's payment sources are nullified in case of order edit/refresh (or if the payment method associated with the order is changed) and must be recreated.

In view of this, make sure to set the payment source as the last step of your checkout implementation.