Configure Paymentus Integration

Overview

Integrating Paymentus within gaiia allows your customers to pay their invoices by credit card or by bank account through your Paymentus account. Payment methods, one-time payments, automatic payments, and refunds are all managed from gaiia, and payments your customers make by phone through Paymentus are recorded on their account automatically.

This integration must be configured by users with the Settings > Integrations permission. Creating the API key for phone payments requires the Settings > API keys permission.

Steps

Setting up the Paymentus integration involves four parts: requesting your credentials from Paymentus, installing the integration in gaiia, configuring the webhook with Paymentus, and creating an API key for phone payments. Follow each section in order. 

We recommend using your Paymentus sandbox credentials in your gaiia sandbox instance first, then repeat the process in production once testing is complete.

A. Get your Paymentus credentials

Paymentus issues the credentials gaiia needs. They aren't all available in your Paymentus Agent Dashboard. Contact your Paymentus representative and request a gaiia XOTP integration for your TLA. Paymentus should provide the following for both their sandbox (UAT) and production environments:

1. XOTP secret and KID.
2. Tokenization secret, sometimes called the encryption key.
3. Webhook secret.
4. The payment type codes to use for residential accounts, commercial accounts, and property groups.

If your customers will pay by phone, also ask Paymentus to enable real-time account lookup and payment notifications with gaiia for phone (IVR) payments.
 

B. Install the integration in gaiia

1. Go to the Settings page and select Integrations.
2. Open the App directory tab.
3. Find Paymentus under the Payments category and click the Install button.

4. In the Select payment type step, select Credit card payments, Bank account payments, or both, and click the Next button.

   If Paymentus gave you separate credentials for credit cards and bank accounts, turn on Use different credentials for each payment type instead. You'll then add one configuration for each payment type.

5. Click the Add configuration button.
6. Fill in the fields with the credentials from step A.
7. Copy the Webhook URL displayed at the top of the configuration. You'll need it in step C.
8. Click the Connect button to complete the process.

Once connected, Paymentus appears in the Installed apps tab. Secret values are hidden after you save them.

C. Configure the webhook with Paymentus

Paymentus uses the webhook to send gaiia real-time payment notifications, including phone payments, bank returns, and chargebacks.

If the webhook secret Paymentus sends doesn't exactly match the one saved in gaiia, gaiia ignores the notification. Paymentus doesn't see an error on their side, so phone payments and returns won't appear in gaiia. If you change the webhook secret, update it in gaiia and with Paymentus at the same time.

1. Send your Paymentus contact the Webhook URL copied in step B.

   It looks like: https://webhooks.gaiia.systems/paymentus/{unique-id}/{unique-id}.

2. Ask Paymentus to send the Webhook secret in the Authorization header of every notification, exactly as it's entered in gaiia.
3. Confirm with Paymentus that notifications are enabled for all payment channels, including phone (IVR) payments, bank account returns, and chargebacks.

D. Create an API key for phone payments (optional)

When a customer pays by phone, Paymentus looks up their account in gaiia to confirm it exists and to read the amount due. Paymentus needs its own API key to do this. Skip this step if your customers won't pay by phone.

1. Go to the Settings page and select API keys.
2. In the Secret keys tab, click the New API key button.
3. Enter a Name, for example "Paymentus".
4. Optionally, add the IP addresses Paymentus calls from in Allowed IP addresses. Ask Paymentus for this list.
5. Click the Next button.
6. Under Permissions, give view access to Accounts, including Accounts > Billing > View. If you bill commercial accounts, also give view access to Commercial accounts.
7. Click the Generate API key button.
8. Copy the key and share it securely with Paymentus.

Customers identify themselves on the phone with their Account ID. Make sure Paymentus uses the gaiia Account ID as the account number. If a phone payment comes in with an account number gaiia can't match, it's recorded as an unlinked payment so your team can assign it manually.

Confirm the integration works as expected

Complete the full payment and refund flow with both payment types in your gaiia sandbox instance, using the test cards and bank accounts provided by Paymentus.

Credit card

1. Create a payment method using a test credit card. The secure Paymentus form opens inside gaiia.

   Once the card is saved, gaiia asks whether to use it for future invoices. Select Yes, enable automatic payments or Skip, set up later.

2. Create a payment:

   • Click on Make payment.
   • Select the new credit card payment method.
   • Enter an amount of $1 or more.

   If a convenience fee applies, gaiia shows the fee and the total. Check I agree to the additional convenience fee being charged. to continue.

3. Verify that the payment appears in your Paymentus transaction history.
4. Issue a refund in gaiia.
5. Confirm the refund also appears in your Paymentus transaction history.

Bank account (ACH)

1. Create a bank account payment method using a test bank account.
2. Create a payment:
   • Click on Make payment.
   • Select the new bank account payment method.
   • Enter an amount of $1 or more.
3. Verify that the payment appears in your Paymentus transaction history.
4. Issue a refund in gaiia and confirm it also appears in Paymentus.

Bank account payments are marked as "Succeeded" as soon as Paymentus accepts them. If the bank later returns the payment, Paymentus notifies gaiia and the payment changes to "Failed". Card chargebacks are reported the same way.

Phone payments

1. Call your Paymentus test phone line and pay using a test account's Account ID.
2. Confirm the payment appears on that account in gaiia.