Webhooks

Account creation webhooks

As an account moves through the underwriting and boarding process, our servers will perform an HTTPS POST to your endpoint with data concerning the status of the account. These notifications allow you to take action or make any appropriate updates within your app.

Receiving Webhooks

As part of account setup, you will be asked to provide an HTTPS endpoint where we can direct webhooks. In order to receive these webhooks, your endpoint will need to be publicly accessible. All webhooks will contain a token (your API key) in the JSON body that you can use to verify the authenticity of the request.

There are ten different account statuses that will trigger a webhook being sent to your endpoint: initiated, requested, inProgress, processing, processingPending, withdrawn,  declined, boarded, installed, and active. The request body of each webhook will contain a JSON object with some common attributes and, depending on the status, some special attributes pertaining to that status. Details on the meaning of each attribute and status are outlined below.

Request Body

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"processing","created":1520404796828,"token":"{your API key here}"}

This is an example of a request body for a “processing” status, which has no special attributes. The attributes it contains, which comprise the attributes common to all statuses, are

id

string

The identification number of the account to which this webhook notification pertains. This corresponds to the applicationId in the success response body of an account creation request (POST to /application/start).

status

string

The account status being reported. The value will be one of: initiated, requested, inProgress, processing, processingPending, withdrawn, declined, boarded, installed, and active. For the significance of each status, see the relevant section below.

created

integer

A timestamp of the actual time when the status event occurred, represented as milliseconds since January 1, 1970 00:00:00 GMT.

token

string

Your API key, which acts as a unique identifier for your API account that you can use to verify the authenticity of the request.

Webhook Token Verification

When you are given your API access credentials, you will also receive an API key, which is the same value that will be sent in the token attribute of every webhook request body. To protect against spoofing, we recommend that you always check for a matching token value on any incoming traffic to your endpoint. If the token value is missing or doesn’t match, the request did not originate from Gravity Payments and should be discarded.

Expected Response

To indicate that a webhook has been received, you will need to respond with an HTTP status code of 200. In the body of the response should be only the word “gravity” (without quotes). Responding with this keyword will signal that the webhook has not only been received, but successfully recorded/processed.

Example:

HTTP/1.1 200 OK
...

gravity

Delivery Schedule

When a status update occurs, a webhook will be sent in near real time. If the webhook request does not get the expected response—for instance if your endpoint has an outage—our server will attempt to re-deliver the webhook over a period of a couple days until the response is received. In such a case, you may receive webhook notifications out of order, and will need to reference the created attribute to determine when each status update occurred.

Code Example

import express from 'express';

const app = express().use([
  express.json(),
  express.urlencoded({ extended: true })
]);
const port = 3000;

app.post('/account/webhook/listener', (req, res) => {
  console.log(`Received Account API webhook with submission status: ${req.body.status}`);
  res.sendStatus(200);
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Initiated Status

The initiated status indicates you have started an application via the Account API. As a developer you can pre-fill information on behalf of the merchant during this phase of the process. If you have your own signup form the merchant is filling in, you can progressively pass those details to our Account API, eliminating the need for the merchant to provide the same details a second time. This phase ends when you request an application link.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"initiated","created":1521062626702,"token":"{your API key here}"}

Requested Status

The requested status indicates an application link has been created, but the merchant hasn’t accessed the link yet. Once an application reaches this stage, you can no longer add information to the application via the Account API. The merchant will complete the application via the link.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"requested","created":1521062626702,"token":"{your API key here}"}

In Progress Status

The inProgress status indicates the merchant has accessed the application but hasn’t completed it yet.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"inProgress","created":1521062626702,"token":"{your API key here}"}

Processing Status

The processing status indicates that an account has been accepted and is currently being underwritten. The webhook notification for this status contains no special attributes.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"processing","created":1521062626702,"token":"{your API key here}"}

Processing - Pending Status

The processingPending status indicates that an account cannot be approved for processing without additional information. Gravity will reach out to request the additional information necessary to proceed.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"processingPending","created":1521062626702,"token":"{your API key here}"}

Withdrawn Status

The withdrawn status indicates Gravity was unable to complete underwriting. The merchant may have requested their application to be withdrawn and/or failed to provide additional or corrected information necessary for underwriting.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"withdrawn","created":1521062626702,"token":"{your API key here}"}

Declined Status

If, for some reason, the submitted account is unable to be underwritten, then it will move to a “declined” status. This would happen if, for instance, the merchant presents an unreasonable processing risk, such as dealings in a restricted industry or a history of excessive chargebacks. Upon declining underwriting of the account, a declined webhook will fire. This webhook contains no special attributes.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"declined","created":1521062626702,"token":"{your API key here}"}

Boarded Status

The boarded status indicates the merchant account has been approved and is ready to be installed. We will return all the information necessary for the merchant to begin processing with this status. If the merchant is purchasing hardware, our Deployment team will start preparing it for delivery to the merchant’s address.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"boarded","created":1521062626702,"token":"{your API key here}","oid":"12345678"}

This status update carries the special oid attribute.

oid

string

The Organization ID for this account.

Installed Status

If Gravity is facilitating an installation for the merchant, this status will be updated when that installation is completed. Accounts may skip this step if you use the credentials returned in the Boarded status to enable the merchant for processing.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"installed","created":1521062626702,"token":"{your API key here}"}

Active Status

This status signifies that an account has begun processing transactions. The first time that a batch settles containing one or more transactions in the amount of $5 or more, this status is triggered. The webhook that gets sent has no special attributes.

Example:

{"id":"53586d7c-9cd7-46c3-8944-7b259a30a833","status":"active","created":1521062626702,"token":"{your API key here}"}

Monitoring for Activity

Oftentimes integration partners want to know that the merchants they’re setting up are beginning to use their accounts. Otherwise, it may indicate that the merchant has hit a roadblock or doesn’t understand how to use the product. The active webhook provides the update you need in order to monitor your accounts in the critical starting stage.