Create an Account Application

Create an Account Application

To create an account, you can choose to collect all the application details up front and submit to the Account API in one session or you may choose to submit chunks of information at a time, saving your progress along the way.

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. 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}. Owner and File information updates use separate endpoints, see API Reference.
  5. POST /application/{applicationId}/submit will submit all your previously saved application data along with the agreement details to Gravity Payments for boarding.

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

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, a default pricing arrangement will be set for accounts that you board through the Account API. The account pricing determines what a merchant will pay in transaction and account fees. The default arrangement is given the pricing code “DEFAULT”, which can be specified in the request object.

If you want to set custom pricing per account, we are more than happy to work with you to get that as the preferred pricing code, please reach out to an Integration Specialist to learn more.

When used in production, pricing specified with pricing codes is subject to final review and approval by Gravity Payments.