POS Payment Status Webhook Payload

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "consumerId": "60513141-4d0f-4d3d-9c8a-cc1bd61f40fd",
  "merchantName": "My Shop",
  "paymentIdempotencyId": "ATOA1695808662681",
  "status": "COMPLETED",
  "statusDetails": null,
  "paidAmount": 25.50,
  "tipAmount": 0,
  "currency": "GBP",
  "createdAt": "2026-03-20T14:30:00.000Z",
  "updatedAt": "2026-03-20T14:31:00.000Z",
  "taxAmount": 0,
  "serviceAmount": 0,
  "transactionType": "CARD",
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "orderId": "POS-ORDER-001",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "errorDescription": null,
  "redirectUrlParams": "{}",
  "splitBill": false,
  "notes": "POS terminal payment",
  "metadata": {
    "bookingId": "BK-42427",
    "orderReference": "ORD-1"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "consumerId": "60513141-4d0f-4d3d-9c8a-cc1bd61f40fd",
  "merchantName": "My Shop",
  "paymentIdempotencyId": "ATOA1695808662681",
  "status": "FAILED",
  "statusDetails": null,
  "paidAmount": 25.50,
  "tipAmount": 0,
  "currency": "GBP",
  "createdAt": "2026-03-20T14:30:00.000Z",
  "updatedAt": "2026-03-20T14:30:05.000Z",
  "taxAmount": 0,
  "serviceAmount": 0,
  "transactionType": "CARD",
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "orderId": "POS-ORDER-002",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "errorDescription": "Card processing error. Please try a different card.",
  "redirectUrlParams": "{}",
  "splitBill": false,
  "notes": "POS terminal payment",
  "metadata": {
    "bookingId": "BK-42427",
    "orderReference": "ORD-1"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "status": "EXPIRED",
  "paidAmount": 25.50,
  "currency": "GBP",
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "orderId": "POS-ORDER-003",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "redirectUrl": "https://paywithatoa.co.uk",
  "redirectUrlParams": {},
  "metadata": {
    "bookingId": "BK-42427",
    "orderReference": "ORD-1"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "COMPLETED",
  "paidAmount": 25.50,
  "refundAmount": 10.00,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "POS-ORDER-001",
  "createdAt": "2026-03-20T15:00:00.000Z",
  "updatedAt": "2026-03-20T15:01:30.000Z",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "FAILED",
  "paidAmount": 25.50,
  "refundAmount": 10.00,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "POS-ORDER-001",
  "createdAt": "2026-03-20T15:00:00.000Z",
  "updatedAt": "2026-03-20T15:01:30.000Z",
  "errorMessage": "The customer's bank rejected the refund. Please try again.",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

Delivers notifications for all POS terminal (Pax machine) activity:

Payments — Pay by Bank and card payments at the terminal.
Refunds (voids) — refunds from the POS terminal. Not delivered under REFUND_STATUS.

API or Dashboard refunds are delivered under REFUND_STATUS, not here.

Payment statuses

Status	Description
COMPLETED	Payment processed successfully. Funds have been transferred to the merchant’s account.
FAILED	Payment was unsuccessful, including reversed transactions. The customer will need to retry.
EXPIRED	Payment request expired before the customer completed the payment.

Refund statuses

Status	Description
COMPLETED	Refund processed successfully. Funds have been credited to the customer’s account.
FAILED	Refund could not be processed. The refund may need to be retried.

Distinguish payment from refund deliveries by checking for refundId. Refund payloads use refundId and refundAmount instead of payment fields like tipAmount and storeDetails.

V2 signing required: Subscribing to POS_PAYMENT_STATUS requires a V2 signing secret. All POS webhooks are delivered with V2 signing — the X-Atoa-Signature header contains the HMAC-SHA256 signature and the body includes an eventType field.

Payloads

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "consumerId": "60513141-4d0f-4d3d-9c8a-cc1bd61f40fd",
  "merchantName": "My Shop",
  "paymentIdempotencyId": "ATOA1695808662681",
  "status": "COMPLETED",
  "statusDetails": null,
  "paidAmount": 25.50,
  "tipAmount": 0,
  "currency": "GBP",
  "createdAt": "2026-03-20T14:30:00.000Z",
  "updatedAt": "2026-03-20T14:31:00.000Z",
  "taxAmount": 0,
  "serviceAmount": 0,
  "transactionType": "CARD",
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "orderId": "POS-ORDER-001",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "errorDescription": null,
  "redirectUrlParams": "{}",
  "splitBill": false,
  "notes": "POS terminal payment",
  "metadata": {
    "bookingId": "BK-42427",
    "orderReference": "ORD-1"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "consumerId": "60513141-4d0f-4d3d-9c8a-cc1bd61f40fd",
  "merchantName": "My Shop",
  "paymentIdempotencyId": "ATOA1695808662681",
  "status": "FAILED",
  "statusDetails": null,
  "paidAmount": 25.50,
  "tipAmount": 0,
  "currency": "GBP",
  "createdAt": "2026-03-20T14:30:00.000Z",
  "updatedAt": "2026-03-20T14:30:05.000Z",
  "taxAmount": 0,
  "serviceAmount": 0,
  "transactionType": "CARD",
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "orderId": "POS-ORDER-002",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "errorDescription": "Card processing error. Please try a different card.",
  "redirectUrlParams": "{}",
  "splitBill": false,
  "notes": "POS terminal payment",
  "metadata": {
    "bookingId": "BK-42427",
    "orderReference": "ORD-1"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "status": "EXPIRED",
  "paidAmount": 25.50,
  "currency": "GBP",
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "orderId": "POS-ORDER-003",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "redirectUrl": "https://paywithatoa.co.uk",
  "redirectUrlParams": {},
  "metadata": {
    "bookingId": "BK-42427",
    "orderReference": "ORD-1"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "COMPLETED",
  "paidAmount": 25.50,
  "refundAmount": 10.00,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "POS-ORDER-001",
  "createdAt": "2026-03-20T15:00:00.000Z",
  "updatedAt": "2026-03-20T15:01:30.000Z",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

{
  "refundId": "c4e92a73-5f12-47c9-8b31-6e54f2d8a91c",
  "paymentRequestId": "8f2471db-3456-9cd8-eff2-1a3b5c7d9e0f",
  "paymentIdempotencyId": "ATOA1893245678912",
  "status": "FAILED",
  "paidAmount": 25.50,
  "refundAmount": 10.00,
  "currency": "GBP",
  "refundNotes": "Customer requested partial refund",
  "orderId": "POS-ORDER-001",
  "createdAt": "2026-03-20T15:00:00.000Z",
  "updatedAt": "2026-03-20T15:01:30.000Z",
  "errorMessage": "The customer's bank rejected the refund. Please try again.",
  "metadata": {
    "refundReason": "damaged-item",
    "ticketId": "SUP-9981"
  },
  "customFields": [
    {
      "fieldName": "Invoice Number",
      "value": "INV-2026-0042",
      "filledBy": "BUSINESS"
    }
  ],
  "eventType": "POS_PAYMENT_STATUS"
}

Custom fields

Custom fields collected during the terminal payment appear as a customFields array. For refunds, custom fields from the original payment are carried over.

Field	Type	Description
`fieldName`	string	The name of the custom field (e.g. “Invoice Number”)
`value`	string	The value entered for the field
`filledBy`	string	Who provided the value — `BUSINESS` or `PAYEE`

Only present when custom fields were entered at the terminal. Not included in PAYMENTS_STATUS or EXPIRED_STATUS webhooks.

Metadata

Merchant-supplied metadata set when creating the payment appears as a metadata object — a flat map of string keys to string values. Unlike custom fields (entered at the terminal), metadata is supplied programmatically and is frozen at payment creation.

Only present when metadata was supplied on the payment. See Process Payment for the field limits.

Signature verification

All POS_PAYMENT_STATUS webhooks use V2 signing. To verify the signature, use the X-Atoa-Signature header as described in the V2 Webhook Signing guide.

Overview

Reference

Webhook

Card on File

POS Payment Status Webhook Payload

Payment statuses

Refund statuses

Payloads

Custom fields

Metadata

Signature verification

​Payment statuses

​Refund statuses

​Payloads

​Custom fields

​Metadata

​Signature verification

Payment statuses

Refund statuses

Payloads

Custom fields

Metadata

Signature verification