Guides

Card Payments

Suggest Edits

Overview

Acquired.com are a fully compliant PCI DSS service provider. We can securely store your sensitive cardholder data using our tokenisation solution, which can be used to process your recurring transactions.

Allowing us to store and tokenise your customers' sensitive payment data vastly reduces your PCI DSS obligations and gives you peace of mind that your customers' card data is safe.

For recurring payments, you need to gain customer consent through the first payment. It works in the same way as a regular payment and the customer may also be required to authenticate the initial transaction with EMV® 3-D Secure. After the first payment, the customer's card will be charged automatically without having to perform a new payment flow.

📘

Note

View our Recurring Payments guide here.

Which integration is best for you?

The Acquired.com API offers card payments via full API integration or our Hosted Checkout or Components solutions. Before you get started we advise deciding which integration is best for you.

A full card API integration gives you the flexibility to build a full checkout journey into your website. You have the ability to decide how you want to capture the relevant pieces of customer information. Whereas, via our Hosted Checkout solution, the structure of our Checkout product dictates how this is displayed.

For more information on our integration options and their benefits, refer to our integration guide.

Processing card payments

When submitting a request into the /payments endpoint, there are various routes available based on the information submitted.

The below diagram illustrates the possible process flows:

In order to save a card for future use, create a card within the first payment request against the relating customer.

Customers can store multiple payment methods against their customer_id. Once you have processed the initial payment request and created the card record, for subsequent payment requests you must specify the required card_id.

/payments

Process a payment - create a card

To create a new card you must pass the full card details within the card object. Ensure that the relating customer_id that you want to store the card against is also passed in the request. In the payment object, set the create_card parameter to true.

📘

Note

When submitting your request to create a card, make sure that the card_id parameter is not passed within the request.

Request:

{
  "transaction": {
    "order_id": "d8bf20b3-6761-487a-a8f1-ac3a4180675e",
    "amount": 20.99,
    "currency": "gbp"
  },
  "payment": {
    "card": {
      "holder_name": "E Smith",
      "scheme": "visa",
      "number": "4000011180138710",
      "expiry_month": 10,
      "expiry_year": 26,
      "cvv": "123"
    },
    "create_card": true,
    "reference": "Custom Ref 001"
  },
  "customer": {
    "customer_id": "5b18a0c0-05de-dfe3-6309-cc703723b0bf"
  }
}

The card_id will then be returned in the response. For future payments, this card_id can then be passed without the full card details and the payment would be processed.

📘

Note

If the transaction has been declined, we will not create a card_id.

Response:

{
    "transaction_id": "bb1c2b84-1686-1b63-5aa6-bf807c69999a",
    "status": "success",
    "issuer_response_code": "00",
    "check": {
        "avs_line1": "matched",
        "avs_postcode": "matched",
        "cvv": "matched"
    },
    "card_id": "10590380-c667-2f69-67c3-e8809d6db5fe",
    "links": [
        {
            "rel": "self",
            "href": "/v1/transactions/bb1c2b84-1686-1b63-5aa6-bf807c69999a"
        }
    ]
}

Process a payment - without creating a card

To process a payment without creating a card record set the create_card parameter to false. The payment will be processed, but the card will not be saved for future use.

If you want to utilise 'guest checkout', pass the below request removing the customer.customer_id and create_card parameters. The transaction will then be created, but will not be stored against a customer_id.

Request:

{
  "transaction": {
    "order_id": "0ca8fbd5-d211-4720-b3cc-b8c48ec9925b",
    "amount": 20.99,
    "currency": "gbp"
  },
  "payment": {
    "card": {
      "holder_name": "E Smith",
      "scheme": "visa",
      "number": "4000011180138710",
      "expiry_month": 10,
      "expiry_year": 26,
      "cvv": "123"
    },
    "create_card": false,
    "reference": "Custom Ref 001"
  },
  "customer": {
    "customer_id": "5b18a0c0-05de-dfe3-6309-cc703723b0bf"
  }
}

Response:

There will be no card_id returned in the response.

{
    "transaction_id": "0e104027-2e32-3d64-ee7a-14ee096d5c70",
    "status": "success",
    "issuer_response_code": "00",
    "check": {
        "avs_line1": "matched",
        "avs_postcode": "matched",
        "cvv": "matched"
    },
    "links": [
        {
            "rel": "self",
            "href": "/v1/transactions/0e104027-2e32-3d64-ee7a-14ee096d5c70"
        }
    ]
}

/payments/reuse

You can process a payment using a previously created card by submitting a request into the /payments/reuse endpoint. The card_id can be passed in the payment request, rather than the full card details. As this is a card present transaction, the cvv value must also be passed to authenticate with 3-D Secure.

📘

Note

When you are processing a payment with an existing card_id, you don't need to pass the create_card parameter.

Request:

{
  "transaction": {
    "order_id": "1f1f2a61-5b68-4725-a0ce-9560514ec00b",
    "amount": 15.02,
    "currency": "gbp",
    "capture": true
  },
  "payment": {
    "card_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "card": {
      "cvv": "123"
    },
    "reference": "Custom Ref 001"
  }
}

Response:

{
    "transaction_id": "0e104027-2e32-3d64-ee7a-14ee096d5c70",
    "status": "success",
    "issuer_response_code": "00",
    "check": {
        "avs_line1": "matched",
        "avs_postcode": "matched",
        "cvv": "matched"
    },
    "links": [
        {
            "rel": "self",
            "href": "/v1/transactions/0e104027-2e32-3d64-ee7a-14ee096d5c70"
        }
    ]
}

Managing and updating cards

In order to be able to process recurring payments, you must ensure that the card details are up to date.

Update card details

You can update any card details using the PUT /cards/{card_id} request. You can update any of the required information by adding the parameter to the body of the request (any fields not added will be left unchanged).

📘

Note

To update billing or shipping data, you must use the PUT /customers/{customer_id} request as these parameters sit within the customer object.

In the below request we are updating the cardholder name:

{
  "holder_name": "E Smith"
}

📘

Note

To update any customer parameters such as billing details, you must navigate to the /customers endpoint. Refer to our customers documentation here.

Testing card payments

For more information on how to test card payments, view our test card suite here.

Updated 7 months ago