Record Offline Payment

Records an offline payment against a payment link. This endpoint is used when a payment is received through channels outside the payment link (e.g., bank transfer, cash, check) and needs to be recorded in the system.

Endpoint

PUT /api/v1/paymentLinks/{id}/offline-payment

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

Path Parameters

Parameter	Type	Required	Description
id	uuid	required	Unique identifier for the payment link

Request Parameters

Field	Type	Required	Description
amount	long	required	Total payment amount in minor units (minimum 1)
externalPaymentReference	string	optional	External payment reference
items	array	optional	Allocates the payment across specific line items (see Item object below). When omitted, the payment is recorded against the payment link as a whole

Item Object

Provide items when an offline payment should be attributed to individual line items (for example, part-paying an invoice item by item). Each entry records how much of the payment applies to a specific item.

Field	Type	Required	Description
id	uuid	required	Identifier of the line item the amount is allocated to
amount	long	required	Amount allocated to this item in minor units (minimum 1)

When items is supplied the following rules apply:

• A maximum of 100 items can be included.
• Item id values must be unique — duplicates are rejected.
• Each item amount must be greater than zero.
• The sum of all item amount values must exactly equal the top-level amount.

Response Parameters

Status Code: 200 OK

Returns the complete updated payment link object with the same structure as the POST /paymentLinks response, including the recorded offline payment in the payments array. Each entry in the items array includes an offlinePaidAmount field showing the cumulative offline amount recorded against that item.

Example Request

Recording a payment against the payment link as a whole:

{
  "amount": 120000,
  "externalPaymentReference": "TRX-20241016-001"
}

Allocating the payment across specific line items:

{
  "amount": 120000,
  "externalPaymentReference": "TRX-20241016-001",
  "items": [
    {
      "id": "9b2e7c14-4f1a-4d3b-8a21-6c0f5e2d1a77",
      "amount": 80000
    },
    {
      "id": "2f5a8d90-7c33-49e2-b1d4-3e6a9c0b2f18",
      "amount": 40000
    }
  ]
}

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": 120000,
    "total": 120000
  },
  "dates": {
    "requestedDate": "2024-10-16T00:00:00Z",
    "dueDate": "2024-11-30T00:00:00Z",
    "linkExpiryDate": "2024-12-31T23:59:59Z"
  },
  "currencyCode": "GBP",
  "statusCode": "paid",
  "statusChangedAt": "2024-10-16T14:30:00Z",
  "paymentLinkUrl": "https://group.pay.accessacloud.com/pay/550e8400-e29b-41d4-a716-446655440000",
  "paidAmount": 120000,
  "lastAccessedAt": null,
  "accessCount": 0,
  "items": [
    {
      "id": "9b2e7c14-4f1a-4d3b-8a21-6c0f5e2d1a77",
      "description": "Consulting Services - October 2024",
      "quantity": 8,
      "unitPrice": 10000,
      "amount": 80000,
      "offlinePaidAmount": 80000
    },
    {
      "id": "2f5a8d90-7c33-49e2-b1d4-3e6a9c0b2f18",
      "description": "Onboarding Setup Fee",
      "quantity": 1,
      "unitPrice": 40000,
      "amount": 40000,
      "offlinePaidAmount": 40000
    }
  ],
  "metadata": {
    "projectId": "PROJ-456",
    "department": "Professional Services"
  },
  "createdAt": "2024-10-16T15:30:00Z",
  "updatedAt": "2024-10-16T17:15: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:

• Amount must be greater than 0
• An offline payment cannot include more than 100 items
• Offline payment items must not contain duplicate item ids
• Each offline payment item amount must be greater than zero
• The sum of the item amounts must equal the payment amount

Status Code: 404 Not Found

Returned when no payment link is found for the given id.

Important Notes

• This operation can only be performed on payment links with status created or partially_paid
• Recording an offline payment will automatically update the payment link status to paid if the payment amount covers the total amount
• If a partial payment is recorded, the payment link status will become partially_paid
• Offline payments are included in the payment link's payment history
• The amount field is a flat field in the request body, not nested inside a payment object
• The items field is optional; when provided, the sum of item amounts must equal the top-level amount
• When items are supplied, each item's cumulative offline amount is reflected in the offlinePaidAmount field of the corresponding item in the response