Webhooks
For every business event, PPRO sends a webhook to the specified webhooksUrl
. Each webhook is an HTTPS request containing a payload that describes the event related to the associated resource
Endpoint requirements
Webhooks are callbacks to an HTTPS endpoint on your server. You’ll need to set up the following on your side before receiving webhooks from PPRO:
- Include the
webhooksUrl
parameter in your request (e.g. payment charge or payment agreement). Alternatively, you can set a defaultwebhooksUrl
configuration by contacting your technical account manager - This endpoint needs to accept HTTPS calls.
- For both sandbox and live environments, an open TCP port for HTTPS traffic.
- Custom headers (key-value pairs) can be included in the webhook if needed.
Responding to webhooks
Before executing any business logic in response to the webhook, ensure the following:
- Store the webhook in your DB.
- Ensure that your server will return an HTTP 2XX response code when acknowledging the webhook.
Retrying webhooks
If a webhook delivery is not acknowledged, we automatically retry the delivery according to an exponential backoff model.
The first retry attempt occurs after 15 seconds. Then, we double the interval for subsequent attempts for a maximum of 15 attempts. The total retry window for a webhook delivery spans approximately 68 hours.
Verifying webhooks
You can verify that webhooks were delivered unaltered from PPRO by verifying the hash value included in the Webhook-Signature
header.
You can compute the hash value using the following algorithm:
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).
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 Types
Webhooks are sent for the following events:
Payment charge
Type | Details |
---|---|
PAYMENT_CHARGE_CREATED | The payment charge / initial authorization attempt are created and persisted in our system. |
PAYMENT_CHARGE_AUTHENTICATION_PENDING | Authorization requires an additional authentication step from the consumer. The payload includes authenticationMethods data on where to direct the consumer for this step (see Example Webhooks) |
PAYMENT_CHARGE_DISCARDED | This event is triggered when the consumer authentication step (see above) is not completed within the timeout window for the payment method in question. You can refer to our payment method guides for specific timeout limits per payment method. |
PAYMENT_CHARGE_PROVIDER_CONFIRMATION_PENDING | Authorization is awaiting confirmation from the payment provider regarding the success or failure of the authorization to PPRO. |
PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED | Successful completion of the authorization process. The payload includes the authorization reference from the provider, as well as a boolean flag indicating whether this is a multi-step payment requiring a separate capture. In multi-step payment methods, unless the auto-capture flag was set in the initial payment request, you will need to make an explicit capture request after successfully authorizing to capture the required amount. |
PAYMENT_CHARGE_AUTHORIZATION_FAILED | Authorization has failed. The payload includes an error object with details. |
PAYMENT_CHARGE_CAPTURE_SUCCEEDED | Requested amount is successfully captured. |
PAYMENT_CHARGE_CAPTURE_FAILED | Capturing the requested amount failed (only valid for multi-step payments that require an explicit capture request). |
PAYMENT_CHARGE_VOID_SUCCEEDED | |
PAYMENT_CHARGE_VOID_FAILED | |
PAYMENT_CHARGE_REFUND_PENDING | |
PAYMENT_CHARGE_REFUND_SUCCEEDED | |
PAYMENT_CHARGE_REFUND_FAILED |
Payment agreement
Type | Details |
---|---|
PAYMENT_AGREEMENT_CREATED | The Payment Agreement entity is persisted in our system. Usually followed by either a PAYMENT_AGREEMENT_AUTHENTICATION_PENDING or a PAYMENT_AGREEMENT_ACTIVE event webhook. |
PAYMENT_AGREEMENT_AUTHENTICATION_PENDING | The consumer must still complete some additional authentication steps before the Agreement becomes ACTIVE and ready for additional merchant-initiated payment charges. |
PAYMENT_AGREEMENT_ACTIVE | Agreement is active and can be used to make subsequent payment charges. |
PAYMENT_AGREEMENT_FAILED | Agreement setup failed, usually because submitted details could not be validated by PPRO or the payment method scheme, or they were outside the allowed limits set by the scheme. |
PAYMENT_AGREEMENT_REVOKED_BY_CONSUMER | Agreement was revoked because the consumer canceled the subscription / mandate through their payment method app / bank. |
Payment instrument
Type | Details |
---|---|
PAYMENT_INSTRUMENT_DETAILS_UPDATED | The instrument details were updated, either by the merchant via an explicit PUT request, or by PPRO after we receive updated information from the issuer. |
Fund state
Type | Details |
---|---|
FUNDS_STATE_CHANGED | The funds status of a Capture or Refund has been updated. This marks the time that PPRO received the captured funds from the payment scheme or sent the refunded funds back to the consumer. |
Reports
Type | Details |
---|---|
REPORT_PROCESSED | Payment Report .csv file has been generated and is ready for download at the link provided by downloadUrl |
REPORT_EXPIRED | Payment Report .csv file download link has expired. |
REPORT_FAILED | Failed to generate the specified report. |
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 charges
{
"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 agreements
{
"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"
}
}
}
// coming soon
Payment instruments
{
"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"
}
Reports
{
"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 8 days ago