Payments

External CRUD for billing payments.

Payments

Prefix: /api/v1/external/payments

See Overview for authentication, pagination, and errors.

Flat CRUD for the billing Payment object. Create goes through the platform payment manager (required-field validation and default approval / GL status).

Endpoint summary

Method	Path
GET	`/payments`
GET	`/payments/{paymentId}`
POST	`/payments`
PUT	`/payments/{paymentId}`
DELETE	`/payments/{paymentId}`

List payments

GET /api/v1/external/payments?page=0&size=20&q=PAY-2026
Authorization: Bearer YOUR_API_TOKEN

Query	Description
`page`	0-based page index (default `0`)
`size`	Page size (default 20, max 20)
`q`	Optional search on `paymentReference`, `comments`, `participantName`

Response 200 — ApiResponse + Spring Page. See Overview.

{
  "requestId": "req-1",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "content": [
      {
        "__type__": "Payment",
        "Id": "4b6a8d20-1c3e-4f79-a5b2-8e0d7c6f9a31",
        "AccountId": "11111111-1111-1111-1111-111111111111",
        "PaymentReference": "PAY-2026-0001",
        "Amount": 250.0
      }
    ],
    "totalElements": 1,
    "size": 20,
    "number": 0
  }
}

Get payment

GET /api/v1/external/payments/{paymentId}
Authorization: Bearer YOUR_API_TOKEN

Response 200

{
  "id": "4b6a8d20-1c3e-4f79-a5b2-8e0d7c6f9a31",
  "accountId": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "amount": 250.0,
  "paymentReference": "PAY-2026-0001",
  "paymentMethod": "Wire Transfer",
  "paymentType": "Pay In",
  "paymentDate": "2026-08-29",
  "paymentStatus": "Completed",
  "balanceStatus": "Unapplied",
  "balance": 250.0,
  "glPaymentDate": "2026-08-29",
  "paymentGlStatus": "Pending",
  "approvalStatus": "Approved",
  "isManualPayment": true,
  "comments": "Wire received"
}

Create payment

POST /api/v1/external/payments
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Required fields: accountId, currency, paymentReference, paymentMethod, paymentDate, paymentType.

Request

{
  "accountId": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "amount": 250.0,
  "paymentReference": "PAY-2026-0001",
  "paymentMethod": "Wire Transfer",
  "paymentType": "Pay In",
  "paymentDate": "2026-08-29",
  "isManualPayment": true,
  "comments": "Wire received"
}

curl -sS -X POST "https://YOUR_TENANT_HOST/api/v1/external/payments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "11111111-1111-1111-1111-111111111111",
    "currency": "USD",
    "amount": 250.0,
    "paymentReference": "PAY-2026-0001",
    "paymentMethod": "Wire Transfer",
    "paymentType": "Pay In",
    "paymentDate": "2026-08-29"
  }'

Response 201 — the full payment, identical in shape to Get payment.

Response 409 on a duplicate paymentReference.

{
  "status": 409,
  "error": "Conflict",
  "message": "Payment paymentReference already exists",
  "path": "uri=/api/v1/external/payments"
}

Update payment

PUT /api/v1/external/payments/{paymentId}
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Request

{
  "amount": 275.0,
  "comments": "Adjusted for FX difference",
  "paymentStatus": "Completed"
}

Response 200

{
  "id": "4b6a8d20-1c3e-4f79-a5b2-8e0d7c6f9a31",
  "accountId": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "amount": 275.0,
  "paymentReference": "PAY-2026-0001",
  "paymentMethod": "Wire Transfer",
  "paymentType": "Pay In",
  "paymentDate": "2026-08-29",
  "paymentStatus": "Completed",
  "comments": "Adjusted for FX difference"
}

Delete payment

DELETE /api/v1/external/payments/{paymentId}
Authorization: Bearer YOUR_API_TOKEN

Response 204 — no body.

On this page