Changelog

API Migration Guide

We are continually introducing new functionality to the Primer Ecosystem, some of which requires additional inputs on our APIs. To make sure these changes don’t break any existing integrations, we roll them out safely using API Versions.

Migrating to v2.1

The latest version of our APIs focus on capturing more details to enable a richer checkout experience. Some of these details are required to allow configuration of the checkout via the Primer Dashboard. Also some of these details are needed to work with advanced Payment Processors or Payment Methods.

The examples below only illustrate how to transition between the two versions of the endpoints, however you should read the latest API Reference linked above for details on the usage of the endpoints. Also read how to introduce API Versioning into your requests in the latest API Reference linked above.

Client Session

This is an example of a request in v1: POST /auth/client-token.

1{
2  "customerCountryCode": "GB",
3  "customerId": "customer-123",
4  "checkout": {
5    "paymentFlow": "DEFAULT"
6  }
7}

This is an example of a equivalent request in v2: POST /client-session with X-Api-Version="2021-09-27".

1{
2  "customerId": "customer-123",
3  "customer": {
4    "emailAddress": "customer@primer.io",
5    "mobileNumber": "+44841234567",
6    "firstName": "John",
7    "lastName": "Doe",
8    "billingAddress": {
9      "addressLine1": "42A",
10      "postalCode": "abcde",
11      "city": "Cambridge",
12      "state": "Cambridgeshire",
13      "countryCode": "GB"
14    },
15    "shippingAddress": {
16      "addressLine1": "42A",
17      "postalCode": "abcde",
18      "city": "Cambridge",
19      "state": "Cambridgeshire",
20      "countryCode": "GB"
21    }
22  },
23  "order": {
24    "lineItems": [
25      {
26        "itemId": "item-1",
27        "description": "My item",
28        "amount": 1337,
29        "quantity": 1
30      }
31    ],
32    "countryCode": "GB"
33  },
34  "currencyCode": "GBP",
35  "orderId": "order-123",
36  "metadata": {
37    "productType": "Merchandise"
38  },
39  "paymentMethod": {
40    "vaultOnSuccess": true
41  }
42}

v2.1

This is an example of a equivalent request in v2.1: POST /client-session with X-Api-Version="2.1".

1{
2  "customerId": "customer-123",
3  "customer": {
4    "emailAddress": "customer@primer.io",
5    "mobileNumber": "+44841234567",
6    "firstName": "John",
7    "lastName": "Doe",
8    "billingAddress": {
9      "addressLine1": "42A",
10      "postalCode": "abcde",
11      "city": "Cambridge",
12      "state": "Cambridgeshire",
13      "countryCode": "GB"
14    },
15    "shippingAddress": {
16      "addressLine1": "42A",
17      "postalCode": "abcde",
18      "city": "Cambridge",
19      "state": "Cambridgeshire",
20      "countryCode": "GB"
21    }
22  },
23  "lineItems": [
24    {
25      "itemId": "item-1",
26      "description": "My item",
27      "amount": 1337,
28      "quantity": 1
29    }
30  ],
31  "orderDetails": {
32    "countryCode": "GB"
33  },
34  "currencyCode": "GBP",
35  "orderId": "order-123",
36  "metadata": {
37    "productType": "Merchandise"
38  },
39  "paymentMethod": {
40    "vaultOnSuccess": true
41  }
42}

Summary of the v2.1 changes

  • order is now called orderDetails
  • lineItems is now a top-level element
  • amount has been removed. You should always specify lineItems and we would dynamically calculate the amount. See our API Reference for how we calculate the amount.

Create a Payment

This is an example of an equivalent request: POST /payments with X-Api-Version="2021-09-27".

POST /payments

1{
2  "orderId": "order-123",
3  "currencyCode": "GBP",
4  "amount": 1337,
5  "paymentInstrument": {
6    "token": "{{payment_method_token}}" // As received from the SDK
7  },
8  "statementDescriptor": "Test payment",
9  "customer": {
10    "email": "customer@primer.io",
11    "billingAddress": {
12      "addressLine1": "42A",
13      "postalCode": "abcde",
14      "city": "Cambridge",
15      "state": "Cambridgeshire",
16      "countryCode": "GB"
17    }
18  }
19}

This is an example of an equivalent request in v2: POST /payments with X-Api-Version="2021-09-27".

1{
2  "orderId": "order-123",
3  "amount": 1000,
4  "currencyCode": "GBP",
5  "customer": {
6    "email": "customer@primer.io",
7    "billingAddress": {
8      "addressLine1": "42A",
9      "postalCode": "abcde",
10      "city": "Cambridge",
11      "state": "Cambridgeshire",
12      "countryCode": "GB"
13    }
14  },
15  "metadata": {
16    "productType": "Merchandise"
17  },
18  "paymentMethodToken": "{{payment_method_token}}", // As received from the SDK
19  "paymentMethod": {
20    "descriptor": "Test payment",
21    "paymentType": "FIRST_PAYMENT"
22  }
23}

This is an example of an equivalent request in v2.1: POST /payments with X-Api-Version="2.1"

1{
2  "paymentMethodToken": "{{payment_method_token}}" // As received from the SDK
3}

OR

1{
2  "orderId": "order-123",
3  "amount": 1337,
4  "currencyCode": "GBP",
5  "customer": {
6    "email": "customer@primer.io",
7    "billingAddress": {
8      "addressLine1": "42A",
9      "postalCode": "abcde",
10      "city": "Cambridge",
11      "state": "Cambridgeshire",
12      "countryCode": "GB"
13    }
14  },
15  "lineItems": [
16    {
17      "itemId": "item-1",
18      "description": "My item",
19      "amount": 1337,
20      "quantity": 1
21    }
22  ],
23  "orderDetails": {
24    "countryCode": "GB"
25  },
26  "metadata": {
27    "productType": "Merchandise"
28  },
29  "paymentMethodToken": "{{payment_method_token}}", // As received from the SDK
30  "paymentMethod": {
31    "descriptor": "Test payment",
32    "paymentType": "FIRST_PAYMENT"
33  }
34}

Summary of the v2.1 changes

  • order is now called orderDetails
  • lineItems is now a top-level element
Built with