Update Payment Link Financial Details

Updates the financial details (amounts) of an existing payment link. This endpoint is separate from the general update endpoint to ensure proper authorization and audit trails for financial changes.

Endpoint

PUT /api/v1/paymentLinks/{id}/financial-details

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

Parameter	Type	Required	Description
amounts	object	required	Updated payment amounts (see Amounts object below)
items	array	required	Array of payment link line items (minimum 1). See Item object in POST endpoint

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

Response Parameters

Status Code: 200 OK

Returns the complete updated payment link object with the same structure as the POST /paymentLinks response.

Example Request

{
  "amounts": {
    "currency": "GBP",
    "subtotal": 150000,
    "total": 150000
  },
  "items": [
    {
      "description": "Consulting Services - October 2024",
      "quantity": 12,
      "unitPrice": 12500,
      "amount": 150000
    }
  ]
}

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": 150000,
    "total": 150000
  },
  "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": 12,
      "unitPrice": 12500,
      "amount": 150000,
      "offlinePaidAmount": 0
    }
  ],
  "metadata": {
    "projectId": "PROJ-456",
    "department": "Professional Services"
  },
  "createdAt": "2024-10-16T15:30:00Z",
  "updatedAt": "2024-10-16T17:00: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
• Sum of items amounts must match the total

Status Code: 404 Not Found

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

Important Notes

• Payment link financial details cannot be updated unless the payment link has status created. Only payment links with status created can be updated.
• Financial changes are logged in the payment link's history for audit purposes
• The total amount must be at least 31 (in minor units)
• The sum of all items[].amount values must equal the amounts.total