Create an Account Application

Create an Account Application

To create an account, you can request an application link, and our user interface will prompt the user for all the information necessary to open an account. You may also choose to collect information from the user yourself and provide those to Gravity via API calls. Any details you provide will be pre-filled for the user when they navigate to our application link. If you collect and submit all the information required, the user will simply need to confirm those details are correct, review Gravity’s terms and conditions, and indicate their acceptance.

There are a few endpoints involved, detailed further below, but the high level flow is this:

  1. Kick things off grabbing a token used with all subsequent requests (see Authenticating to the API).
  2. Start an application: POST /application/start
  3. Optional: To upload the necessary supporting documents and files, you will:
    1. Send us a file’s metadata
    2. Get an Amazon S3 pre-signed URL, which you will use to upload the file
    3. Upload the file to its corresponding S3 pre-signed URL
  4. Optional: Need to add or modify any application data? Use PATCH /application/{applicationId}. Patch calls to update application data should be completed before you generate an application URL. Once you generate an application URL the values can only be modified by the user applying for an account within our application user interface. People and File information updates use separate endpoints, see API Reference.
  5. POST /application/{applicationId}/link will return an application link the user will use to finalize their application.

The attributes that are required in the Account Application will depend on factors such as the merchant’s legal entity type and number of owners, as explained in the API Reference.

Request Headers

Content-Type: application/json
Authorization: Bearer {your authorization token goes here}

Start an Application

Start an application with only a few required fields or the entire application details, your choice.

Endpoint

POST {baseUrl}/application/start

Request Body

{
	"externalApplicationId": "73c7e8a0-9eab-45a5-baa2-29eced8d04f7",
	"pricingCode": "ABC123"
}

Response Body

{ "applicationId": "2abe961a-eb03-4f3e-a45a-3479184f1a59" }

Uploading Files (Optional)

To upload the necessary supporting documents and files, you will:

    1. Send us a file’s metadata using POST /application/{applicationId}/file, we will return expAt, fileId, presignedUrl
    2. Amazon S3 pre-signed URL can also be obtained through GET /application/{applicationId}/file/{fileId}
    3. Upload the file to its corresponding S3 pre-signed URL

      Notes:
      The S3 pre-signed URL expires after 120 seconds of sending the file metadata through POST /application/{applicationId}/file. If the S3 pre-signed URL has been expired, generate a new one by sending the file metadata again through POST /application/{applicationId}/file

Endpoints

POST {baseUrl}/application/{applicationId}/file

GET {baseUrl}/application/{applicationId}/file/{fileId}

Request Body

// POST {baseUrl}/application/{applicationId}/file

{
	"fileType": "Financials",
	"name": "2021 Profit and Loss Statement",
	"contentLength": "7056",
	"contentType": "application/pdf"
}

Response Bodies

// POST {baseUrl}/application/{applicationId}/file

{
  "expAt": 0,
  "fileId": "a1c6a2ab-4b01-4253-b4c9-70e04b3b48fc",
  "presignedUrl": "http://example.com"
}
// GET {baseUrl}/application/{applicationId}/file/{fileId}

{ "presignedUrl": "https://some-s3-url.com/my-file" }

Submit Application

Submit all your previously saved application data along with the agreement details to Gravity Payments for boarding.

Endpoint

POST {baseUrl}/application/{applicationId}/submit

Request Body

{
	"agreement": {
		"timestamp": "2023-08-16T21:54:41+00:00",
		"ipAddress": "172.28.53.223",
		"keyedInSignature": "John Doe"
	}
}

Code Example: Start Application

const url = 'https://api.account.gravitypayments.com/v2/application/start';
const authToken = 'my-auth-token';
const requestBody = {
	"externalApplicationId": "73c7e8a0-9eab-45a5-baa2-29eced8d04f7",
	"pricingCode": "DEFAULT"
};
const options = {
	method: 'POST',
	headers: {
		"Content-Type": "application/json",
		"Authorization": `Bearer ${authToken}`
	},
	body: JSON.stringify(requestBody)
};

fetch(url, options)
	.then(res => res.json())
	.then(json => console.log(JSON.stringify(json)))
	.catch(err => console.error('Error: ' + JSON.stringify(err)));
curl --request POST \
	--url https://api.account.gravitypayments.com/v2/application \
	--header 'Content-Type: application/json' \
	--header 'Authorization: Bearer {enter your auth token}' \
	--data '{refer to API Reference document}'

Pricing Codes

At the time of your enrollment, your integration specialist will provide a Pricing Code that you will pass through with each account that you board through the Account API. The Pricing Code determines what a merchant will pay in transaction and account fees. If you support multiple pricing models, we will provide you with a pricing code that corresponds to each. Other items, such as whether or not the merchant is purchasing a payment device, may also be driven by the pricing code.