Customers

Learn about the customer resource.

Suggest Edits

Overview

The creation of a customer is essential to the Acquired.com API, everything is linked back to the customer_id. We recommend creating a customer profile containing personal information before submitting a payment request. You can then retrieve details about a returning customer, as all payment information will be linked back to the customer_id. This process allows us to manage your customer profile for you.

Customer's can be created and managed from within the API.

In the API you can:

  • Create a customer
  • Retrieve a customer
  • Update an existing customer
  • List all customers (you can also utilise pagination parameters to query specific customer records)

📘

Note

Before you create a new customer, make sure that the customer does not already exist, as this can cause problems with further transactions etc.

Card payments process

New customer

The first step in processing a payment for a new customer is to create the customer record. Submit a request into the /customers endpoint and you will be returned a customer_id.

Example:

{
  "reference": "customer_number_00001",
  "first_name": "Edward",
  "last_name": "Johnson",
  "dob": "1988-10-03",
  "ip": "127.0.0.1",
  "custom_data": "L3BheW1lbnQtbGlua3MgcGF5IGN1c3RvbV9kYXRh",
  "billing": {
    "address": {
      "line_1": "152 Aldgate Drive",
      "line_2": "",
      "city": "London",
      "state": "",
      "postcode": "E1 7RT",
      "country_code": "GB"
    },
    "email": "[email protected]",
    "phone": {
      "country_code": "44",
      "number": "2039826580"
    }
  },
  "shipping": {
    "address_match": true,
    }
  }
}

Response:

{
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

You can then include the customer_id in the payment request along with the card details. For more information on how to use the save cards feature, please refer to our card payments guide.

Existing customer

When an existing customer returns to make a payment request, either the card_id or the full card parameters (depending on whether the card has already been created) can be submitted. For more information on our card payments flows, view our card payments guide.

Guest checkout

In the event that the request does not include any customer details and the create_card parameter is set to false, the payment will be successfully processed; however, it will not be linked to a specific customer. This is essentially the /payments version of 'guest checkout'.

📘

Note

Please refer to both our card payments guide and also our payments API reference for further detail on these processes, including code examples.

Hosted Checkout process

Much like with the payments API, customers and their customer_id are very important to the Hosted Checkout and will determine the end customer's experience of using checkout as well as the merchant's ability to process recurring payments.

While merchants integrating with the API for card payments are expected to create customers before submitting payments, the Hosted Checkout will handle this automatically and provide details of customer IDs via webhook notification.

For new customers, providing a unique customer.reference in the initial payment-links request will ensure that a new customer is created in the Acquired.com system. When the customer attempts payment, a customer_id will be returned via the customer_new webhook.

If no customer reference is provided for new customers, then the customers will go through a Guest Checkout flow and their details won't be saved. If the initial payment is intended for future recurring payments and the recurring flag is set to true though, a customer reference must be provided.

For existing customers, providing a customer_id in the initial payment links request will ensure that any card used for payment will be saved against that customer, assuming the 'save cards' feature is turned on in the Hosted Checkout Settings. See the Hosted Checkout saving card details guide for more.

The below example shows all potential customer object fields, you do not have to pass all of them in your request.

See example below:

{
  "transaction": {
    "order_id": "{{$guid}}",
    "amount": 15.02,
    "currency": "gbp",
    "capture": true
  },
"customer": {
    "reference": "customer_number_00001",
    "first_name": "Edward",
    "last_name": "Johnson",
    "dob": "1988-10-03",
    "ip": "127.0.0.1",
    "custom_data": "L3BheW1lbnQtbGlua3MgcGF5IGN1c3RvbV9kYXRh",
    "billing": {
      "address": {
        "line_1": "152 Aldgate Drive",
        "line_2": "",
        "city": "London",
        "state": "",
        "postcode": "E1 7RT",
        "country_code": "GB"
      },
      "email": "[email protected]",
      "phone": {
        "country_code": "44",
        "number": "2039826580"
      }
    },
    "shipping": {
      "address_match": true
      }
    },
  "tds": {
    "is_active": true,
    "challenge_preference": "no_preference",
    "contact_url": "https://yourdomain.com/contact"
  },
  "is_recurring": false,
  "redirect_url": "https://qaacs.acquired.com/merchant_redirect/test_success",
  "webhook_url": "https://yourdomain.com/webhook"
}

📘

Note

When passing the customer_id it is not required that the full customer details are also passed in the request.

See example below:

{
  "transaction": {
    "order_id": "{{$guid}}",
    "amount": 15.02,
    "currency": "gbp",
    "capture": true
  },
  "customer": {
    "customer_id": "cd9a5209-5eac-4744-b674-1b8af429f0d5"
  },
  "tds": {
    "is_active": true,
    "challenge_preference": "no_preference",
    "contact_url": "https://yourdomain.com/contact"
  },
  "is_recurring": false,
  "redirect_url": "https://qaacs.acquired.com/merchant_redirect/test_success",
  "webhook_url": "https://yourdomain.com/webhook"
}

Customer requests

Update customer details

To update any of the customer's personal details, such as billing or shipping data, you must submit a request into PUT/customers/{customer_id}.

In the below request we are updating the billing.address.line_1 parameter:

{  
"billing": {  
        "address": {  
            "line_1": "156 Aldgate Drive"  
        }  
    }  
}

Retrieve a customer

To retrieve a specific customer, simply append the required customer_id to GET/customers/{customer_id}.

You can utilise query parameters to filter what is returned in your response. See the below example:

GET/customers/{customer_id}?filter=first_name,last_name,billing.address.line_1

Response:

{
    "first_name": "Edward",
    "last_name": "Johnson",
    "billing": {
        "address": {
            "line_1": "152 Aldgate Drive"
        }
    }
}

List all customers

Simply submit a GET request into the /customers endpoint to retrieve a list of all customers. Use query parameters to filter and limit what is returned within your response. See the below example:

GET/customers?filter=customer_id,first_name,ip&limit=3

Response:

{
    "meta": {
        "count": 3,
        "offset": 0,
        "limit": 3,
        "total": 22,
        "links": [
            {
                "rel": "self",
                "href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=0"
            },
            {
                "rel": "first",
                "href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=0",
                "title": "first page"
            },
            {
                "rel": "last",
                "href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=21",
                "title": "last page"
            },
            {
                "rel": "prev",
                "href": "",
                "title": "prev page"
            },
            {
                "rel": "next",
                "href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=3",
                "title": "next page"
            }
        ]
    },
    "data": [
        {
            "customer_id": "b56af699-1abd-783c-4453-d3e7df888886",
            "first_name": "Edward",
            "ip": "127.0.0.1"
        },
        {
            "customer_id": "7397a977-7984-53c5-2e89-e04f7a325270",
            "first_name": "Edward",
            "ip": "127.0.0.1"
        },
        {
            "customer_id": "ad2cc336-349f-b3a6-6735-581e32ae06b1",
            "first_name": "Edward",
            "ip": "127.0.0.1"
        }
    ]
}

Updated 2 months ago