Heartland - Integration Set up
Heartland is a direct payment processor option in Rex. Enter your Heartland API credentials to start accepting credit card payments at checkout.
Open the Payment Settings modal
On the venue details page, click the **Payment** settings card. The Payment Settings modal opens.
Turn off Sandbox mode
If the **Sandbox mode** toggle is on, switch it off. Sandbox mode uses Rex test credentials and simulates payments — no real money is charged. Turn it off to configure live payment processing.
Select Heartland as the payment processor
From the **Payments** dropdown, select **Heartland**. Four credential fields appear.
Enter your Heartland credentials
Fill in all four fields with values from your Heartland merchant account:
| Field | Description |
|---|---|
| Payment key | Your Heartland public API key (starts with `pkapi_`). |
| Payment secret | Your Heartland secret API key (starts with `skapi_`). |
| Payment URL | The Heartland Portico gateway endpoint. |
| Payment MID | Your Heartland merchant ID. |
Save changes
Click **Save changes**. All four fields are required — the modal will not save if any field is empty.
How Heartland payments work
Rex integrates with Heartland through the Global Payments (Portico) API. When a guest completes checkout, the card is charged directly through your Heartland merchant account.
How checkout payments work
The guest enters their credit card details on the Rex checkout page.
Rex tokenizes the card using your [Payment key] (public key). The raw card number never reaches Rex servers.
Rex sends the token, postal code, charge amount, and currency to the Heartland gateway using your [Payment secret] and [Payment URL].
Heartland processes the charge and returns a response code.
If the response code is `00` (approved), Rex creates a transaction record and confirms the reservation. Any other response code results in a payment error shown to the guest.
How refunds work
When you cancel or modify a reservation that was paid via Heartland:
Rex looks up the original Heartland transaction ID from the stored transaction record.
Rex sends a refund request to Heartland for the specified amount using the same gateway credentials.
Heartland processes the refund and Rex creates a refund transaction record.
Partial refunds are supported. Rex tracks the remaining balance on each transaction and only refunds up to what was originally charged on that transaction.
Sandbox vs. production
| Field | Description |
|---|---|
| Environment | Purpose |
| Sandbox | Testing. No real charges. Rex auto-fills test credentials when sandbox mode is on. |
| Production | Live payments. Funds are deposited to your linked bank account. |
Notes
Heartland charges are immediate — there is no separate capture step. The full amount is charged at checkout.
Rex uses the `globalpayments-api` SDK to communicate with Heartland.
If the `FAKE_PAYMENT` environment variable is set, Rex skips the Heartland API call entirely and creates a fake transaction. This is only used in development environments.
Transaction records include the Heartland transaction ID, auth code, and reference number for reconciliation.
Updated May 30, 2026
Was this helpful?