Connecting Business Software to Gravity Payments

By Cameron Price, payment-integration documentation editor with nine years reviewing merchant-software workflows (editorial persona)
Last reviewed: July 12, 2026

Gravity Payments offers several integration products rather than one universal plugin. emergepay processes payments through web, mobile and device interfaces; Easy Integrator connects desktop point-of-sale software with a gateway or terminal; Account API automates merchant applications and onboarding status updates.

This independent guide is not operated by Gravity Payments and cannot issue production credentials, inspect API traffic or change an integration.

Choose the product before writing code

The three main products solve different problems.

Gravity product	Primary purpose	Typical user
emergepay	Processes online, tokenized, mobile and device-based payments	Software developers and ecommerce platforms
Easy Integrator	Lets desktop POS software communicate with external payment hardware or a gateway	Windows or locally installed business software
Account API	Starts merchant applications and returns underwriting or onboarding statuses	Software platforms enrolling their own merchants

Gravity describes emergepay as a multi-interface, operating-system-independent payment integration with a web API. Easy Integrator is a desktop application that passes transaction information from the point of sale to an external gateway or hardware device. Account API is a REST interface for merchant boarding, not a substitute for the transaction-processing API.

Start with the business workflow. Skip choosing an API merely because its name sounds broader.

Account API is not the checkout API

Account API creates and tracks merchant applications. It does not replace emergepay for customer purchases.

Confusing the two can produce an integration that successfully enrolls businesses but has no method for taking payments.

Pick the emergepay checkout experience

Gravity currently documents several emergepay interfaces. Each determines how much of the checkout screen the software controls and where payment information is collected.

Modal

The Simple Form opens a responsive payment interface with a fixed design and placement. Gravity presents it as the faster implementation for software that does not need complete control over every payment field.

Embedded URL page

The embedded form places a prebuilt payment page inside an iframe. It can provide a quicker implementation than constructing the checkout field by field.

Hosted Fields

Gravity’s Custom Form places hosted payment fields inside the developer’s design. The software controls the surrounding layout, while Gravity-hosted iframe elements collect sensitive payment information.

Checkout

Gravity describes Checkout as an ecommerce option for developers who want control over the transaction flow while using Gravity-hosted input fields. The developer must provide Gravity with the valid parent domain before production use.

Digital wallets and remote payments

emergepay supports Apple Pay and Google Pay after the required wallet-registration steps. Gravity also documents Text to Pay, native iOS and Android SDKs, physical payment devices, tokenized payments and direct ACH methods.

Do not promise every method by default. Wallets, devices and alternative payment types may require separate configuration.

What tokenization changes

Gravity’s CIP token method is designed so sensitive card information is sent from the customer’s browser to Gravity rather than being posted to the software provider’s server. Gravity returns a token to the browser; the application then sends that token to its server, which submits the tokenized transaction to Gravity.

The simplified flow is:

1. The customer enters payment information.
2. The browser sends the sensitive fields to Gravity.
3. Gravity creates and returns a token.
4. The browser sends the token and ordinary order data to the merchant application.
5. The application submits the tokenized transaction.
6. Gravity returns an approval or decline.

Gravity says its properly implemented hosted-interface libraries can keep the software vendor’s environment outside the payment-data scope addressed by those fields. Its developer FAQ also states that merchants still need to attest to PCI compliance. A hosted form therefore reduces direct handling of payment data; it does not eliminate every security or compliance responsibility surrounding the website, employee access and integration.

Use the hosted fields as documented. Skip copying sensitive values through application logs, analytics events or error-reporting tools.

Keep sandbox and production credentials separate

emergepay uses an OID, or organization ID, together with an authorization token. Gravity says merchant credentials are specific to the merchant account, and many businesses use one account per location. Some merchants separate device activity from ecommerce activity by using distinct accounts.

Gravity also provides partner-level authorization tokens. A partner token can authorize requests for associated merchants when each request contains the correct merchant OID. Merchant-specific tokens authorize only their assigned account.

Sandbox and production use different endpoints and credentials. A sandbox approval does not create a live transaction, while production credentials should never be embedded in browser code or committed to a public source repository. Gravity directs developers seeking private test credentials and real-time test reporting to their Integration Specialist.

Common configuration failures include:

• A sandbox token sent to production
• A production token sent to the sandbox
• The correct partner token paired with the wrong merchant OID
• Credentials belonging to a different location
• A secret token exposed in client-side code
• An old credential retained after account reconfiguration

Check environment, OID and token assignment before changing transaction logic.

Stop duplicate payments with idempotency keys

Network timeouts create a dangerous question: did the original payment fail, or did only the response fail?

Gravity added public idempotency-key documentation in May 2026. An idempotency key lets an integrator send the same request more than once while emergepay processes it only once and returns the same result. Gravity supports these keys across its public emergepay APIs.

Gravity says the idempotency session remains active for 24 hours. Requests must use the same endpoint, the same key and an identical payload. If a reused key contains different data, emergepay returns a 409 conflict. A 409 response can also indicate that the original transaction is still in progress and no final result has been recorded.

Generate a new version 4 UUID for each intended transaction, as Gravity recommends. Preserve it with the order record.

Priority one is preventing a duplicate charge. Skip automatic retries that create a new transaction identifier every time the network pauses.

Save both transaction identifiers

Gravity’s developer FAQ distinguishes two identifiers.

The externalTransactionID is generated by the integrating software and sent with the transaction. Gravity recommends saving it as the software’s historical reference. The uniqueTransactionID is returned by Gravity and is used for later tokenized actions such as voiding the processed transaction.

Store both beside:

• Internal order number
• Merchant location
• Transaction type
• Amount
• Approval or decline result
• Creation time
• Idempotency key
• Refund or void status

Searching by an internal order number alone is unreliable when one order contains several payment attempts. The Gravity-returned identifier shows which attempt actually reached the processor.

Webhooks require verification and ordering logic

Account API sends HTTPS POST webhooks as a merchant application moves through boarding. Gravity currently documents statuses including initiated, requested, inProgress, processing, processingPending, withdrawn, declined, boarded, installed and active.

Gravity includes the account identifier, status, event timestamp and API token in the webhook body. Its documentation recommends comparing the supplied token with the expected value and discarding traffic when it is missing or incorrect.

The receiving endpoint must return HTTP 200 with only the word gravity in the response body. When that response is not received, Gravity says it retries after one minute and then twice more at two-minute intervals, creating a total retry window of about five minutes. Webhooks may arrive out of order, so the integration should compare the event’s created timestamp rather than assuming the most recently received request represents the latest status.

Do not mark an account active merely because the last webhook delivered to the server says processing. Delivery order and business-event order are not always the same.

Gravity’s review and beta process

Gravity publishes a five-stage integration process:

1. Solution: choose the payment approach with Gravity.
2. Integrate: build independently or work with an Integration Specialist.
3. Review: Gravity reviews the integration and supplies testing actions.
4. Beta: the first three merchants are installed for controlled testing.
5. Launch: the integration becomes available to the wider merchant base.

Gravity does not publish one guaranteed development timeline because integrations differ in hardware, checkout design, onboarding and testing requirements. Its current process explicitly places review and a three-merchant beta before general release.

Plan for error handling, refunds, voids, partial approvals, device failures and interrupted network responses before beta. A successful one-cent sandbox sale is not a complete production test.

Dashboard, gateway and software reports

Gravity’s Custom Checkout Form can hide Gravity branding from the customer-facing payment experience. Gravity’s reporting Dashboard remains Gravity-branded and cannot be white-labeled, according to the developer FAQ.

The official Merchant Logins page also retains a Legacy gateway console for legacy integrated solutions. Gravity says that console supports transactions, batches, a virtual terminal and fraud-protection modules. It should not be treated as the standard login for every current emergepay merchant.

A software platform may therefore display an order as paid while Gravity Dashboard or the legacy gateway displays the underlying processor transaction. Reconciliation should preserve a shared reference between those two records.

FAQ

Does Gravity Payments have an API?

Yes. Gravity documents emergepay for payment processing and Account API for merchant onboarding.

Is emergepay the same as Account API?

No. emergepay processes transactions. Account API starts merchant applications and reports their onboarding statuses.

Can a Gravity checkout be white-labeled?

Gravity says the Custom Checkout Form can hide Gravity branding from customers. The Gravity reporting Dashboard remains branded.

Does Gravity provide a sandbox?

Yes. Gravity publishes separate sandbox and production environments. Private test credentials and Dashboard access are available through an assigned Integration Specialist.

How do I prevent duplicate API charges?

Send a unique idempotency key with each intended transaction and reuse that same key with an identical payload when retrying the original request. Gravity keeps the idempotency session for 24 hours.

Why does the API return HTTP 409?

Gravity documents 409 responses when the same idempotency key is reused with a conflicting payload or when the original transaction using that key is still in progress.

Can Gravity integrate with physical terminals?

Yes. emergepay documents supported payment devices, while Easy Integrator connects desktop point-of-sale software with external gateways or hardware. Device availability and supported transaction types vary by model.

The dependable implementation order is product selection, sandbox configuration, tokenized checkout, identifier storage, duplicate protection, Gravity review and limited beta testing before a general merchant launch.