Subscription webhook endpoint

post

https://api.payretailers.com/api/v1/subscription-events

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.

Body Params

eventType

string

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

eventId

string

Unique identifier for this event (use for idempotency)

eventDate

date-time

UTC timestamp when the event occurred

entityId

string

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

status

string

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

statusDate

date-time

UTC timestamp when the status changed

message

string | null

Optional message (e.g., cancellation reason)

errorCode

string | null

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

errorMessage

string | null

Human-readable error message

pspReference

string | null

Payment Service Provider reference

end2EndId

string | null

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

additionalData

array of objects | null

additionalData

Responses

204

Webhook received successfully - No Content

Language

Credentials

Basic

base64

URL

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

400Bad Request