Create Payment Link

Creates a new payment link that can be shared with customers to collect payments.

Endpoint

POST /api/v1/paymentLinks

Header Parameters

Parameter	Type	Required	Description
x-api-key	string	required	PaySuite provided API key
merchantId	string	required	Customer identifier as provided during customer onboarding
Content-Type	string	required	Must be application/json

Request Parameters

Parameter	Type	Required	Description
customer	object	required	Customer information (see Customer object below)
description	string max(500)	required	Payment link description
externalReference	string max(100)	required	External reference identifier for the payment link
externalUrl	string max(1000)	optional	URL to redirect after payment completion
amounts	object	required	Payment amounts (see Amounts object below)
dates	object	required	Payment dates (see Dates object below)
items	array	required	Array of line items (minimum 1). See Item object below
metadata	object	optional	Additional metadata as key-value pairs

Customer Object

Field	Type	Required	Description
name	string max(200)	optional	Customer's full name
email	string max(255)	optional	Customer's email address
phone	string max(20)	optional	Customer's phone number
address	object	optional	Customer's address (see Address object below)

Address Object

Field	Type	Required	Description
line1	string max(200)	required	Address line 1
line2	string max(200)	optional	Address line 2
city	string max(100)	optional	City
state	string max(100)	optional	State or province
postalCode	string max(20)	optional	Postal or ZIP code
country	string max(2)	required	ISO 3166-1 alpha-2 country code

Amounts Object

Field	Type	Required	Description
currency	string	required	ISO 4217 currency code (e.g., GBP, USD)
subtotal	long	optional	Subtotal amount before adjustments (minimum 0)
total	long	required	Total amount to be paid in minor units (minimum 31). Sum of items[].amount must match this total

Dates Object

Field	Type	Required	Description
requestedDate	dateTime	required	Payment requested date (typically Invoice date) - ISO 8601 format
dueDate	dateTime	optional	Payment due date - ISO 8601 format
linkExpiryDate	dateTime	optional	Payment Link expiry date - ISO 8601 format

Item Object

Field	Type	Required	Description
description	string max(1000)	required	Item description
quantity	integer	required	Quantity of items (minimum 1)
unitPrice	long	required	Price per unit in minor units (minimum 1)
amount	long	required	Total item amount in minor units (minimum 1)
metadata	object	optional	Custom key-value pairs

Response Parameters

Status Code: 201 Created

Parameter	Type	Description
id	uuid	Unique identifier for the payment link
paymentLinkId	string	Generated payment link number
divisionAccountId	string	Division account identifier
merchantId	string	Merchant identifier
customer	object	Customer information
description	string	Payment link description
externalReference	string	External reference identifier
externalUrl	string	Redirect URL after payment
amounts	object	Payment amounts (currency, subtotal, total)
dates	object	Payment dates (requestedDate, dueDate, linkExpiryDate)
currencyCode	string	ISO 4217 currency code
statusCode	string	Payment link status (created, in_progress, paid, partially_paid, expired, cancelled)
statusChangedAt	dateTime	Last status change timestamp (ISO 8601)
paymentLinkUrl	string	The payment link URL to share with customers
paidAmount	long	Total paid amount in minor units
lastAccessedAt	dateTime	Last time the payment link was accessed (nullable)
accessCount	integer	Number of times the payment link has been accessed
items	array	Line items
metadata	object	Additional metadata
createdAt	dateTime	Creation timestamp (ISO 8601)
updatedAt	dateTime	Last update timestamp (ISO 8601)
createdBy	string	User who created the payment link
updatedBy	string	User who last updated the payment link
version	integer	Version number for optimistic concurrency

Example Request

{
  "customer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "address": {
      "line1": "123 High Street",
      "line2": "Apartment 4B",
      "city": "London",
      "state": "Greater London",
      "postalCode": "SW1A 1AA",
      "country": "GB"
    }
  },
  "description": "Invoice #INV-2024-001 - Consulting Services",
  "externalReference": "INV-2024-001",
  "externalUrl": "https://example.com/invoices/INV-2024-001",
  "amounts": {
    "currency": "GBP",
    "subtotal": 125000,
    "total": 125000
  },
  "dates": {
    "requestedDate": "2024-10-16T00:00:00Z",
    "dueDate": "2024-11-30T00:00:00Z",
    "linkExpiryDate": "2024-12-31T23:59:59Z"
  },
  "items": [
    {
      "description": "Consulting Services - October 2024",
      "quantity": 10,
      "unitPrice": 12500,
      "amount": 125000
    }
  ],
  "metadata": {
    "projectId": "PROJ-456",
    "department": "Professional Services"
  }
}

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "paymentLinkId": "PL-20241016153000-a1b2c3",
  "divisionAccountId": "6F2A9C31-8B45-4E0B-9C77-12AF34D9B201",
  "merchantId": "A91C4B87-3D0E-4B46-8E52-9BD4E57EAA98",
  "customer": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "address": {
      "line1": "123 High Street",
      "line2": "Apartment 4B",
      "city": "London",
      "state": "Greater London",
      "postalCode": "SW1A 1AA",
      "country": "GB"
    }
  },
  "description": "Invoice #INV-2024-001 - Consulting Services",
  "externalReference": "INV-2024-001",
  "externalUrl": "https://example.com/invoices/INV-2024-001",
  "amounts": {
    "currency": "GBP",
    "subtotal": 125000,
    "total": 125000
  },
  "dates": {
    "requestedDate": "2024-10-16T00:00:00Z",
    "dueDate": "2024-11-30T00:00:00Z",
    "linkExpiryDate": "2024-12-31T23:59:59Z"
  },
  "currencyCode": "GBP",
  "statusCode": "created",
  "statusChangedAt": "2024-10-16T15:30:00Z",
  "paymentLinkUrl": "https://group.pay.accessacloud.com/pay/550e8400-e29b-41d4-a716-446655440000",
  "paidAmount": 0,
  "lastAccessedAt": null,
  "accessCount": 0,
  "items": [
    {
      "id": "9b2e7c14-4f1a-4d3b-8a21-6c0f5e2d1a77",
      "description": "Consulting Services - October 2024",
      "quantity": 10,
      "unitPrice": 12500,
      "amount": 125000,
      "offlinePaidAmount": 0
    }
  ],
  "metadata": {
    "projectId": "PROJ-456",
    "department": "Professional Services"
  },
  "createdAt": "2024-10-16T15:30:00Z",
  "updatedAt": "2024-10-16T15:30:00Z",
  "createdBy": "api-key-user",
  "updatedBy": "api-key-user",
  "version": 1
}

Status Code: 400 Bad Request

Returned when the request validation fails. Common validation errors include:

• Total amount must be greater than 30
• Items array must contain at least 1 item
• Required fields missing (customer, description, externalReference, amounts, dates)
• Invalid currency code

Status Code: 401 Unauthorized

Returned when the API key is missing or invalid.