Notifications (Webhooks)

AutoPay uses this endpoint to notify you about failed charges and lifecycle changes.

Important:

Approved transactions are sent exclusively via Settlement.
Although this endpoint is part of Contracts and there is Contracts Authentication, the mechanism to validate message integrity is the Digital Signature described below.

Available events

Event	Description
`AUTOPAY_CREATED`	Registration finished and autopay is active.
`AUTOPAY_UPDATED`	Payment method or rules were updated.
`AUTOPAY_TRANSACTION_FAILED`	Automatic charge attempt failed (e.g., insufficient funds).
`AUTOPAY_CANCELED`	Autopay has been canceled.

Security validation (signatures)

It is critical to verify that the notification comes from Placetopay. We digitally sign every message. You must replicate the signing process on your server and compare the result.

Validation example:

Suppose your secretKey is ABC123example456trankey+789abc012def3456ABC= and you receive:

1. Received Payload

{
   "id": "111111-2222-3333-4444-555555555555",
   "type": "AUTOPAY_TRANSACTION_FAILED",
   "date": "2023-01-01 12:00:00",
   "signature": "sha256:a1b2c3d4e5..."
}

Step-by-step process

Concatenate: Join id, type, date, and your secretKey (in this exact order, without spaces or separators).

String = 111111-2222-3333-4444-555555555555 + AUTOPAY_TRANSACTION_FAILED + 2023-01-01 12:00:00 + ABC123example456trankey+789abc012def3456ABC=
Hash: Apply the SHA-256 algorithm to the resulting string.
Compare: If your hash matches the received signature (ignoring the sha256: prefix), the request is authentic.

If the signature does not match, respond with HTTP 400 and ignore the message. Never expose your secretKey in the frontend or public repositories.

POST/autopay/webhook

Webhook structure

Recommendation: The webhook is strictly an event notification. To guarantee you have the latest and most detailed information, it is recommended to query the Search AutoPay API using the received id.

Request

Name
id
Type
string
is Required
REQUIRED
Description
Unique identifier of the AutoPay.
Example:2972c13d-6315-4da3-80d7-64c24eb232ad
Format:uuid
Max length:36
Min length:36
Name
type
Type
string
is Required
REQUIRED
Description
Type of notified event. See more at Webhook events.
Allowed values:AUTOPAY_CREATEDAUTOPAY_UPDATEDAUTOPAY_CANCELEDAUTOPAY_TRANSACTION_FAILED
Name
date
Type
string
is Required
REQUIRED
Description
Date and time when the event was triggered for the first time, in ISO 8601 format.
Example:2025-09-29T17:09:29-05:00
Format:date-time
Name
signature
Type
string
is Required
REQUIRED
Description
Digital signature of the webhook payload for validation. See more at Webhook validation.
Example:sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s
Name
reference
Type
string
is Required
REQUIRED
Description
AutoPay reference provided by the client/merchant. This reference must be unique and active per merchant.
Example:ACC00012345
Max length:32
Name
additional
Type
object
is optional
CONDITIONAL
Description
Object containing relevant information to identify the AutoPay and event-related details.

Request

POST

{{baseURl}}/autopay/webhook

{
    "id": "2972c13d-6315-4da3-80d7-64c24eb232ad",
    "reference": "ACC00012345",
    "type": "AUTOPAY_CREATED",
    "date": "2023-01-19 15:57:23",
    "signature": "sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

Response

The webhook was received successfully.

Name
status
Type
Status
is optional
Description
Structure used to define response statuses.

Response

    {
      "status": {
         "status": "OK",
         "reason": "00",
         "message": "Successful response",
         "date": "2025-09-29T17:09:29-05:00"
      },
    }