Webhooks
Webhooks are crucial for keeping your system synchronized with the status of payments and other resources. For every business event (e.g., a payment charge authorization or a dispute), PPRO sends an HTTPS request to a specific URL you provide. This request contains a JSON payload describing the event and the associated resource.
For maximum compatibility and ease of integration with your cloud infrastructure, all PPRO webhooks follow the CloudEvents 1.0.2 specification. This provides a consistent, standardized envelope for all event data, regardless of the event type.
Endpoint requirements
Before you can receive webhooks, you must configure a dedicated endpoint on your server. This endpoint acts as a callback URL for PPRO.
HTTPS only | Your endpoint must be secured with HTTPS and configured to listen for incoming requests on an open TCP port for HTTPS traffic (typically port 443). |
Set the URL | Specify your endpoint URL using the |
Custom headers | You can optionally include custom headers (key-value pairs) in the webhook configuration if your endpoint requires them for internal routing or security. |
Signing secret | We strongly recommend configuring a unique signing secret for each endpoint. You will use this secret to validate the hash in the |
Responding to webhooks
To ensure reliable delivery and avoid unnecessary retries, your endpoint must respond quickly and correctly. Do this before executing any complex business logic:
- Acknowledge immediately: Your server must return an HTTP 2xx response code (e.g., 200 OK) as soon as possible after receiving the request. This signal confirms receipt to PPRO.
- Store first: Immediately store the webhook payload in your database. Defer the actual processing (updating inventory, sending customer emails, etc.) to a background job queue. This practice prevents timeouts and ensures you don't lose events.
Retrying webhooks
If PPRO does not receive a successful acknowledgement (an HTTP 2xx response), we automatically retry the delivery to ensure you don't miss a critical event.
We use an exponential backoff model for retries:
- First retry: Occurs after 15 seconds.
- Subsequent attempts: The interval is doubled for each subsequent attempt.
- Maximum: The system attempts a maximum of 15 deliveries.
- Total window: The total retry window for a single webhook event spans approximately 68 hours.
Verifying webhooks
To ensure that a webhook truly originates from PPRO and has not been altered in transit, we strongly recommend that you validate the signature included in the Webhook-Signature
header.
How verification works
- Compute a hash using the following formula:
sha256(payload + "." + signingSecret)
signingSecret
is a secret key generated by PPRO and shared by your technical account manager.payload
is the raw content string payload in the webhook body (not in prettified JSON format).
-
Compare your computed hash with the value from the Webhook-Signature header.
✅ If they match: the webhook is authentic.
❌ If they don’t: reject the webhook.
If the computed result matches the value in the Webhook-Signature
header, then you can confirm that the payload is the authentic payload sent by PPRO.
Example
Signing secret
Pm8qfkbXJJFjRspOzAiPoFy2N6LbMIPR
Raw payload
{"source":"https://www.ppro.com","id":"9YfP1n6pICxXGP5t6D9Ph","type":"PAYMENT_CHARGE_CAPTURE_SUCCEEDED","subject":"PAYMENT_CHARGE_CAPTURE_SUCCEEDED","time":"2024-04-12T09:02:46.732Z","data":{"paymentChargeId":"charge_Knb2EzlOhLDWKpO03wY4p","paymentChargeStatus":"CAPTURED","paymentMethod":"MOCK","type":"PAYMENT_CHARGE_CAPTURE_SUCCEEDED","captureId":"capture_F2NlOULNaPeDvP5dWbGBE","amount":{"value":1001,"currency":"EUR"}},"specversion":"1.0.2","datacontenttype":"application/json"}
Webhook-Signature
9bd16ac906c5a0da60c8849f36f27b8241c3708c972b0d28057eaa8508fbc72f
Webhook Events
PPRO sends webhooks to notify you of key events in the boarding, payment and dispute lifecycle. Each event type corresponds to a specific action or status update in our system.
Event Type | Details |
---|---|
PAYMENT_CHARGE_CREATED | A new payment charge was created and recorded in PPRO. |
PAYMENT_CHARGE_AUTHENTICATION_PENDING | The payment charge is awaiting consumer authentication before authorization can proceed. |
PAYMENT_CHARGE_DISCARDED | The consumer failed to complete authentication within the allowed time window. Refer to the payment method guides for method-specific timeout limits. |
PAYMENT_CHARGE_PROVIDER_CONFIRMATION_PENDING | The authorization request has been sent and is awaiting a definitive success or failure confirmation from the payment provider (i.e., the provider could not give an immediate response). |
PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED | The authorization was successfully completed. The payload includes a flag indicating whether the payment is multi-step and requires a separate capture. For multi-step methods, if the auto-capture flag was not set, you must explicitly send a capture request. |
PAYMENT_CHARGE_AUTHORIZATION_FAILED | The authorization attempt failed. The payload includes an error object with details about the failure. |
PAYMENT_CHARGE_CAPTURE_SUCCEEDED | The requested amount was successfully captured. |
PAYMENT_CHARGE_CAPTURE_FAILED | The capture for the requested amount failed. |
PAYMENT_CHARGE_VOID_SUCCEEDED | The payment charge was successfully voided, canceling the authorization before any capture occurred. |
PAYMENT_CHARGE_VOID_FAILED | The attempt to void the payment charge failed, leaving the authorization active. |
PAYMENT_CHARGE_REFUND_PENDING | A refund has been requested and is awaiting processing by PPRO or the provider. |
PAYMENT_CHARGE_REFUND_SUCCEEDED | The requested refund was successfully processed. |
PAYMENT_CHARGE_REFUND_FAILED | The refund attempt failed. The payload includes an error object with details about the failure. |
Example Webhooks
The source
, id
, type
, subject
, time
, specversion
, and datacontenttype
fields are common to all PPRO webhooks. Each webhook also contains the data
object, which exposes different fields depending on the webhook type.
Payment charge
{
"source": "https://www.ppro.com",
"id": "EDZY2coicSbmQReOBrFio",
"type": "PAYMENT_CHARGE_CREATED",
"subject": "PAYMENT_CHARGE_CREATED",
"time": "2025-04-28T15:14:14.878Z",
"data": {
"paymentChargeId": "charge_k8cdyX2Qf7smkpLyHzaip",
"paymentChargeStatus": "AUTHORIZATION_PROCESSING",
"paymentMethod": "IDEAL",
"type": "PAYMENT_CHARGE_CREATED",
"paymentMedium": "ECOMMERCE",
"amount": {
"value": 1000,
"currency": "EUR"
},
"merchantId": "MERCHANT_ID",
"consumer": {
"name": "Connor Summer",
"email": "[email protected]",
"country": "NL"
},
"authenticationSettings": [
{
"settings": {
"returnUrl": "https://example.com/order_details?order_id=12345"
},
"type": "REDIRECT"
}
],
"instrument": {
"id": "instr_ySHP8TvlEdnHOZu49PraU",
"type": "BANK_ACCOUNT"
}
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "nedw6sCzuJ4yGY9nTFqrO",
"type": "PAYMENT_CHARGE_AUTHENTICATION_PENDING",
"subject": "PAYMENT_CHARGE_AUTHENTICATION_PENDING",
"time": "2025-04-28T15:14:15.112Z",
"data": {
"paymentChargeId": "charge_k8cdyX2Qf7smkpLyHzaip",
"paymentChargeStatus": "AUTHENTICATION_PENDING",
"paymentMethod": "IDEAL",
"type": "PAYMENT_CHARGE_AUTHENTICATION_PENDING",
"authorizationId": "authz_AEHYgBvONReqXhilt80hh",
"amount": {
"value": 1000,
"currency": "EUR"
},
"authenticationMethods": [
{
"details": {
"requestUrl": "https://redirection-target.ppro.com",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
]
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "Bi4iNhNqQzNZQVoNI40cf",
"type": "PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED",
"subject": "PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED",
"time": "2025-04-28T15:19:08.417Z",
"data": {
"paymentChargeId": "charge_k8cdyX2Qf7smkpLyHzaip",
"paymentChargeStatus": "CAPTURED",
"paymentMethod": "IDEAL",
"type": "PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED",
"authorizationId": "authz_6jrppvkxlhD8dU4mLx8yX",
"amount": {
"value": 1000,
"currency": "EUR"
},
"isMultiStep": false
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "BZVDcF4NgSmxhBH0YAkjn",
"type": "PAYMENT_CHARGE_CAPTURE_SUCCEEDED",
"subject": "PAYMENT_CHARGE_CAPTURE_SUCCEEDED",
"time": "2025-04-28T15:19:08.417Z",
"data": {
"paymentChargeId": "charge_k8cdyX2Qf7smkpLyHzaip",
"paymentChargeStatus": "CAPTURED",
"paymentMethod": "IDEAL",
"type": "PAYMENT_CHARGE_CAPTURE_SUCCEEDED",
"captureId": "capture_KB3yd382UIZXH2V04cMH1",
"amount": {
"value": 1000,
"currency": "EUR"
}
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "9yFxTFeAEZ6kE4L0Q1SYZ",
"type": "PAYMENT_CHARGE_DISCARDED",
"subject": "PAYMENT_CHARGE_DISCARDED",
"time": "2025-04-28T15:56:47.710Z",
"data": {
"paymentChargeId": "charge_k8cdyX2Qf7smkpLyHzaip",
"paymentChargeStatus": "DISCARDED",
"paymentMethod": "IDEAL",
"type": "PAYMENT_CHARGE_DISCARDED",
"authorizationId": "authz_AEHYgBvONReqXhilt80hh",
"amount": {
"value": 1000,
"currency": "EUR"
}
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "3sReOGKGY6kPTEUH8j8mZ",
"type": "PAYMENT_CHARGE_VOID_SUCCEEDED",
"subject": "PAYMENT_CHARGE_VOID_SUCCEEDED",
"time": "2024-01-08T23:45:39.014Z",
"data": {
"paymentChargeId": "charge_75HV7qzznWIN5hIWbmhXw",
"paymentChargeStatus": "VOIDED",
"paymentMethod": "CARD",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "PAYMENT_CHARGE_VOID_SUCCEEDED",
"voidId": "void_cy0R2EcqD8J1kteCBkHse",
"amount": {
"value": 1000,
"currency": "BRL"
},
"merchantVoidReference": "optional_different_refence_for_operation"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "mPsiTTFMvMm5Di2I0a7lh",
"type": "PAYMENT_CHARGE_VOID_FAILED",
"subject": "PAYMENT_CHARGE_VOID_FAILED",
"time": "2024-01-08T23:42:29.687Z",
"data": {
"paymentChargeId": "charge_75HV7qzznWIN5hIWbmhXw",
"paymentChargeStatus": "CAPTURE_PENDING",
"paymentMethod": "CARD",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "PAYMENT_CHARGE_VOID_FAILED",
"voidId": "void_9Ak2EQncUUmRscedqBNBD",
"amount": {
"value": 1200,
"currency": "BRL"
},
"errorMessage": "Void failed",
"merchantVoidReference": "optional_different_refence_for_operation"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "PFDkXMQe1CFqcECAHc9di",
"type": "PAYMENT_CHARGE_CAPTURE_FAILED",
"subject": "PAYMENT_CHARGE_CAPTURE_FAILED",
"time": "2024-01-08T23:56:10.106Z",
"data": {
"paymentChargeId": "charge_5fZInvMbTGGNvMaaXJYsK",
"paymentChargeStatus": "CAPTURE_PENDING",
"paymentMethod": "CARD",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "PAYMENT_CHARGE_CAPTURE_FAILED",
"captureId": "capture_bHuFnULwQCSGcar1beMVt",
"amount": {
"value": 1200,
"currency": "BRL"
},
"errorMessage": "Capture failed"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "PFDkXMQe1CFqcECAHc9di",
"type": "PAYMENT_CHARGE_AUTHORIZATION_FAILED",
"subject": "PAYMENT_CHARGE_AUTHORIZATION_FAILED",
"time": "2024-01-08T23:56:10.106Z",
"data": {
"paymentChargeId": "charge_5fZInvMbTGGNvMaaXJYsK",
"paymentChargeStatus": "FAILED",
"paymentMethod": "CARD",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "PAYMENT_CHARGE_AUTHORIZATION_FAILED",
"authorizationId": "authz_p74LMQmOeV1TalZXp35k5",
"amount": {
"value": 1200,
"currency": "BRL"
},
"failure": {
"failureType": "PROVIDER_DECLINE",
"failureCode": "GENERIC_DECLINE",
"failureMessage": "Generic decline"
}
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "1eyjX7KcrPk7UFz0NuQwj",
"type": "PAYMENT_CHARGE_REFUND_SUCCEEDED",
"subject": "PAYMENT_CHARGE_REFUND_SUCCEEDED",
"time": "2024-01-08T23:18:14.847Z",
"data": {
"paymentChargeId": "charge_suhuFV3903klVteuCvDp7",
"paymentChargeStatus": "REFUNDED",
"paymentMethod": "IDEAL",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "PAYMENT_CHARGE_REFUND_SUCCEEDED",
"refundId": "refund_xAlYloaS9RSAdzSFB5fJh",
"amount": {
"value": 1000,
"currency": "EUR"
},
"merchantRefundReference": "optional_set_different_reference_for_operation"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"source": "https://www.ppro.com",
"id": "PjsXhEXURxKRfqmONciR5",
"type": "PAYMENT_CHARGE_REFUND_FAILED",
"subject": "PAYMENT_CHARGE_REFUND_FAILED",
"time": "2024-01-08T23:23:11.313Z",
"data": {
"paymentChargeId": "charge_suhuFV3903klVteuCvDp7",
"paymentChargeStatus": "REFUNDED",
"paymentMethod": "IDEAL",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "PAYMENT_CHARGE_REFUND_FAILED",
"refundId": "refund_o8lqH5aKPukMx0qTe8vWI",
"amount": {
"value": 1200,
"currency": "EUR"
},
"errorMessage": "Refund failed",
"merchantRefundReference": "optional_set_different_reference_for_operation"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
Payment agreement
{
"source": "https://www.ppro.com",
"id": "Hx5YZGaVPRgPZy9sIg7Rw",
"type": "PAYMENT_AGREEMENT_CREATED",
"subject": "PAYMENT_AGREEMENT_CREATED",
"time": "2024-01-10T10:57:09.769Z",
"data": {
"paymentAgreementId": "agr_f8MckPveVACvBfzkHLdMB",
"paymentAgreementStatus": "INITIALIZING",
"type": "PAYMENT_AGREEMENT_CREATED",
"paymentMethod": "CARD",
"description": "insurance",
"instrument": {
"id": "instr_UCQVq6QDdrMYtuwmvQsk3",
"type": "CARD_PPRO_VAULTED",
"details": {
"brand": "VISA",
"bin": "411111",
"last4Digits": "1111",
"expiryMonth": 12,
"expiryYear": 2023,
"holderName": "John Smith",
"panAlias": "numberalias_nPhbNtOb9",
"cvvAlias": "cvvalias_f6DNvZnPZ",
"isCvvPresent": true
}
},
"startDate": "2023-03-26T20:24:27Z",
"endDate": "2023-11-27T19:30:00Z",
"frequency": {
"type": "MONTHLY",
"interval": 1
},
"amount": {
"value": 10000,
"currency": "INR"
},
"amountType": "EXACT",
"merchantId": "merch_sales_eng_1",
"consumer": {
"name": "John Smith",
"email": "[email protected]",
"phone": "+4911123523524",
"country": "DE",
"taxIdentification": "TaxIdHere22323",
"merchantConsumerReference": "MC-234235423452",
"billingAddress": {
"firstName": "John",
"lastName": "Smith",
"phoneNumber": "01522113356",
"street": "Hellersbergstraße 14",
"postalCode": "41460",
"city": "Berlin",
"region": "Berlin",
"country": "DE"
}
}
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"specversion": "1.0.2",
"source": "global-payment-gateway/0.0.0",
"datacontenttype": "application/json",
"id": "060ac805cf0b0455a9a92",
"type": "PAYMENT_AGREEMENT_AUTHENTICATION_PENDING",
"subject": "PAYMENT_AGREEMENT_AUTHENTICATION_PENDING",
"time": "2022-11-03T11:23:47.123Z",
"data": {
"paymentAgreementId": "agr_FlTZQyHL4DeUYLYtXmOdq",
"paymentAgreementStatus": "AUTHENTICATION_PENDING",
"type": "PAYMENT_AGREEMENT_AUTHENTICATION_PENDING",
"authenticationMethods": [
{
"details": {
"requestUrl": "https://url.com",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
]
}
}
{
"source": "https://www.ppro.com",
"id": "0OyISq3CF24QAeTPTie8T",
"type": "PAYMENT_AGREEMENT_ACTIVE",
"subject": "PAYMENT_AGREEMENT_ACTIVE",
"time": "2024-01-10T10:57:10.403Z",
"data": {
"paymentAgreementId": "agr_f8MckPveVACvBfzkHLdMB",
"paymentAgreementStatus": "ACTIVE",
"type": "PAYMENT_AGREEMENT_ACTIVE"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
{
"specversion": "1.0.2",
"source": "global-payment-gateway/0.0.0",
"datacontenttype": "application/json",
"id": "060ac805cf0b0455a9a92",
"type": "PAYMENT_AGREEMENT_FAILED",
"subject": "PAYMENT_AGREEMENT_FAILED",
"time": "2022-11-03T11:23:47.123Z",
"data": {
"paymentAgreementId": "agr_FlTZQyHL4DeUYLYtXmOdq",
"paymentAgreementStatus": "FAILED",
"type": "PAYMENT_AGREEMENT_FAILED",
"failure": {
"failureType": "PROVIDER_ERROR",
"failureCode": "internal-failure-code",
"providerFailureCode": "provider-failure-code",
"failureMessage": "Failed to authorize agreement"
}
}
}
{
"source": "https://www.ppro.com",
"id": "0OyISq3CF24QAeTPTie8T",
"type": "PAYMENT_AGREEMENT_REVOKED_BY_CONSUMER",
"subject": "PAYMENT_AGREEMENT_REVOKED_BY_CONSUMER",
"time": "2024-01-10T10:57:10.403Z",
"data": {
"paymentAgreementId": "agr_f8MckPveVACvBfzkHLdMB",
"paymentAgreementStatus": "REVOKED",
"type": "PAYMENT_AGREEMENT_REVOKED_BY_CONSUMER"
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
Payment instrument
{
"specversion": "1.0.2",
"source": "global-payment-gateway/0.0.0",
"datacontenttype": "application/json",
"id": "e8aifYespOA2ZHXQ1zR7O",
"type": "PAYMENT_INSTRUMENT_DETAILS_UPDATED",
"subject": "PAYMENT_INSTRUMENT_DETAILS_UPDATED",
"time": "2022-11-03T11:23:47.123Z",
"data": {
"paymentInstrumentId": "instr_FlTZQyHL4DeUYLYtXmOdq",
"updateTimestamp": "2022-11-03T11:23:47.123Z",
"details": {
"type": "BANK_ACCOUNT",
"details": {
"iban": "6940493949392039",
"holderName": "John Doe"
}
},
"type": "PAYMENT_INSTRUMENT_DETAILS_UPDATED"
}
}
Fund state
{
"source": "https://www.ppro.com",
"id": "PFDkXMQe1CFqcECSH89di",
"type": "FUNDS_STATE_CHANGED",
"subject": "FUNDS_STATE_CHANGED",
"time": "2024-01-08T23:56:10.106Z",
"data": {
"paymentChargeId": "charge_5fZInvMbTGGNvMaaXJYsK",
"paymentChargeStatus": "CAPTURE_PENDING",
"paymentMethod": "CARD",
"merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
"type": "FUNDS_STATE_CHANGED",
"fundsState": "FUNDS_RECEIVED",
"fundsStateChangedTimestamp": "2024-01-08T23:56:09.106Z",
"captureId": "capture_bHuFnULwQCSGcar1beMVt",
"amount": {
"value": 1000,
"currency": "BRL"
},
},
"specversion": "1.0.2",
"datacontenttype": "application/json"
}
Report
{
"source": "gpg-payment-reports/0.0.0",
"id": "0OyISq3CF27GAeTPTie8T",
"type": "REPORT_PROCESSED",
"subject": "REPORT_PROCESSED",
"time": "2022-11-03T11:23:47.123Z",
"specversion": "1.0.2",
"datacontenttype": "application/json",
"data": {
"reportId": "report_0OyISq3CF24QAeTPTd48T",
"merchantId": "merchant-id",
"status": "PROCESSED",
"operationType": "CAPTURE",
"startDate": "2023-01-10T10:57:10.403Z",
"endDate": "2024-01-10T10:57:10.403Z",
"downloadUrl": "http://payment-reports-bucket/...",
"contentLength": "${contentLength}",
"type": "REPORT_PROCESSED"
}
}
{
"source": "gpg-payment-reports/0.0.0",
"id": "0OyISq3CF24TAeTPTie8T",
"type": "REPORT_EXPIRED",
"subject": "REPORT_EXPIRED",
"time": "2022-11-03T11:23:47.123Z",
"specversion": "1.0.2",
"datacontenttype": "application/json",
"data": {
"reportId": "report_0OyISq3CF24QAeTPTd48T",
"merchantId": "merchant-id",
"status": "EXPIRED",
"operationType": "CAPTURE",
"startDate": "2023-01-10T10:57:10.403Z",
"endDate": "2024-01-10T10:57:10.403Z",
"type": "REPORT_EXPIRED"
}
}
{
"source": "gpg-payment-reports/0.0.0",
"id": "0OyISq3H627GAeTPTie8T",
"type": "REPORT_FAILED",
"subject": "REPORT_FAILED",
"time": "2022-11-03T11:23:47.123Z",
"specversion": "1.0.2",
"datacontenttype": "application/json",
"data": {
"reportId": "report_0OyISq3CF24QAeTPTd48T",
"merchantId": "merchant-id",
"status": "FAILED",
"operationType": "CAPTURE",
"startDate": "2023-01-10T10:57:10.403Z",
"endDate": "2024-01-10T10:57:10.403Z",
"type": "REPORT_FAILED"
}
}
Updated 2 days ago