Integration testing guide

Learn how to test your Payabli integration
View as MarkdownOpen in Claude
Applies to:Developers

Test Payabli’s APIs and features in the sandbox environment before going live with your Payabli integration. You need a Payabli sandbox account to do any testing.

Pay In

This section explains how to test Payabli’s Pay In features in the sandbox environment.

Process transactions

You can create transactions with the API or Payabli’s embedded components. To create a transaction via the API, see Make a sale transaction. To create a transaction via Payabli’s embedded components, see Embedded components overview.

You can simulate declined transactions in the sandbox environment by using Payabli’s provided test cards. See test accounts for more information.

Cancel transactions

You can cancel a transaction in the sandbox environment by voiding or refunding it:

  • Void: If the transaction isn’t settled, you can void it to prevent the transaction from settling.
  • Refund: If the transaction is settled, you can refund it and send the money back to the account holder.

By default, sandbox transactions settle at 9:00 PM UTC daily. To test the void path, void a transaction the same day before that settlement run, while its SettlementStatus is still 0 (Pending). Transactions left until after settlement can only be refunded. To change the settlement time, contact your Payabli solutions engineer.

See the Decision guide: Void vs refund to choose the right method, and Cancel a Pay In transaction for more on canceling transactions.

Handle disputes

Chargebacks and ACH returns are dispute events that occur when a customer disputes a transaction in a production environment. To test how your app handles them in the sandbox environment, set up a webhook for the relevant event, then trigger it:

1

Create a webhook notification

Create a webhook notification for the ReceivedChargeBack or ReceivedAchReturn event. See Manage notifications for more information.

2

Create webhook handling logic

Your app should handle the webhook notification when it’s received via an HTTP request. This includes parsing the notification data and triggering behavior based on the event type.

3

Trigger the event

Trigger the dispute event so Payabli sends the webhook notification to your app:

  • Chargeback: Import a test chargeback in the Payabli Portal. See Simulate a chargeback below.
  • ACH return: Contact your Payabli solutions engineer with the ACH transaction IDs you want turned into returns. There’s no self-serve API or Portal flow for ACH returns.

In a production environment, these events are triggered automatically when a customer disputes a transaction.

After the dispute is created, you can retrieve it and respond to it with POST /ChargeBacks/response/{Id} to exercise the full read-and-respond flow. See Payment disputes to learn how disputes work and how to respond.

Simulate a chargeback

To create a test chargeback in the sandbox environment, import it as a CSV file in the Payabli Portal. A chargeback attaches to a settled card transaction, so make a card transaction and let it settle before you start. Importing the file updates the transaction’s dispute and funding status and fires the ReceivedChargeBack webhook.

1

Open the card disputes import

In the Payabli Portal, at the organization or paypoint level, go to Pay In > Reports > Card Disputes, then click Import.

2

Download and complete the example file

Download the example chargeback file the import screen provides, then fill in a row using a settled card transaction from your sandbox account. Enter the transaction’s ID in the Trans_Id column and its paypoint’s ID in the Paypoint_Id column. The example file shows the other columns to complete.

3

Upload the file

Drag and drop the completed CSV file (max 2 MB) onto the import screen, then click Accept. The transaction’s funding and dispute status update on upload.

Test payment funding statuses

All pay in transactions have a payment funding status. The payment funding status indicates where a transaction is in the settlement process. Transactions in the sandbox environment automatically progress through the following funding statuses:

  1. Pending - This transaction is in an open batch.
  2. In Transit - This transaction is in a closed batch that’s being routed to the banks.
  3. Transferred - The funds are being transferred to the merchant’s bank account.
  4. Funded (settled) - The funds are in the merchant’s bank account.

If you need to test how your app handles the following funding statuses, contact your Payabli solutions engineer:

  • Exception
  • ACH Return or Chargebacks
  • Held
  • Released

See Payment funding status for more information.

Pay Out

This section explains how to test Payabli’s Pay Out features in the sandbox environment.

Handle payouts

Payouts are expenses that you pay to your vendors. In Payabli, there are two steps for handling payouts:

  1. Authorizing - Reserves funds for a payout.
  2. Capturing - Flags authorized funds for batch processing.

After a payout is authorized, the funds are reserved and can’t be used for other payouts. After a payout is captured, the funds are transferred to the vendor’s bank account during the next batch processing window. To learn more about handling payouts, see Manage payouts with the API.

Manage vendors

Vendors are entities that receive funds from your payouts. You can reference vendors in payouts and bills to organize and track expenses. Before you can reference a vendor in a payout or bill, you must create the vendor. See Manage vendors with the API for more information on creating and managing vendors.

Manage bills

In Payabli, bills represent a bill from a vendor that a paypoint is expected to pay. To create a bill via the API, see Create bill. After you’ve created a bill, you can approve it for payment, update it, or delete it. See Manage bills with the API for more information.

Pay Ops

This section explains how to test Payabli’s Pay Ops features in the sandbox environment.

Board merchants

Boarding is the process of enabling paypoints to process payments via Payabli. There are four stages in the boarding process:

Sandbox boarding applications don’t go through actual underwriting and don’t automatically create paypoints. To move an application through the boarding stages and create a paypoint in sandbox, contact your Payabli solutions engineer.

2

Merchant applies

The merchant fills out and submits the boarding application. The merchant also e-signs the agreement during this step.

3

Underwriting

As merchants submit boarding applications in the sandbox environment, they automatically move from the “Submitted” status to the “Underwriting” status. If you need to test other boarding application statuses, or create new paypoints from boarding applications, contact your Payabli solutions engineer. In a production environment, Payabli reviews the merchant’s application and decides how to proceed with it.

4

Paypoint created

After a merchant is approved in underwriting in a production environment, a new paypoint is created. To create paypoints from boarding applications in the sandbox environment, contact your Payabli solutions engineer.

See Board merchants for more information.

See these related resources to help you get the most out of Payabli.