API overview

Welcome to the Payabli API reference. Here you’ll find all the information you need for using the Payabli APIs.

Authentication

Payabli supports two ways to authenticate API requests: a long-lived API token sent in the requestToken header, and OAuth2 client credentials exchanged for a short-lived Bearer token. See API token authentication for API tokens and the token types, and OAuth authentication for the OAuth2 flow.

Environments

Payabli offers two environments: a sandbox environment for development and a production environment to bring your Payabli integration live.

Sandbox

Use the sandbox environment to build your payments integration without having to charge actual payments and settle bank accounts. Test and run unlimited transactions and play around with Payabli’s tools to build your application.

Payabli Client Success and Development Support give you your sandbox API token after your integration kickoff call.

Sandbox API URL: https://api-sandbox.payabli.com/api

Production

Use the production environment to go live with your integration. Transactions in this environment charge payors and create actual settlements into bank accounts. This environment also lets you create bills and send them for actual payment.

Make sure you have completed extensive testing before launching. Reach out to the Payabli team to make sure you’re ready to launch.

Production API URL: https://api.payabli.com/api

Rate limits

For security and fraud prevention, Payabli applies two different kinds of rate limits: request limits, and transaction limits (also known as fraud controls).

Request limits

Payabli has request velocity limits in place to give optimal system performance, security, and fair usage. Request limits govern the number of requests a single API token can make to endpoints in a given period. Reach out to the Payabli team if you have a use case that requires limit changes.

Fraud controls

Fraud controls, also known as transaction limits, dictate the number of declines and transactions a paypoint may process within a specified period.

Reach out to the Payabli team to customize transaction limits for individual paypoints.

Request timeouts

The Payabli API has request timeouts. Write requests (POST, PUT, DELETE) time out after 30 seconds, and read requests (GET) time out after 90 seconds. If a request takes longer than the timeout, the API returns a 504 Gateway Timeout error.

Preventing duplicate requests

Payabli’s idempotencyKey header parameter lets you give your POST requests a unique identifier so you can safely retry a request that timed out without worrying about creating duplicate objects or transactions. Using them is optional, but is a best practice to avoid creating duplicate transactions.

The idempotency key is something that you must generate and include as a header parameter in POST requests. Payabli recommends using a UUID for your tokens.

When using idempotency keys, keep these considerations in mind.

• Payabli retains the idempotency key for 2 minutes. After 2 minutes, you can reuse the key if needed.
• If a transaction is declined because of a bad payment method, you can’t correct the payment information and retry the transaction with the same idempotency key value, it fails with a 409 Conflict error.
• The idempotency key you send on a request isn’t echoed back in the resulting webhook payload. To correlate a webhook delivery with your API call, use the transId field in the webhook payload. It matches the transaction identifier returned in the API response, although the field name varies by endpoint (for example, referenceId in v1 Money In or paymentTransId in v2).

When using an idempotency key, your request header looks something like this:

$
curl -X POST https://api.payabli.com/api/v2/MoneyIn/getpaid \
>
     -H "accept: application/json" \
>
     -H "content-type: application/*+json" \
>
     -H "idempotencyKey: dc125696-0c78-11ee-be56-0242ac120002" \
>
     -H "requestToken: <API TOKEN>"

409 conflict

If you send an idempotencyKey more than once before it expires, you get a 409 Conflict response:

$
HTTP Response: 409 Conflict
$
Duplicated idempotencyKey: 12345

If you get this error when running a payment transaction, you can query a list of transactions to pull in any information about a transaction that was approved but timed out.

Use webhooks to avoid duplicate transactions

Payabli recommends using webhooks to help avoid duplicate transactions. All of the Money In webhooks are helpful, and the ApprovedTransaction notification will let you know when a transaction has been approved.

One of the main reasons you might double-charge a card is if you tried to process the payment and received a timeout error response. In that case, you don’t know if the original transaction was received, processed, or approved, and the standard course of action is to resubmit the transaction request.

If you have webhooks configured, you will get a copy of the approval or decline response. You can use the response sent via webhook instead of the standard response you should have received but didn’t because the request timed out.

Entrypoint vs entry

An entrypoint is an alias used to identify an organization or paypoint. When you make a call via the API or with embedded components, the entrypoint value indicates which paypoint account to use for a payment, subscription, or storing a payment method.

1
...
2
      "EntryPoints": [
3
        {
4
          "IdEntry": 100,
5
          "EntryName": "8cfec329267",
6
    ...
7
        }
8
      ]