{"openapi":"3.1.0","info":{"title":"Boarding Webhooks","version":"1.0.0","license":{"name":"Proprietary","identifier":"Proprietary"},"description":"Webhook events emitted by merchant and enrollment status changes. Docs-only file: never consumed by codegen, so internal-only status values are stripped at build time."},"servers":[{"url":"https://api.sandbox.eu.ppro.com","description":"Production"}],"security":[],"webhooks":{"merchantStatusUpdated":{"post":{"operationId":"merchantStatusUpdated","tags":["Merchants"],"summary":"Merchant Status Updated","description":"Sent when a merchant's status changes. Delivered to the endpoint configured via `webhooksUrl` on the merchant (see CreateMerchantRequest/ UpdateMerchantRequest); subscription/registration of that endpoint is out of scope for this page.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantWebhookEnvelope"},"examples":{"suspended":{"summary":"SUSPENDED transition","value":{"specversion":"1.0.2","id":"evt_abcdefghijklmno123456","source":"https://www.ppro.com","type":"MERCHANT_STATUS_UPDATED","subject":"MIDNITH123","time":"2026-04-08T14:15:00.000Z","datacontenttype":"application/json","data":{"type":"MERCHANT_STATUS_UPDATED","merchantId":"MIDNITH123","externalMerchantReference":"ENTITY1234567890","currentStatus":{"status":"SUSPENDED","updatedAt":"2026-04-08T14:14:55.000Z","capabilities":{"canPay":false,"canRefund":true},"statusReason":{"reasonCode":"RISK_CHECK","reasonMessage":"The merchant has been flagged for risk and is under review"}},"previousStatus":{"status":"ACTIVE","updatedAt":"2026-04-07T10:00:00.000Z"}}}},"firstStatusEvent":{"summary":"First status event for a merchant (no previousStatus)","value":{"specversion":"1.0.2","id":"evt_bcdefghijklmnop234567","source":"https://www.ppro.com","type":"MERCHANT_STATUS_UPDATED","subject":"MIDNITH123","time":"2026-04-08T14:15:00.000Z","datacontenttype":"application/json","data":{"type":"MERCHANT_STATUS_UPDATED","merchantId":"MIDNITH123","externalMerchantReference":"ENTITY1234567890","currentStatus":{"status":"PENDING","updatedAt":"2026-04-08T14:14:55.000Z","capabilities":{"canPay":false,"canRefund":false}}}}}}}}},"responses":{"200":{"description":"Webhook received."},"default":{"description":"Any non-2xx response (or a timeout) is treated as delivery failure and triggers a retry."}}}},"enrollmentStatusUpdated":{"post":{"operationId":"enrollmentStatusUpdated","tags":["Enrollments"],"summary":"Enrollment Status Updated","description":"Sent when an enrollment's status changes. Delivered to a configured webhook endpoint (`webhooksUrl`): the merchant's, or the one given on the enrollment request. Subscription/registration of that endpoint is out of scope for this page.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrollmentWebhookEnvelope"},"examples":{"failed":{"summary":"FAILED transition with a failure reason","value":{"specversion":"1.0.2","id":"evt_abcdefghijklmno123456","source":"https://www.ppro.com","type":"ENROLLMENT_STATUS_UPDATED","subject":"enrollment_lUj4DR28ygrIgcuhhdZZa","time":"2026-10-06T14:15:00.000Z","datacontenttype":"application/json","data":{"type":"ENROLLMENT_STATUS_UPDATED","enrollmentId":"enrollment_lUj4DR28ygrIgcuhhdZZa","merchantId":"PPROULRICHTEEPTCORP855605A49436F","externalMerchantReference":"ENTITY1234567890","paymentMethod":"TWINT","currentStatus":{"status":"FAILED","updatedAt":"2026-10-06T14:14:55.000Z","statusReason":{"reasonType":"PROVIDER_DECLINE","reasonCode":"GENERIC_DECLINE","reasonMessage":"enrollment declined"}}}}},"firstStatusEvent":{"summary":"First status event for an enrollment","value":{"specversion":"1.0.2","id":"evt_bcdefghijklmnop234567","source":"https://www.ppro.com","type":"ENROLLMENT_STATUS_UPDATED","subject":"enrollment_lUj4DR28ygrIgcuhhdZZa","time":"2026-10-06T14:15:00.000Z","datacontenttype":"application/json","data":{"type":"ENROLLMENT_STATUS_UPDATED","enrollmentId":"enrollment_lUj4DR28ygrIgcuhhdZZa","merchantId":"PPROULRICHTEEPTCORP855605A49436F","externalMerchantReference":"ENTITY1234567890","paymentMethod":"TWINT","currentStatus":{"status":"ACTIVE","updatedAt":"2026-10-06T14:14:55.000Z"}}}},"suspended":{"summary":"SUSPENDED transition","value":{"specversion":"1.0.2","id":"evt_cdefghijklmnopq345678","source":"https://www.ppro.com","type":"ENROLLMENT_STATUS_UPDATED","subject":"enrollment_lUj4DR28ygrIgcuhhdZZa","time":"2026-10-06T14:15:00.000Z","datacontenttype":"application/json","data":{"type":"ENROLLMENT_STATUS_UPDATED","enrollmentId":"enrollment_lUj4DR28ygrIgcuhhdZZa","merchantId":"PPROULRICHTEEPTCORP855605A49436F","externalMerchantReference":"ENTITY1234567890","paymentMethod":"TWINT","currentStatus":{"status":"SUSPENDED","updatedAt":"2026-10-06T14:14:55.000Z"}}}}}}}},"responses":{"200":{"description":"Webhook received."},"default":{"description":"Any non-2xx response (or a timeout) is treated as delivery failure and triggers a retry."}}}}},"components":{"schemas":{"CloudEventAttributes":{"type":"object","description":"CloudEvents 1.0.2 context attributes shared by every PPRO webhook envelope; delivery mechanics (retries, signing) are handled elsewhere.","required":["specversion","id","source","subject","time","datacontenttype"],"properties":{"specversion":{"type":"string","description":"The CloudEvents specification version.","const":"1.0.2","example":"1.0.2"},"id":{"type":"string","description":"Unique event id (idempotency key for consumers).","example":"evt_abcdefghijklmno123456"},"source":{"type":"string","example":"https://www.ppro.com"},"subject":{"type":"string","description":"The resource this event is about, e.g. the merchantId or enrollmentId.","example":"MIDNITH123"},"time":{"type":"string","format":"date-time"},"datacontenttype":{"type":"string","description":"The event content type.","const":"application/json","example":"application/json"}}},"MerchantId":{"type":"string","pattern":"^([A-Z0-9]{5,32}|merchant_[a-zA-Z0-9-]{21})$","description":"Unique identifier for the merchant","example":"MERCHANTID456"},"ExternalReference":{"type":"string","pattern":"^[A-Z0-9]{1,32}$","description":"Unique reference, assigned by external client.","example":"ENTITY1234567890"},"MerchantStatus":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"],"description":"Merchant lifecycle status.","example":"ACTIVE"},"ExternalReasonCode":{"type":"string","enum":["RISK_CHECK","PROHIBITED_MCC","PROHIBITED_COUNTRY","CUSTOMER_REQUEST"],"description":"External reason code for a merchant status, coarsened from the internal reason code.","example":"RISK_CHECK"},"StatusReason":{"type":"object","required":["reasonCode"],"properties":{"reasonCode":{"allOf":[{"$ref":"#/components/schemas/ExternalReasonCode"}],"description":"Reason code for the merchant status."},"reasonMessage":{"type":"string","description":"Human-readable message. Free text - not for programmatic branching, use reasonCode instead.","example":"The merchant has been flagged for risk and is under review"}}},"MerchantStatusSnapshot":{"type":"object","required":["status","updatedAt"],"properties":{"status":{"$ref":"#/components/schemas/MerchantStatus"},"updatedAt":{"type":"string","format":"date-time"},"statusReason":{"$ref":"#/components/schemas/StatusReason","description":"Present on SUSPENDED/CLOSED transitions; may be absent for ACTIVE."}}},"MerchantStatusCapabilities":{"title":"MerchantStatusCapabilities","description":"Capability flags of a merchant.","type":"object","properties":{"canPay":{"type":"boolean","description":"Whether the merchant can process payments."},"canRefund":{"type":"boolean","description":"Whether the merchant can process refunds."}},"required":["canPay","canRefund"],"example":{"canPay":true,"canRefund":true}},"MerchantCurrentStatusSnapshot":{"description":"MerchantStatusSnapshot for the event's new status, where the producer guarantees statusReason is set on SUSPENDED/CLOSED. Not used for previousStatus - a historical snapshot may predate that guarantee.","allOf":[{"$ref":"#/components/schemas/MerchantStatusSnapshot"},{"type":"object","properties":{"capabilities":{"$ref":"#/components/schemas/MerchantStatusCapabilities"}},"required":["capabilities"]},{"if":{"properties":{"status":{"enum":["SUSPENDED","CLOSED"]}}},"then":{"properties":{"statusReason":{}},"required":["statusReason"],"unevaluatedProperties":true}}]},"MerchantStatusUpdatedData":{"type":"object","required":["type","merchantId","currentStatus"],"properties":{"type":{"type":"string","description":"Matches the envelope's `type` - required for discriminator resolution.","enum":["MERCHANT_STATUS_UPDATED"]},"merchantId":{"$ref":"#/components/schemas/MerchantId"},"externalMerchantReference":{"description":"Unique reference, assigned by external client. Omitted when the merchant has no external reference.","$ref":"#/components/schemas/ExternalReference"},"currentStatus":{"$ref":"#/components/schemas/MerchantCurrentStatusSnapshot"},"previousStatus":{"description":"Omitted on the very first status-producing event for a merchant (e.g. initial creation), where there is no prior status.","$ref":"#/components/schemas/MerchantStatusSnapshot"}}},"MerchantWebhookEnvelope":{"allOf":[{"$ref":"#/components/schemas/CloudEventAttributes"},{"type":"object","required":["type","data"],"properties":{"type":{"type":"string","description":"Discriminator selecting the shape of `data`.","enum":["MERCHANT_STATUS_UPDATED"]},"data":{"description":"The event business payload.","oneOf":[{"$ref":"#/components/schemas/MerchantStatusUpdatedData"}],"discriminator":{"propertyName":"type","mapping":{"MERCHANT_STATUS_UPDATED":"#/components/schemas/MerchantStatusUpdatedData"}}}}}]},"EnrollmentStatus":{"type":"string","enum":["PENDING","PROVIDER_PENDING","ACTIVE","FAILED","SUSPENDED","CLOSED"],"description":"Enrollment lifecycle status.\n- `PENDING`: enrollment submitted and in progress.\n- `PROVIDER_PENDING`: waiting on the payment provider.\n- `ACTIVE`: enrolled; the payment method is usable.\n- `FAILED`: enrollment failed at the provider or scheme after retries; `statusReason` is set.\n- `SUSPENDED`: the payment method is currently not usable for the merchant and can be reactivated. Also used when a merchant unenrolls from a single payment method.\n- `CLOSED`: the merchant itself is closed. Reserved and not emitted yet; enrollments of a closed merchant currently arrive as `SUSPENDED`.\n","example":"ACTIVE"},"EnrollmentStatusReason":{"type":"object","required":["reasonType","reasonCode"],"properties":{"reasonType":{"type":"string","enum":["INTERNAL_ERROR","INTERNAL_DECLINE","PROVIDER_ERROR","PROVIDER_DECLINE"],"description":"The category of failure that caused the enrollment status.","example":"PROVIDER_DECLINE"},"reasonCode":{"type":"string","description":"Reason code for the enrollment status. Free-form, supplied by PPRO or the payment provider - not for programmatic branching, use reasonType instead.","example":"GENERIC_DECLINE"},"reasonMessage":{"type":"string","description":"Human-readable message. Free text - not for programmatic branching, use reasonType instead.","example":"enrollment declined"}}},"EnrollmentStatusSnapshot":{"type":"object","required":["status","updatedAt"],"properties":{"status":{"$ref":"#/components/schemas/EnrollmentStatus"},"updatedAt":{"type":"string","format":"date-time"},"statusReason":{"$ref":"#/components/schemas/EnrollmentStatusReason","description":"Present on FAILED transitions; may be absent for other statuses."}}},"EnrollmentStatusUpdatedData":{"type":"object","required":["type","enrollmentId","merchantId","paymentMethod","currentStatus"],"properties":{"type":{"type":"string","description":"Matches the envelope's `type` - required for discriminator resolution.","enum":["ENROLLMENT_STATUS_UPDATED"]},"enrollmentId":{"type":"string","description":"Unique identifier for the enrollment.","example":"enrollment_lUj4DR28ygrIgcuhhdZZa"},"merchantId":{"$ref":"#/components/schemas/MerchantId"},"externalMerchantReference":{"description":"Unique reference, assigned by external client. Omitted when the merchant has no external reference.","$ref":"#/components/schemas/ExternalReference"},"paymentMethod":{"type":"string","description":"Payment method the enrollment was created for.","example":"TWINT"},"currentStatus":{"$ref":"#/components/schemas/EnrollmentStatusSnapshot"}}},"EnrollmentWebhookEnvelope":{"allOf":[{"$ref":"#/components/schemas/CloudEventAttributes"},{"type":"object","required":["type","data"],"properties":{"type":{"type":"string","description":"Discriminator selecting the shape of `data`.","enum":["ENROLLMENT_STATUS_UPDATED"]},"data":{"description":"The event business payload.","oneOf":[{"$ref":"#/components/schemas/EnrollmentStatusUpdatedData"}],"discriminator":{"propertyName":"type","mapping":{"ENROLLMENT_STATUS_UPDATED":"#/components/schemas/EnrollmentStatusUpdatedData"}}}}}]}}}}