Create an account
To create an account, you will POST a JSON Account Object to the /accounts
endpoint. In the header of your request, you must supply a valid authentication token (that you retrieved from the /auth
endpoint – see Authenticating to the API). The attributes that are required in the Account Object will depend on factors such as the merchant’s legal entity type and number of owners, as explained in The Account Object below.
Endpoint
https://api.gravitypayments.com/{version}/accounts
Request Headers
Content-Type: application/json
Authorization: Bearer {your authorization token goes here}
Request Body
{"apiKey":"{your API Key goes here}","business":{"dba":"Root Beer Cheers","type":"Restaurant","goodsAndServices":"We sell root beer and provide Root Beer Consulting. We also have a Root-Beer-of-the-Month Club. Charges are made when orders ship or when services are rendered. RBOM Club members are charged a monthly or yearly membership fee.","address":{"line1":"1410 Sarsaparilla Lane","line2":"Suite 100","city":"Seattle","state":"WA","postalCode":"98107"},"phone":"866-701-4700","email":"howdy@rootbeercheers.co","websiteUrl":"http:\/\/rootbeercheers.co"},"legalEntity":{"type":"Tax-Exempt Organization","name":"Root Beer Cheers","tin":123456789,"address":{"line1":"1 Salty Lane","line2":"Suite 9","city":"Seattle","state":"WA","postalCode":"98107"},"yearsInBusiness":10,"foreign":false},"owners":[{"salutation":"Mr.","firstName":"Oliver","middleName":"X.","lastName":"Heneghan","title":"Owner","percentOwnership":100,"ssn":"123456789","dob":"1984-09-22","address":{"line1":"22 Horseshoe Road","line2":"Box 808","city":"Seattle","state":"WA","postalCode":"98107"},"phone":"206-388-5900","email":"ollie@rootbeercheers.co"}],"banking":{"depositAccount":"48276574","depositRouting":"125008547"},"contact":{"salutation":"Mx.","firstName":"Logan","middleName":"J.","lastName":"Berry","title":"Secretary","address":{"line1":"4 Paws Court","line2":"1st Floor","city":"Seattle","state":"WA","postalCode":"98107"},"phone":"206-388-5900","email":"logan@rootbeercheers.co","authorizedSigner":true},"processingProfile":{"averageMonthlyCardVolume":50000,"averageTicket":100,"averageMonthlySalesVolume":80000,"currentlyAcceptingCards":true,"seasonal":true,"seasonalFrom":3,"seasonalTo":9,"acceptanceMethods":{"swiped":30,"keyed":10,"moto":0,"internet":60}},"pricingCode":"DEFAULT"}
This is an example of a request body containing an Account Object with sample data. All the attributes of the Account Object are validated for type and content according to the entity being submitted. Individual attributes and their constraints are detailed below in The Account Object.
Response Body
{"success":true,"message":"account created","appId":"APP-101"}
Responses will come in the form of a JSON object with success
and message
attributes. If success
is false
—that is, the request to create an account was unsuccessful—the message
attribute will contain the relevant error message indicating what caused the failure.
Success responses will additionally contain an appId
attribute. This number will then be used in webhook notifications to reference the submitted account, and therefore should be stored in your database.
The Account Object
apiKey
string required
Your API Key. This identifies that the new merchant is to be assigned under you.
business
hash required
A hash of attributes pertaining to the merchant’s business location. Child attributes are:
dba
string required
“Doing business as”, the merchant’s business name, trade name, or operating name.
type
string required
The primary type of the business conducted by the merchant, as an industry designation. For a list of values pertaining to your clientele, please contact your Gravity Payments representative.
goodsAndServices
string max. 255 characters required
A brief description of the goods and services sold by the business. If relevant, include how payments are collected, for instance recurring charges or invoice terms. For nonprofits receiving donations, indicate any goods/services sold as fundraisers, as well as any specific deliverables expected from funding.
hash required
A hash of the address of the business location (where customers make transactions). Child attributes are:
line1
string max. 24 characters required
The first line of the street address.
line2
string max. 24 characters
The second line of the street address, if any.
city
string max. 18 characters required
The city where the business is located.
state
string required
The state where the business is located.
postalCode
string required
The zip or postal code of the business.
phone
string required
The customer service phone number of the business. May be formatted with or without punctuation (dashes, parentheses, etc.).
string required
The customer service email address of the business.
websiteUrl
string
The primary web address of the business, if any.
legalEntity
hash required
A hash of the merchant’s legal entity information. Child attributes are:
type
string required
The legal entity type. Valid values are:
- Sole Proprietorship
- Public Corp
- Private Corp
- Publicly Traded Partnership
- Private Partnership
- Publicly Traded LLC
- Private LLC
- Association/Estate/Trust
- Tax-Exempt Organization
- International/Organization
- Government
name
string conditionally required
The legal name of the business entity. Required for all entity types except Sole Proprietorship.
tin
integer 9 digits conditionally required
The Tax Identification Number (TIN/EIN) of the business). Required for all entity types except Sole Proprietorship.
address
hash conditionally required
A hash of the legal address of the business entity. Required for all entity types except Sole Proprietorship. For child attributes, see Business Address.
yearsInBusiness
integer required
The number of years that the merchant has been in business formed as this legal entity.
foreign
boolean required
Is the legal entity of United States origin, or is it foreign?
true
if foreign, otherwisefalse
. For Sole Proprietorships, if the owner is not a legal citizen of the United States, thentrue
, otherwisefalse
.
owners
list required
An array of owners of the business. For all entity types, at least one owner must be listed. For Private Corp, Private LLC, and Private Partnership, the total of all listed owners’ ownership percentage must be at least 50%. The first owner listed will be Signer 1. If a second owner is listed, they will be Signer 2. Any additional owners that are listed will not sign.
Attributes of each owner object are:
salutation
string
The owner’s salutation. Typical values are Mr., Mrs., Ms., Mx., Dr., and Prof.
firstName
string required
The owner’s first name.
middleName
string
The owner’s middle name.
lastName
string required
The owner’s last name.
title
string
The owner’s title. Valid values are: President, Vice President, Treasurer, Owner, Partner, CEO, Secretary, Director.
percentOwnership
integer conditionally required
The ownership percentage of the owner, rounded to the nearest whole number. Required for all owners of a Private Corp, Private LLC, or Private Partnership.
ssn
string 9 numeric characters required
The owner’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN).
dob
string required
The owner’s date of birth, formatted as YYYY-MM-DD.
address
hash required
A hash containing the owner’s address details. For child attributes, see Business Address.
phone
string required
The owner’s phone number. May be formatted with or without punctuation (dashes, parentheses, etc.).
string required
The owner’s email address.
banking
hash required
A hash of the business bank account information. The bank account specified here will be the account on record for depositing all funds and retrieving all fees. Child attributes are:
depositAccount
string required
The account number of the business’s bank account.
depositRouting
string required
The routing number of the business’s bank account.
contact
hash
A hash of the designated account contact, if any. This entire hash is optional. If you are not supplying a contact in any given account, the
contact
key can simply be omitted from the request (rather than populating it with an empty hash as the value).Child attributes are:
salutation
string
The contact’s salutation. Typical values are Mr., Mrs., Ms., Mx., Dr., and Prof.
firstName
string conditionally required
The contact’s first name. Only required if supplying a contact.
middleName
string
The contact’s middle name.
lastName
string conditionally required
The contact’s last name. Only required if supplying a contact.
title
string
The contact’s title.
address
hash
A hash containing the contact’s address details. For child attributes, see Business Address.
phone
string conditionally required
The contact’s phone number. May be formatted with or without punctuation (dashes, parentheses, etc.). If supplying a contact, the contact must have a phone number or an email address, or both.
string conditionally required
The contact’s email address. If supplying a contact, the contact must have an email address or a phone number, or both.
authorizedSigner
boolean
Is the contact authorized to sign for account changes on behalf of the business?
true
if yes,false
if no. Defaults tofalse
.
processingProfile
hash required
A hash containing details of the merchant’s processing patterns. Child attributes are:
averageMonthlyCardVolume
integer required
The average monthly total dollar amount of sales that the merchant is paid by card, as a whole number.
averageTicket
integer required
The average dollar amount of a sale at the merchant’s business, as a whole number.
averageMonthlySalesVolume
integer
The average monthly total dollar amount of all sales by any payment method, as a whole number.
currentlyAcceptingCards
boolean required
Is the business currently accepting credit/debit cards for payment?
true
if yes,false
if no or new business.
seasonal
boolean
Is this a seasonal business, where sales are significantly higher during certain seasons than others?
true
if yes,false
if no. Defaults tofalse
.
seasonalFrom
integer conditionally required
The month when the merchant’s high sales season begins, as a number (1-12). Only required if
seasonal
istrue
.
seasonalTo
integer conditionally required
The month when the merchant’s high sales season ends, as a number (1-12). Only required if
seasonal
istrue
.
acceptanceMethods
hash required
A hash of the card acceptance method percentages for the business. Percentage figures from the child attributes must add up to 100. If business is new, figures should represent estimates of expected activity. Child attributes are:
swiped
integer
The percentage of card sales that are accepted in person, where the card is physically swiped, tapped, or dipped with a reader. Round to the nearest whole number.
keyed
integer
The percentage of card sales that are manually key-entered, where the card numbers are typed into a computer or machine to charge a sale. Round to the nearest whole number.
moto
integer
The percentage of card sales that are accepted by mail or telephone order (MOTO), where the card is not present at the time of sale. Round to the nearest whole number.
internet
integer
The percentage of card sales that are accepted by online order from the cardholder. Round to the nearest whole number.
pricingCode
string
The code for the pricing to be assigned to this account. Defaults to “DEFAULT”. For more information, see Pricing Codes.
products
list
A list of product objects to order for deployment with this new account. For more information, see Products.
Attributes of each product object are:
code
string conditionally required
The product code.
qty
integer conditionally required
The quantity of the product to be ordered.
purchase
boolean
Is this product for purchase or rental by the merchant?
true
if purchase,false
if rental or N/A. Defaults tofalse
.
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 Account 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.
Products
In setting up your access to the Account API, your Gravity Payments representative will provide you with product codes for any products that you may need to order with new merchant accounts, as can be specified in the Account Object. This will typically include one or more payment gateway options, and any card readers, terminals, or other hardware that your merchants will use to process payments. When a product is ordered through the API, the merchant’s bank account is charged for the purchase or rental cost of the product as applicable.
Should you need product codes for any additional products, your Gravity Payments representative can supply them.