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 6 different account statuses that will trigger a webhook being sent to your endpoint: processing, declined, boarded, deployed, 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":"APP-101","status":"processing","eventTime":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 /accounts).

status

string

The account status being reported. The value will be one of: processing, declined, boarded, deployed, and active. For the significance of each status, see the relevant section below.

eventTime

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 eventTime 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}`);
});

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. Below is an example:

{"id":"APP-102","status":"processing","eventTime":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":"APP-102","status":"declined","eventTime":1521062626702,"token":"{your API key here}"}

Boarded Status

Once an account has been underwritten, it gets boarded onto Gravity’s processing platform and the boarded webhook is fired. Example below:

{"id":"APP-102","status":"boarded","eventTime":1521062626702,"token":"{your API key here}","mid":"517924510026974"}

This status update carries the special mid attribute.

mid

string

The Merchant Identification Number for this account.

The Merchant Identification Number, or MID, is essentially the merchant’s account number for their processing account with Gravity. It is the number that appears on all processing statements, and that the merchant can use to identify their account to Customer Support. The MID is what you’ll want to present to the merchant as their account number, while the id is kept for internal reference of the submitted account.

Deployed Status

With the account boarded for processing, any products ordered can now be deployed. For physical products, such as terminals and card readers, this means they’ve been programmed and shipped.

Here’s an example of the webhook:

{"id":"APP-102","status":"deployed","eventTime":1521062626702,"token":"{your API key here}"}

When an account reaches “deployed” status, it is ready for processing. Therefore, once a device is received or gateway access obtained, it can be used immediately to process transactions.

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":"APP-102","status":"active","eventTime":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.