Webhooks

Account creation webhooks

As an account moves through the creation process and specific account events fire, our servers will perform an HTTPS POST to your endpoint with data concerning the status of the account. These notifications allow you to then 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 in the JSON body that you can use to verify the authenticity of the request.

There are 7 different account statuses that will trigger a webhook being sent to your endpoint: retrysigningsubmitteddeclinedboardeddeployed, 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":"submitted","eventTime":1520404796828,"token":"{your token code goes here}"}

This is an example of a request body for a “submitted” 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 appId 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: retrysigningsubmitteddeclinedboardeddeployed, or 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

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 a webhook token, 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.

Retry Status

When an account is first submitted to the /accounts endpoint, it goes through initial validation to check that the Account Object conforms to the expected format and meets requirements for its entity type. After the server gives a success response with an appId, the account then moves on to go through secondary validation and record creation. Secondary validation includes matching the pricing code to an available pricing arrangement and matching product codes to existing products, among other checks. This validation is completed within a few minutes of receiving the account.

If the account fails during the second round of validation, or there is an error during record creation, then the account gets put into a “retry” status and the retry webhook gets fired. Below is a sample:

{"id":"APP-102","status":"retry","eventTime":1520404796828,"token":"{your token code goes here}","msg":"Pricing Code not found."}

With this status comes the special msg attribute.

msg

string

A message explaining the validation failure or error that occurred with this account.

Once an account is in “retry” status, it will not be processed further. If due to a validation failure, you will need to correct the data and submit the account again. If due to an error on our end, we will be in touch with you by email to let you know when it’s safe to resubmit the account. If you ever need clarification on a message you receive, please don’t hesitate to contact us at developer@gravitypayments.com.

Signing Status

If a submitted account passes all validation, a DocuSign envelope is generated using the account data. This enables the merchant to electronically sign a Merchant Services Account Agreement (for details on the e-signing process and document, see E-Signing). Within a few minutes of the initial call to /accounts, a signing webhook gets fired containing the special attributes signingUrl and signer, like the sample below.

{"id":"APP-102","status":"signing","eventTime":1520404796828,"token":"{your token code goes here}","signingUrl":"https:\/\/demo.docusign.net\/Signing\/StartInSession.aspx?t=654b4d4f-3fe7-4011-9f58-0a8d8f7d5e9f","signer":1}

signingUrl

string

The URL that the signer must visit to electronically sign the Merchant Services Account Agreement.

signer

integer

The signer number to which the Signing URL pertains. This number corresponds to the order in which the owner was specified in the Account Object—the first owner in the owners array becomes signer 1 and the second owner becomes signer 2.

The sample request body above contains the signingUrl for the first owner, as indicated by signer being set to 1. You will direct the user for the first owner to this URL for signing, and on completion, they will be redirected to your API Return URL.

If there is a second owner of the business, you will receive a second signing webhook with another signingUrl and signer set to 2. You will repeat the signing process for this signer, directing their user to the Signing URL and having them return to your API Return URL upon signing.

Any owners beyond the first two specified will not sign.

API Return URL

During onboarding to API access, you will be asked to provide an API Return URL. This is the address that users will be returned to after e-signing the Merchant Services Account Agreement. As such, it should be a page within your app that provides a message or other contextual cues to orient the user to the action that has just been completed.

When DocuSign returns the user, it will append a query parameter to the Return URL indicating what took place, such as ?event=signing_complete. Make sure that your app parses this parameter so that it can display the appropriate message, for instance when the user cancels signing rather than completing it. For complete details, see the DocuSign docs on Determining Recipient Action.

Submitted Status

The submitted status indicates that an account has been submitted to Underwriting. This occurs immediately after all signers have completed the Merchant Services Account Agreement. The webhook notification for this status contains no special attributes. Below is an example:

{"id":"APP-102","status":"submitted","eventTime":1521062626702,"token":"{your token code goes 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 token code goes 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 token code goes 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. For virtual products, such as gateways, this means they’ve been set up and access is ready.

Here’s an example of the webhook:

{"id":"APP-102","status":"deployed","eventTime":1521062626702,"token":"{your token code goes here}","gateway":{"provider":"Gravity Link","key":"_V87Qtb513Cd3vabM7RC0TbtJWeSo8p7","secret":"123456"}}

For supported gateways, this webhook comes with the special gateway attribute containing credentials.

gateway

hash

A hash of the gateway credentials. Child attributes are:

provider

string

The gateway provider, or brand, such as Gravity Link, BridgePay, NMI, Payeezy, etc.

key

string

The gateway credential key for API access, sometimes known as the username or login ID. For Gravity Link, this is the Source Key.

secret

string

The gateway credential secret for API access, sometimes known as the password or PIN. For Gravity Link, this is the PIN.

Supported Gateways

Currently, supported gateways are Gravity Link, NMI, BridgePay, Payeezy, and Credit Call (additional gateways may be able to be supported upon request). When these gateways are ordered, credentials will be included in the webhook. If, instead, an unsupported gateway is ordered, or no gateway is ordered, the webhook will not contain a gateway attribute.

Authorize.Net and certain other gateways are not able to be supported, as these gateways provide credentials by an email or login process directly to the merchant. If your app requires gateway credentials for an integration, you will need to obtain them from the merchant for these gateways.

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 token code goes 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.

Testing Webhook Notifications

While in production, notifications of each status will naturally fire as accounts move through the boarding process, developers may need a way to artificially trigger each status notification in order to test an integration in sandbox. The following test endpoint is provided for that purpose in sandbox only.

Making a request to the Test Notification endpoint will cause a test webhook notification of the designated status to fire in a separate transaction to the postback URL that is associated with your developer account. Meanwhile, a successful response to your request will indicate that the notification has been triggered.

Test notifications triggered in this way will fire only once per request, regardless of whether they receive a successful response. Real notifications triggered by actual account activity, on the other hand, will attempt to redeliver if they get an unsuccessful response, as described in Expected Response.

Endpoint

HTTP MethodURI
GEThttps://api.gravitypayments.com/sandbox/tests/notifications/{status}

Path Parameters

status

The status of notification that you wish to have sent.

Valid values are:

  • retry
  • signing
  • submitted
  • declined
  • boarded
  • deployed
  • active

Query String Parameters

appId

optional

The Application ID of the account for which to send the test notification. This value becomes the id in the test notification body. If provided, we will attempt to associate the provided ID to an account and use that account’s attributes when applicable. If not provided, or if unable to associate, the placeholder of APP-000 will be sent instead.

Request Headers

X-Api-Key: {your API Key goes here}
Authorization: Bearer {your authorization token goes here}

Response Body

{"success":true,"message":"Notification has been sent.","appId":"APP-000","postbackUrl":"https:\/\/your-postback-url.io"}