Skip to main content

Webhooks

getpaid sends real-time notifications on progress on each application, this allows platforms to react to each event (or missing events), for instance:

graph TD A[Platform invites Merchant to complete info] --> F[Merchant visits the hosted onboarding page] F[Merchant visits the hosted onboarding page]-->|application_started| B[Merchant completes require data and submits application] B -->|application_submitted|C[getpaid Compliance Team completes KYC / KYB checks] C -->|application_approved| D[Merchant is enabled to process payments in getpaid] C -->|application_action_required| E[Platform gets in contact with getpaid support team]

Fig.1 - Application Lifecycle.

Common scenarios for notifications​

  1. Activate your Merchant on your platform once you receive the notification Application Approved.
  2. Get in contact with getpaid support team if you receive an Event Application Action Required.
caution

Platforms will provide the endpoints where getpaid will send the notifications. If those endpoints are unavailable, after 10 retries getpaid will pause all notifications to the endpoints.

Setting the webhook URL​

Webhook URLs are defined when initiating an application, by setting the urls.webhook field:

{
  "applicant": {
    "email": "jon.smith@acme.com",
    "first_name": "Jon",
    "last_name": "Smith"
  },
  "currencies": [
    "EUR"
  ],
  "integration": {
    "type": "hosted"
  },
  "language": "en",
  "reference": "merch-001",
  "urls": {
    "webhook": "http://example.com"
  }
}

For more details on the Initiate Application API call, see Initiate Onboarding.

Webhook Events​

We currently send webhooks for the following events:

Application Started​

The application_started event occurs when the merchant visits the hosted onboarding page for the first time.

Example Webhook​

{
  "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  "type": "application_started",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "id": "app_44678r08jtm8zbt227tzhc4nw5",
    "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
    "reference": "merch-001"
  }
}

Application Submitted​

The application_submitted event occurs when an application has been submitted by a merchant.

Example Webhook​

{
  "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  "type": "application_submitted",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "id": "app_44678r08jtm8zbt227tzhc4nw5",
    "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
    "reference": "merch-001"
  }
}

Application Succeeded​

The application_succeeded event occurs when an application has been submitted by a merchant and all the compliance checks are completed successfully.

Example Webhook​

{
  "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  "type": "application_succeeded",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "id": "app_44678r08jtm8zbt227tzhc4nw5",
    "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
    "reference": "merch-001"
  }
}

Application Action Required​

The application_action_required event occurs when an application has been submitted by a merchant and our compliance department needs more information. Our operation team will get in contact with you to complete the onboarding process.

Example Webhook​

{
  "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  "type": "application_action_required",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "id": "app_44678r08jtm8zbt227tzhc4nw5",
    "merchant_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8",
    "reference": "merch-001"
  }
}

Handling Webhooks​

All webhooks are submitted to the provided URL via a HTTP POST request. The content type of the request body is application/json.

To confirm that you have successfully handled the webhook, return any successful 2xx HTTP status code. Any other status code will be treated as a failure and the webhook will be retried.

Webhooks will be retried a maximum of 10 times.