API Migration Guide

Suggest Edits

📘

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

On our API Reference v2.1 the latest version.

📘

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

v1

POST /auth/client-token

{
    "customerCountryCode": "GB",
    "customerId": "customer-123",
    "checkout": {
        "paymentFlow": "DEFAULT"
    }
}

v2

POST /client-session
X-Api-Version="2021-09-27"

{
    "customerId": "customer-123",
    "customer": {
        "emailAddress": "[email protected]",
        "mobileNumber": "+44841234567",
        "firstName": "John",
        "lastName": "Doe",
        "billingAddress": {
            "addressLine1": "42A",
            "postalCode": "abcde",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        },
        "shippingAddress": {
            "addressLine1": "42A",
            "postalCode": "abcde",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        }
    },
    "order": {
        "lineItems": [
            {
                "itemId": "item-1",
                "description": "My item",
                "amount": 1337,
                "quantity": 1
            }
        ],
        "countryCode": "GB"
    },
    "currencyCode": "GBP",
    "orderId": "order-123",
    "metadata": {
        "productType": "Merchandise"
    },
    "paymentMethod": {
        "vaultOnSuccess": true
    }
}

v2.1

POST /client-session
X-Api-Version="2.1"

{
    "customerId": "customer-123",
    "customer": {
        "emailAddress": "[email protected]",
        "mobileNumber": "+44841234567",
        "firstName": "John",
        "lastName": "Doe",
        "billingAddress": {
            "addressLine1": "42A",
            "postalCode": "abcde",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        },
        "shippingAddress": {
            "addressLine1": "42A",
            "postalCode": "abcde",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        }
    },
    "order": {
        "countryCode": "GB",
        "lineItems": [
          {
            "itemId": "item-1",
            "description": "My item",
            "amount": 1337,
            "quantity": 1
          }
        ]
    },
    "currencyCode": "GBP",
    "orderId": "order-123",
    "metadata": {
        "productType": "Merchandise"
    },
    "paymentMethod": {
        "vaultOnSuccess": true
    }
}

Summary of the v2.1 changes

  • paymentType and descriptor can now be set on the Client Session. These values are passed through to the payment request.

Create a Payment

v1

POST /payments

{
  "orderId": "order-123",
  "currencyCode": "GBP",
  "amount": 1337,
  "paymentInstrument": {
    "token": "{{payment_method_token}}" // As received from the SDK
  },
  "statementDescriptor": "Test payment",
  "customer": {
    "email": "[email protected]",
    "billingAddress": {
      "addressLine1": "42A",
      "postalCode": "abcde",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  }
}

v2

POST /payments
X-Api-Version="2021-09-27"

{
  "orderId": "order-123",
  "amount": 1337,
  "currencyCode": "GBP",
  "customer": {
    "email": "[email protected]",
    "billingAddress": {
      "addressLine1": "42A",
      "postalCode": "abcde",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  },
  "order": {
    "countryCode": "GB",
    "lineItems": [
      {
        "itemId": "item-1",
        "description": "My item",
        "amount": 1337,
        "quantity": 1
      }
    ],
   },
  "metadata": {
    "productType": "Merchandise"
  },
  "paymentMethodToken": "{{payment_method_token}}",  // As received from the SDK
  "paymentMethod": {
    "descriptor": "Test payment",
    "paymentType": "FIRST_PAYMENT",
    "vaultOnSuccess": true
  }
}

v2.1

POST /payments
X-Api-Version="2.1"

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

OR

{
  "orderId": "order-123",
  "amount": 1337,
  "currencyCode": "GBP",
  "customer": {
    "email": "[email protected]",
    "billingAddress": {
      "addressLine1": "42A",
      "postalCode": "abcde",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  },
  "order": {
    "countryCode": "GB",
    "lineItems": [
      {
        "itemId": "item-1",
        "description": "My item",
        "amount": 1337,
        "quantity": 1
      }
    ],
   },
  "metadata": {
    "productType": "Merchandise"
  },
  "paymentMethodToken": "{{payment_method_token}}",  // As received from the SDK
  "paymentMethod": {
    "descriptor": "Test payment",
    "paymentType": "FIRST_PAYMENT",
    "vaultOnSuccess": true
  }
}

Updated over 1 year ago