API reference

The endpoints an in-store integration uses. All requests are authenticated with your API key and made against https://api-live.kcpboundless.com.

note

This reference is maintained by hand for now. It will be generated directly from the API's OpenAPI specification, so the published reference always matches the running service.

Payments

Take a payment

POST /api/in-store/payments

Sends a bill to a terminal and returns the payment in AWAITING_TERMINAL. See Accept a payment for the request body and response.

Check a payment's status

POST /api/in-store/payments/{id}/sync-status

Returns the current state of the payment, advancing it if the customer has finished at the device. Safe to call repeatedly.

Cancel a payment

POST /api/in-store/payments/{id}/cancel

Withdraws a bill that is still waiting at the terminal. If the customer completed the payment first, their payment stands and the response reports that instead. See Cancelling an open bill.

Read a payment

GET /api/transactions/{id}

The payment's current state, without contacting the terminal — the cheap call for routine polling. sync-status above is the one that refreshes from the device first.

List payments

GET /api/transactions?merchantExternalId={merchantExternalId}
      &from=&to=&status=&acquirerName=&q=&page=&size=

Paged, newest first. Filter by date range, status, or free text; page is 0-indexed and the response carries content plus totalElements / totalPages.

Stores

GET    /api/merchants/{merchantExternalId}/stores
GET    /api/merchants/{merchantExternalId}/stores/search?q=&status=&country=&hasTerminals=&sort=&page=&size=
POST   /api/merchants/{merchantExternalId}/stores
GET    /api/merchants/{merchantExternalId}/stores/{storeExternalId}
PUT    /api/merchants/{merchantExternalId}/stores/{storeExternalId}
DELETE /api/merchants/{merchantExternalId}/stores/{storeExternalId}[?force=true]

Create, read, update, and remove the stores under your business. The plain list is alphabetical; search adds free text, filters, sorting, and paging. Deletes cascade to the store's terminals and are guarded when the store took payments in the last 24 hours — see Removing safely.

Terminals

GET    /api/merchants/{merchantExternalId}/stores/{storeExternalId}/terminals
POST   /api/merchants/{merchantExternalId}/stores/{storeExternalId}/terminals
GET    /api/merchants/{merchantExternalId}/stores/{storeExternalId}/terminals/{terminalExternalId}
PUT    /api/merchants/{merchantExternalId}/stores/{storeExternalId}/terminals/{terminalExternalId}
DELETE /api/merchants/{merchantExternalId}/stores/{storeExternalId}/terminals/{terminalExternalId}[?force=true]

Create, read, update, and remove the terminals under a store. The same delete guard applies.

Webhook configuration

POST   /api/webhooks/configs                      create a destination
GET    /api/webhooks/configs                      list yours
GET    /api/webhooks/configs/{id}                 read one
PUT    /api/webhooks/configs/{id}                 update url or event selection
DELETE /api/webhooks/configs/{id}                 remove
POST   /api/webhooks/configs/{id}/regenerate-key  rotate the signing secret
POST   /api/webhooks/configs/{id}/test            send a TEST event now
GET    /api/webhooks/configs/{id}/events          delivery history
GET    /api/webhooks/events/{eventId}/attempts    per-delivery attempts

Create body: { "url": "https://...", "description": "...", "eventTypes": ["PAYMENT_CAPTURED"] } — omit eventTypes to receive every event. The response includes the signing secret. See Webhooks.

Status and error codes

Code	Meaning
200 OK	The request succeeded.
201 Created	The payment was accepted and is on the terminal.
400 Bad Request	The request body was invalid.
401 Unauthorized	The API key was missing or invalid.
403 Forbidden	The key may not perform this action.
404 Not Found	The resource does not exist, or does not belong to your business.
409 Conflict	The request conflicts with the current state of the resource — a duplicate terminal serial, or a delete guarded by recent payments.
429 Too Many Requests	Rate limit exceeded. Retry after a short pause.
5xx	A temporary problem on our side. Retry with backoff.