On every business event for a Payment Charge (and other objects), PPRO sends a webhook to the specified webhooksUrl. A webhook is an HTTPS call with a payload describing an event on the associated Payment Charge, Payment Instrument, Payment Agreement, Payment Session, or Payment Report.

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 default webhooksUrl configuration via the Global Portal or by contacting your technical account manager at PPRO.
This endpoint needs to accept HTTPS calls.
For both test and live environments, an open TCP port for HTTPS traffic.

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.

Webhook Types

Webhooks are sent for the following events:

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`
`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.
`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.
`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.
`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": "a6qpF1AB2HtO7WKL1egVw",
  "type": "PAYMENT_CHARGE_CREATED",
  "subject": "PAYMENT_CHARGE_CREATED",
  "time": "2024-01-08T22:45:02.348Z",
  "data": {
    "paymentChargeId": "charge_suhuFV3903klVteuCvDp7",
    "paymentChargeStatus": "AUTHORIZATION_PROCESSING",
    "paymentMethod": "IDEAL",
    "merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
    "type": "PAYMENT_CHARGE_CREATED",
    "paymentMedium": "ECOMMERCE",
    "country": "NL",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "merchantId": "merch_your_id_here",
    "consumer": {
      "name": "John Smith",
      "country": "NL"
    },
    "authenticationSettings": [
      {
        "settings": {
          "returnUrl": "https://example.com/order_details?order_id=12345"
        },
        "type": "REDIRECT"
      }
    ],
    "instrument": {
      "id": "instr_IGFRzaJUE6Qv606FxGY8O",
      "type": "BANK_ACCOUNT",
      "details": {
        "bankCode": "ABNANL2A"
      }
    }
  },
  "specversion": "1.0.2",
  "datacontenttype": "application/json"
}

{
  "source": "https://www.ppro.com",
  "id": "ieXnJbVeuKhdatczhXlhw",
  "type": "PAYMENT_CHARGE_AUTHENTICATION_PENDING",
  "subject": "PAYMENT_CHARGE_AUTHENTICATION_PENDING",
  "time": "2024-01-08T22:45:02.571Z",
  "data": {
    "paymentChargeId": "charge_suhuFV3903klVteuCvDp7",
    "paymentChargeStatus": "AUTHENTICATION_PENDING",
    "paymentMethod": "IDEAL",
    "merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
    "type": "PAYMENT_CHARGE_AUTHENTICATION_PENDING",
    "authorizationId": "authz_Eq4lgkq0bbGgroj1bTrxu",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "authenticationMethods": [
      {
        "details": {
          "requestUrl": "https://redirect-the-consumer-here.com",
          "requestMethod": "GET"
        },
        "type": "REDIRECT"
      }
    ]
  },
  "specversion": "1.0.2",
  "datacontenttype": "application/json"
}

{
  "source": "https://www.ppro.com",
  "id": "Dc5mj3WWljgS8EJI4OLti",
  "type": "PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED",
  "subject": "PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED",
  "time": "2024-01-08T22:59:55.712Z",
  "data": {
    "paymentChargeId": "charge_suhuFV3903klVteuCvDp7",
    "paymentChargeStatus": "CAPTURED",
    "paymentMethod": "IDEAL",
    "merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
    "type": "PAYMENT_CHARGE_AUTHORIZATION_SUCCEEDED",
    "authorizationId": "authz_dyk1VVCIBNhRJ697kB2UD",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "isMultiStep": false
  },
  "specversion": "1.0.2",
  "datacontenttype": "application/json"
}

{
  "source": "https://www.ppro.com",
  "id": "charge-discarded-event-id",
  "type": "PAYMENT_CHARGE_DISCARDED",
  "subject": "Payment Charge Discarded",
  "time": "2023-01-10T13:25:32.456Z",
  "data": {
    "paymentChargeId": "payment-charge-id",
    "paymentChargeStatus": "FAILED",
    "paymentMethod": "IDEAL",
    "authorizationId": "authorization-id",
    "type": "PAYMENT_CHARGE_DISCARDED",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "merchantPaymentChargeReference": "YOUR_REFERENCE_HERE"
  },
  "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": "XkrwETWvaPoftqu6piJDP",
  "type": "PAYMENT_CHARGE_CAPTURE_SUCCEEDED",
  "subject": "PAYMENT_CHARGE_CAPTURE_SUCCEEDED",
  "time": "2024-01-08T22:59:55.712Z",
  "data": {
    "paymentChargeId": "charge_suhuFV3903klVteuCvDp7",
    "paymentChargeStatus": "CAPTURED",
    "paymentMethod": "IDEAL",
    "merchantPaymentChargeReference": "YOUR_REFERENCE_HERE",
    "type": "PAYMENT_CHARGE_CAPTURE_SUCCEEDED",
    "captureId": "capture_xCtGY1B46HpeTa2568m3U",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "merchantCaptureReference": "YOUR_REFERENCE_HERE"
  },
  "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": "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"
}

{
  "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"
}

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"
    }
  }

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",
        "internalFailureCode": "internal-failure-code",
        "providerFailureCode": "provider-failure-code",
        "failureMessage": "Failed to authorize agreement"
      }
    }
  }

// coming soon

Payment 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"
    }
  }

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.

Webhook Signatures

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)

Where:

signingSecret is a secret key generated in the Global Portal or shared with you by our integrations team
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, then you can confirm that the payload is the authentic payload sent by PPRO.

You can try computing the signature match yourself using the algorithm above and the following sample values:

Sample Signing Secret

Pm8qfkbXJJFjRspOzAiPoFy2N6LbMIPR

Sample Raw Payload Content

{"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"}

Sample `Webhook-Signature`

9bd16ac906c5a0da60c8849f36f27b8241c3708c972b0d28057eaa8508fbc72f