API overview
Get started with the Payabli API
Welcome to the Payabli API reference. Here you’ll find all the information you need for using the Payabli APIs.
Authentication
The Payabli API uses secure API tokens to authenticate requests. This guide explains the different API tokens you may use and how to create and manage basic API tokens.
Note that API tokens are different than payment method tokens. API tokens are used for authentication, and payment method tokenization exchange sensitive payment method information for secure tokens.
When you authenticate to the API, send the API token in the request header with the key requestToken.
You must make all API requests over HTTPS. API requests without authentication will fail.
Create and manage API tokens
You can create and manage your own API tokens in PartnerHub.
- Navigate to Developers > API Tokens, then click Create API Token.
- In the modal, configure your API token. See the configuration options table below.
- When finished, save your work.
To view or delete API tokens, navigate to Developers > API Tokens, then click the Action column of a token you want to manage.
API token types
To enhance security, Payabli has several different types of API token, each with different scopes and lifetime.
Organization API token (most common)
The organization token is the most basic and most commonly used API token used in the platform. Any organization or paypoint with an organization token has access to most API functions and endpoints. You can view and manage these API tokens in PartnerHub.
Payabli has two kinds of organization API tokens:
- Private Token: Private tokens are for making API calls and have the highest level of security.
- Public Token: Public tokens are for adding Payabli’s embeddable components in your user interface. These tokens are publicly readable.
You can’t access API endpoints related to management and authentication services for users with an organization token. To access to those services, you need an application token.
Application API token
The Payabli team generates application API tokens for partners that are using API endpoints for authentication and managing entities. For example, you need this kind of token if you are building your own portals for paypoints, or any solution that involves users authenticating to Payabli outside of PartnerHub or a PayHub.
User API token
If you are working outside of a PayHub or PartnerHub, the Payabli API requires you to retrieve a user API token before performing certain actions. These tokens add an extra layer of security for managing paypoints, managing users stored in Payabli, getting access to merchant documents, and using authentication services. If you are performing these activities within PartnerHub or a PayHub, you don’t need to generate this token.
You need an application API token to generate a user API token.
How to generate a user API token
To generate a user API token you need:
- Application API token (provided by the Payabli team to the Partner or Merchant).
- User email and user password (the user’s Payabli login credentials).
Temporary API token
Temporary API tokens are generated by services or endpoints related mainly to resetting passwords, multi-factor authentication (MFA), and activities without authentication that require approved security levels, like payment pages. Temporary tokens can be used for only one request in specific endpoints.
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).
Payabli reserves the right to alter rate limited in case of security concerns, and will communicate changes to impacted accounts.
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.
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 1 minute. After 1 minute, 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 Conflicterror.
When using an idempotency key, your request header looks something like this:
409 conflict
If you send an idempotencyKey more than once before it expires, you get a 409 Conflict response:
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.
Sometimes the terms “paypoint” and “entrypoint” are used seemingly interchangeably.
A paypoint is a merchant. An entrypoint is an alias used to identify an organization or a paypoint. Sometimes the entrypoint is referred to as entry or entryname in the APIs and as Entry Name in PartnerHub and PayHub.
Find an entrypoint with the API
You can get the list of active paypoints for your organization by making a request to the List Paypoints endpoint. You need the entry ID for the parent organization to make the request. Payabli gives you this ID in your onboarding documents.
A paypoint’s entrypoint is returned as EntryName in the response. This is the value you need to make any API calls that deal with that paypoint.
Find an entrypoint in PartnerHub
You can get entrypoint names from the UI in PartnerHub. Just navigate to Portfolio > Paypoints, and copy the value in the Entry Name column for the paypoint you want to work with.