Sign in

v1

latestOpenAPI 3.1.02026-07-263436159.3 KB
Webhook

Subscription webhook endpoint

This endpoint documents the webhook events that PayRetailers will send to your notificationUrl. You should implement this endpoint on your server to receive subscription and payment status updates.

post/api/v1/subscription-events

Request body

eventTypestring

Type of webhook event. Valid values: subscription_activation, subscription_cancellation, subscription.payment, subscription.payment_schedule, subscription.payment_cancellation

eventIdstring

Unique identifier for this event (use for idempotency)

eventDatestring date-time

UTC timestamp when the event occurred

entityIdstring

ID of the entity that triggered the event (Subscription or SubscriptionPayment ID)

statusstring

Current status of the entity. For subscriptions: PENDING_USER_AUTH, ACTIVE, CANCELLED, EXPIRED, REJECTED. For payments: PENDING, IN_PROGRESS, PAID, FAILED, CANCELLED

statusDatestring date-time

UTC timestamp when the status changed

messagestring nullable

Optional message (e.g., cancellation reason)

errorCodestring nullable

Error code if applicable. Common values: INSUFFICIENT_FUNDS, REJECTED_BY_BANK, CANCELLED_BY_USER, ACCOUNT_CLOSED, AUTHORIZATION_REVOKED, PAYMENT_EXPIRED

errorMessagestring nullable

Human-readable error message

pspReferencestring nullable

Payment Service Provider reference

end2EndIdstring nullable

End-to-End ID (PIX-specific transaction identifier)

Example request

{
  "eventType": "subscription.payment",
  "eventId": "event-guid-123",
  "eventDate": "2025-01-15T10:30:00Z",
  "entityId": "subscription-guid",
  "status": "PAID",
  "statusDate": "2025-01-15T10:35:00Z"
}

Response

Webhook received successfully - No Content