Create Payment Links in Bulk

Creates multiple payment links in a single request. Each payment link in the batch is processed and reported individually, so the batch can partially succeed: some links may be created while others fail validation. Because of this, the endpoint always responds with 207 Multi-Status when the request itself is well-formed — you must inspect each item in the results array to determine its outcome.

The request groups payment links per merchant. In v1 a batch is restricted to a single merchant group and a maximum of 100 payment links; the grouped shape is forward-compatible with multi-merchant batches planned for a future version.

Endpoint

POST /api/v1/paymentLinks/batch

Header Parameters

Parameter	Type	Required	Description
`x-api-key`	string	required	PaySuite provided API key
`Content-Type`	string	required	Must be `application/json`
`Idempotency-Key`	string	optional	Unique key (max 255 characters) that makes the request safe to retry. See Idempotency

The batch is scoped to your division account, which PaySuite resolves from your API key. Unlike the other endpoints, no merchantId header is required — each merchant is specified per group in the request body and verified against your division. Payment links for a merchant that cannot be verified fail individually with a FORBIDDEN error rather than failing the whole batch.

Request Parameters

Parameter	Type	Required	Description
`merchants`	array	required	Array of merchant groups. In v1 exactly one group is allowed (minimum 1, maximum 1)

MerchantBatchGroup Object

Field	Type	Required	Description
`merchantId`	string	required	Merchant the payment links belong to
`paymentLinks`	array	required	Payment links to create for this merchant. Each entry has the same shape as the Create Payment Link request body

The total number of payment links across all groups must be between 1 and 100.

Response Parameters

Status Code: `207 Multi-Status`

Returned whenever the request is well-formed. Individual outcomes are reported per item — inspect results[].status to determine which links were created.

Parameter	Type	Description
`batchId`	uuid	Unique identifier for this batch. Also written to each created link's `metadata.batchId`
`summary`	object	Aggregate counts (see BatchSummary below)
`results`	array	Per-item outcomes (see BatchResultItem below)

BatchSummary Object

Field	Type	Description
`totalRequested`	integer	Total number of payment links submitted in the batch
`succeeded`	integer	Number of payment links successfully created
`failed`	integer	Number of payment links that failed

BatchResultItem Object

Field	Type	Description
`index`	integer	Zero-based position of the item in the flattened request (across all groups)
`merchantId`	string	Merchant the item belonged to
`externalReference`	string	External reference of the submitted payment link (nullable)
`status`	string	Item outcome: `created` or `failed`
`paymentLink`	object	The created payment link (same structure as the Create Payment Link response). `null` when the item failed
`error`	object	Error details when the item failed (see BatchItemError below). `null` when the item succeeded

BatchItemError Object

Field	Type	Description
`code`	string	Error code, e.g. `VALIDATION_ERROR`, `FORBIDDEN`, `CONFLICT`, `BUSINESS_ERROR`
`message`	string	Human-readable error message
`details`	object	Additional error context (nullable)

Idempotency

Batch creation is not automatically idempotent: retrying a request without an idempotency key will create the payment links again. To make a batch safe to retry, supply an Idempotency-Key header with a unique value (for example a UUID) per logical batch. The key may be at most 255 characters; a longer value is rejected with 400 Bad Request.

Idempotency keys are scoped to your division account:

First request — processed normally; the response and status code are stored and remain replayable for 24 hours.
Retry with the same key and the same request body — the stored response is returned verbatim, without creating the links again. Replayed responses include an Idempotent-Replayed: true response header so they are easy to distinguish from freshly processed ones.
Same key with a different request body — the API responds with 409 Conflict.
Same key while the original request is still being processed — the API responds with 409 Conflict.

Example Request

{
  "merchants": [
    {
      "merchantId": "A91C4B87-3D0E-4B46-8E52-9BD4E57EAA98",
      "paymentLinks": [
        {
          "customer": {
            "name": "John Smith",
            "email": "[email protected]"
          },
          "description": "Invoice #INV-2024-101",
          "externalReference": "INV-2024-101",
          "amounts": {
            "currency": "GBP",
            "total": 125000
          },
          "dates": {
            "requestedDate": "2024-10-16T00:00:00Z"
          },
          "items": [
            {
              "description": "Consulting Services",
              "quantity": 1,
              "unitPrice": 125000,
              "amount": 125000
            }
          ]
        },
        {
          "customer": {
            "name": "Jane Wilson",
            "email": "[email protected]"
          },
          "description": "Invoice #INV-2024-102",
          "externalReference": "INV-2024-102",
          "amounts": {
            "currency": "GBP",
            "total": 20
          },
          "dates": {
            "requestedDate": "2024-10-16T00:00:00Z"
          },
          "items": [
            {
              "description": "Web Development Services",
              "quantity": 1,
              "unitPrice": 20,
              "amount": 20
            }
          ]
        }
      ]
    }
  ]
}

Example Response

{
  "batchId": "b7f1c2d3-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "summary": {
    "totalRequested": 2,
    "succeeded": 1,
    "failed": 1
  },
  "results": [
    {
      "index": 0,
      "merchantId": "A91C4B87-3D0E-4B46-8E52-9BD4E57EAA98",
      "externalReference": "INV-2024-101",
      "status": "created",
      "paymentLink": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "paymentLinkId": "PL-20241016153000-a1b2c3",
        "divisionAccountId": "6F2A9C31-8B45-4E0B-9C77-12AF34D9B201",
        "merchantId": "A91C4B87-3D0E-4B46-8E52-9BD4E57EAA98",
        "description": "Invoice #INV-2024-101",
        "externalReference": "INV-2024-101",
        "amounts": {
          "currency": "GBP",
          "subtotal": 125000,
          "total": 125000
        },
        "currencyCode": "GBP",
        "statusCode": "created",
        "paymentLinkUrl": "https://group.pay.accessacloud.com/pay/550e8400-e29b-41d4-a716-446655440000",
        "paidAmount": 0,
        "metadata": {
          "batchId": "b7f1c2d3-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
        },
        "version": 1
      },
      "error": null
    },
    {
      "index": 1,
      "merchantId": "A91C4B87-3D0E-4B46-8E52-9BD4E57EAA98",
      "externalReference": "INV-2024-102",
      "status": "failed",
      "paymentLink": null,
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "The payment link is invalid.",
        "details": {
          "field": "amounts.total",
          "reason": "Total amount must be greater than 30."
        }
      }
    }
  ]
}

Status Code: `400 Bad Request`

Returned when the request itself is malformed, before any items are processed. Common causes:

The request body is missing or is not valid JSON
No merchant groups were supplied
More than one merchant group was supplied (v1 allows a single group)
No payment links were supplied
The batch contains more than 100 payment links
The Idempotency-Key header exceeds 255 characters

Status Code: `401 Unauthorized`

Returned when the API key is missing or invalid.

Status Code: `409 Conflict`

Returned when the supplied Idempotency-Key has already been used with a different request body, or an identical request with the same key is still being processed. See Idempotency.

Important Notes

The endpoint returns 207 Multi-Status even when every item fails validation — always check summary and each results[].status.
results preserves the order of the submitted payment links; use index to correlate each outcome with your request.
Every successfully created payment link has the batch's batchId recorded under metadata.batchId, allowing you to retrieve all links created by a batch.
Validation applied to each item is identical to the single Create Payment Link endpoint.
Use an Idempotency-Key whenever you might retry a batch to avoid creating duplicate links.

Endpoint​

Header Parameters​

Request Parameters​

MerchantBatchGroup Object​

Response Parameters​

Status Code: 207 Multi-Status​

BatchSummary Object​

BatchResultItem Object​

BatchItemError Object​

Idempotency​

Example Request​

Example Response​

Status Code: 400 Bad Request​

Status Code: 401 Unauthorized​

Status Code: 409 Conflict​

Important Notes​