Card Payments

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.


Creating and saving cards

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",
        "moto": false,
        "capture": true
    },
    "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",
        "moto": false,
        "capture": true
    },
    "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.