PSP API Guide

Overview

The PSP API enables compliant merchants, Payment Service Providers (PSPs) and Payment Orchestration Platforms to process transactions through Acquired’s acquiring connections without relying on the customer and card management system. This API is designed to provide a direct, streamlined payment processing flow while allowing PSPs to maintain full control over customer authentication, tokenization, digital wallets and risk management.

Unlike traditional integrations, where merchants store customer and payment details within Acquired’s platform, this API allows PSPs to pass full card data, network tokens, and cryptograms directly in the request.

The PSP Payments API provides endpoints for processing a variety of card-not-present transactions, including one-time payments, recurring transactions, and digital wallet payments (Apple Pay and Google Pay).

Key features

• Direct acquirer access: Enables PSPs to connect to Acquired’s acquiring relationships without requiring customer_id and card_id.
• Full card data support: Accepts PANs (Primary Account Numbers) and network tokens for processing transactions.
• Digital wallet support: Handles Apple Pay and Google Pay payments using decrypted tokens.
• Recurring payments: Supports MIT transactions with scheme reference data and the Mastercard Transaction Link Identifier (TLID).
• 3-D Secure (3DS) support: Allows 3DS authentication from another provider to be integrated.
• Seamless refund, capture, and void operations: Fully compatible with existing /v1/transactions/void, /v1/transactions/capture, and /v1/transactions/refund endpoints.

Supported endpoints

Add a table below here with this information and link to the area of the guide.

Authentication

Please follow our standard API authentication process for this API.

Endpoints

Endpoint POST /psp-payments

The POST /psp-payments endpoint functions similarly to the standard [/payments](https://docs.acquired.com/reference/create-payment) endpoint. You can process one-time card transactions by passing full card details in the request.

All validation rules, transaction processing, and response structures remain the same as /payments, except for the differences outlined below.

Key Differences from /payments

1. Nocustomer_id or card_id:

• You must send full customer and card details in the request instead of referencing a stored customer_id or card_id.

2. credential_on_filehandling:

• This field determines whether the transaction is a standalone payment or if card credentials are being stored for future use.
• Default behaviour: If omitted, it defaults to false.
• Accepted values:
  • false → Standalone transaction (default).
  • true → Indicates that card details are being stored for future use.

3. 3-D Secure (TDS) handling_(Optional)_:

• Default behaviour: If omitted, it defaults to false.
• If tds.is_active = true, the request must include:
  • tds.version ("2.X.X")
  • tds.eci ("01", "02", "05", "06")
  • tds.ds_transaction_id
  • tds.authentication_value

Request

{
  "transaction": {
    "order_id": "1f1f2a61-5b68-4725-a0ce-9560514ec00b",
    "amount": {{$randomPrice}},
    "currency": "gbp",
    "moto": false,
    "capture": true,
    "custom_data": "",
    "custom_1": "",
    "custom_2": ""
  },
  "payment": {
    "card": {
      "holder_name": "E Johnson",
      "number": "4000011180138710",
      "expiry_month": 10,
      "expiry_year": 26,
      "cvv": "123"
    },
    "credential_on_file": false,
    "reference": "Custom Ref 001"
  },
  "customer": {
    "first_name": "Edward",
    "last_name": "Johnson",
    "dob": "1988-10-03",
    "billing": {
      "address": {
        "line_1": "152 Aldgate Drive",
        "postcode": "E1 7RT"
      }
    }
  },
  "tds": {
    "is_active": true,
    "version": "2.2.0",
    "eci": "02",
    "ds_transaction_id": "eb7b98d8-c8d2-4fa3-acf1-64b4be9d1500",
    "authentication_value": "kANpUZhEE9xhIgH0rULj/IJhGAyr"
  }
}

Response

{
    "transaction_id": "019514d8-771f-7082-b8a7-2ea21ae8d4e9",
    "status": "success",
    "issuer_response_code": "00",
    "check": {
        "avs_line1": "matched",
        "avs_postcode": "matched",
        "cvv": "matched"
    },
    "scheme_reference_data": "135412000000000",
    "transaction_link_id": null,
    "links": [
        {
            "rel": "self",
            "href": "/v1/transactions/019514d8-771f-7082-b8a7-2ea21ae8d4e9"
        }
    ]
}

Cardholder-Initiated Transactions (CIT)

Endpoint: POST /psp-payments/reuse

The POST /psp-payments/reuse endpoint functions similarly to the standard [/payments/reuse](https://docs.acquired.com/reference/create-payment-stored-card) endpoint. You can process a payment using a stored card or a network token by passing full card details in the request.

All validation rules, transaction processing, and response structures remain the same as /payments/reuse, except for the differences outlined below.

Key Differences from /payments/reuse

1. No customer_id or card_id:

• You must send full card details or a network token in the request instead of referencing a stored customer_id or card_id.

2. is_network_tokenHandling_(Optional):_

• This field indicates whether the request is using a full PAN (Primary Account Number) or a Network Token.
• Default behaviour: If omitted, it defaults to false.
• Accepted values:
  • false → The transaction is processed using a full PAN.
  • true → The transaction is processed using a Network Token, and network_token_cryptogram is required.

3. network_token_cryptogram Handling (Required ifis_network_token = true)

• If is_network_token = true, network_token_cryptogram must be included in the request.
  This value is required for authentication and must be passed in the request to the acquirer.

3. 3-D Secure (TDS) Handling_(Optional):_

• Default behaviour: If omitted, tds.is_active defaults to false.
• If tds.is_active = true, the request must include:
  • tds.version ("2.X.X")
  • tds.eci ("01", "02", "05", "06")
  • tds.ds_transaction_id
  • tds.authentication_value

This endpoint processes cardholder-initiated transactions (CIT) using network tokens or PAN.

{
  "transaction": {
    "order_id": "1f1f2a61-5b68-4725-a0ce-9560514ec00b",
    "amount": {{$randomPrice}},
    "currency": "gbp",
    "moto": false,
    "capture": true
  },
  "payment": {
    "card": {
      "holder_name": "E Johnson",
      "number": "40001180138710",
      "expiry_month": 10,
      "expiry_year": 26,
      "cvv": "123"
    },
    "is_network_token": false,
    "network_token_cryptogram": "",
    "reference": "Custom Ref 001"
  },
  "customer": {
    "first_name": "Edward",
    "last_name": "Johnson",
    "dob": "1988-10-03",
    "billing": {
      "address": {
        "line_1": "152 Aldgate Drive",
        "postcode": "E1 7RT"
      }
    }
  },
  "tds": {
    "is_active": true,
    "version": "2.2.0",
    "eci": "02",
    "ds_transaction_id": "eb7b98d8-c8d2-4fa3-acf1-64b4be9d1500",
    "authentication_value": "kANpUZhEE9xhIgH0rULj/IJhGAyr"
  }
}

• Set is_network_token to true if using a network token.
• Pass the token cryptogram if required by the schemes.

Merchant-Initiated Transactions (MIT)

Endpoint: POST /psp-payments/recurring

The POST /psp-payments/recurring endpoint functions similarly to the standard [/payments/recurring](https://docs.acquired.com/reference/create-recurring-payment) endpoint. You can process recurring payments using a stored card or a network token while passing scheme reference data and subscription details.

All validation rules, transaction processing, and response structures remain the same as /payments/recurring, except for the differences outlined below.

Key Differences from /payments/recurring

1. Nocustomer_id or card_id:

• You must send full card details or a network token in the request instead of referencing a stored customer_id or card_id.

2. is_network_token Handling (Optional)

• This field indicates whether the request is using a full PAN (Primary Account Number) or a Network Token.
• Default behaviour: If omitted, it defaults to false.
• Accepted values:
  • false → The transaction is processed using a full PAN.
  • true → The transaction is processed using a Network Token, and network_token_cryptogram may be required depending on scheme rules.

3. network_token_cryptogramHandling_(Optional, Scheme Dependent)_

• If is_network_token = true, network_token_cryptogram should be included if required by the schemes.
• If a cryptogram is required for this authorisation, it must be included and passed in the request to the acquirer.

4. scheme_reference_dataHandling (Optional):

• If provided, must follow scheme-specific formatting rules:
• Visa: ^\\d{15}$ (15-digit numeric value).
• Mastercard: ^[A-Z0-9]{13}$ (13-character alphanumeric value).

5. transaction_link_idHandling (Optional, Mastercard only):

• The Mastercard Transaction Link Identifier (TLID) returned on the cardholder-initiated transaction that set up the agreement. If you vault cards yourself, store it alongside scheme_reference_data and send it on every MIT for that agreement.
• Mastercard TLIDs are 22 characters. The field accepts up to 36 characters.
• See Transaction Link Identifier (TLID) for more on the Mastercard mandate.

6. subscription_reasonHandling_(Optional)_

• This field must follow the same accepted values as /payments/recurring.
• If omitted, the default value configured at the MID level will be used.

Use this endpoint for recurring payments or merchant-initiated transactions (MIT) using network tokens or PAN.

{
  "transaction": {
    "order_id": "1f1f2a61-5b68-4725-a0ce-9560514ec00b",
    "amount": {{$randomPrice}},
    "currency": "gbp",
    "capture": true
  },
  "payment": {
    "card": {
      "holder_name": "E Johnson",
      "number": "40001180138710",
      "expiry_month": 10,
      "expiry_year": 26
    },
    "is_network_token": false,
    "network_token_cryptogram": "",
    "scheme_reference_data": "",
    "transaction_link_id": ""
  },
  "customer": {
    "first_name": "Edward",
    "last_name": "Johnson",
    "dob": "1988-10-03",
    "billing": {
      "address": {
        "line_1": "152 Aldgate Drive",
        "postcode": "E1 7RT"
      }
    }
  },
  "subscription_reason": "",
  "reference": "Custom Ref 001"
}

Apple Pay Payments

Endpoint: POST /psp-payments/apple-pay

The POST /psp-payments/apple-pay endpoint functions similarly to the standard [/payments/apple-pay](https://docs.acquired.com/reference/create-apple-pay) endpoint. PSPs can process Apple Pay transactions by passing decrypted payment details from an Apple Pay token.

All validation rules, transaction processing, and response structures remain the same as /payments/apple-pay, except for the differences outlined below.

Key Differences from /payments/apple-pay

1. PSPs Handle Apple Pay Token Decryption

• Acquired does not handle token decryption.
• The PSP must decrypt the Apple Pay token using their own Apple Merchant Certificates before submitting the request.

2. No customer_id or card_id:

• You must send full decrypted Apple Pay card details in the request instead of referencing a stored customer_id or card_id.

3. credential_on_fileHandling_(Optional)_

• This field determines whether the transaction is a standalone payment or if card credentials are being stored for future use.
• Default behaviour: If omitted, it defaults to false.
• Accepted values:
  • false → Standalone transaction (default).
  • true → Indicates that card details are being stored for future use.

4. online_payment_cryptogramHandling_(Required)_:

• This field is mandatory and must be passed in the request.

5. eci_indicatorHandling_(Optional but Required for Visa)_

• If provided, eci_indicator must be included in the request.
• If omitted, the request should still include the field with a blank value for consistency.

Use this endpoint for Apple Pay transactions where you handle decryption yourself.

• Flag the transaction as "putting a card on file" if required.

{
  "transaction": {
    "order_id": "c47e7432-57c5-4d4f-a3c2-f7c0f4720824",
    "amount": {{$randomPrice}},
    "currency": "gbp",
    "capture": true
  },
  "payment": {
    "card": {
      "number": "40001180138710",
      "expiry_month": 10,
      "expiry_year": 26
    },
  	"credential_on_file": false,
  	"online_payment_cryptogram": "AABBCCDDEEFF11223344556677889900",
  	"eci_indicator": "5",
  },
  "customer": {
    "first_name": "Edward",
    "last_name": "Johnson",
    "dob": "1988-10-03",
    "billing": {
      "address": {
        "line_1": "152 Aldgate Drive",
        "postcode": "E1 7RT"
      }
    }
  },
  "reference": "Custom Ref 0001"
}

Google Pay Payments

Endpoint: POST /psp-payments/google-pay

The POST /psp-payments/google-pay endpoint functions similarly to the standard [/payments/google-pay](https://docs.acquired.com/reference/create-google-pay) endpoint. PSPs can process Google Pay transactions by passing decrypted payment details from a Google Pay token.

All validation rules, transaction processing, and response structures remain the same as /payments/google-pay, except for the differences outlined below.

Key Differences from/payments/google-pay:

1. PSPs Handle Google Pay Token Decryption:

• Acquired does not handle token decryption.
• The PSP must decrypt the Google Pay token using their own Google Pay Merchant Keys before submitting the request.

2. Nocustomer_id or card_id:

• You must send full decrypted Google Pay card details in the request instead of referencing a stored customer_id or card_id.

3. credential_on_fileHandling_(Optional)_:

• This field determines whether the transaction is a standalone payment or if card credentials are being stored for future use.
• Default behaviour: If omitted, it defaults to false.
• Accepted values:
  • false → Standalone transaction (default).
  • true → Indicates that card details are being stored for future use.

4. HandlingPAN_ONLY vs. CRYPTOGRAM_3DS Transactions:

• Google Pay transactions can be processed using one of two authentication methods:

PAN_ONLY Transactions

• The card number is provided, but no cryptogram is included.
• 3-D Secure (tds) can be used to authenticate the transaction if required.
• If tds.is_active = true, the request must include:
  • tds.version ("2.X.X")
  • tds.eci (01, 02, 05, 06)
  • tds.ds_transaction_id
  • tds.authentication_value
• If tds.is_active = false, no 3-D Secure authentication will be applied.

CRYPTOGRAM_3DS Transactions

• The request includes an online payment cryptogram and an ECI indicator.
• Required fields for CRYPTOGRAM_3DS transactions:
  • online_payment_cryptogram → A cryptographic value used for authentication. (Mandatory for this flow.)
  • eci_indicator → Electronic Commerce Indicator (ECI) value. (Optional but recommended, particularly for Visa.)
  • Accepted values for eci_indicator: 0, 1, 2, 5, 6, 7.
  • If eci_indicator is omitted, the request should still include the field with a blank value for consistency.

Use this endpoint for Google Pay transactions using either CRYPTOGRAM_3DS or PAN_ONLY methods.

• Flag the transaction as "putting a card on file" if required.

{
  "transaction": {
    "order_id": "c47e7432-57c5-4d4f-a3c2-f7c0f4720824",
    "amount": {{$randomPrice}},
    "currency": "gbp",
    "capture": true
  },
  "payment": {
    "card": {
      "number": "40001180138710",
      "expiry_month": 10,
      "expiry_year": 26
    },
    "credential_on_file": false,
  	"online_payment_cryptogram": "AABBCCDDEEFF11223344556677889900",
  	"eci_indicator": "5",
  },
  "customer": {
    "first_name": "Edward",
    "last_name": "Johnson",
    "dob": "1988-10-03",
    "billing": {
      "address": {
        "line_1": "152 Aldgate Drive",
        "postcode": "E1 7RT"
      }
    }
  },
  "tds": {
    "is_active": true,
    "version": "2.2.0",
    "eci": "02",
    "ds_transaction_id": "171a8359-a4eb-4910-8951-73cf23e9c1ed",
    "authentication_value": "kANpUZhEE9xhgHrULj/IJhGAyr"
  },
  "reference": "Custom Ref 0001",
}

External Recurring Payments

Endpoint: POST /psp-payments/recurring

External recurring allows merchants to process recurring transactions across multiple payment processors while maintaining a single Continuous Payment Authority (CPA).

To maintain continuity across processors, you must include the following fields in the /psp-payments/recurring request:

The external recurring capability has been updated to support tokenisation, Account Updater, and Network Tokenisation.

1. Tokenising Transactions:

• Merchants may include create_card: true in the API request to generate a card_id. This requires the request to also include a customer_id.

Card creation rules:

2. Account Updater Integration:

• Declines with specific status or reason codes continue to trigger the Account Updater process.
• card_ids nearing expiry remain included in the monthly Account Updater batch (when enabled).

3. Network Tokenisation Integration:

If network tokens are enabled for the merchant:

• Provision a network token automatically on successful authorisation and card_id creation.
• All future payments using that card_id will use:
  • The active network token, and
  • The stored SRD value, and
  • The stored TLID value (Mastercard).
• Network token lifecycle management (status updates, webhooks, expiry logic) remains unchanged.