# API overview > Welcome to the Payabli API reference. Find information on authentication, environments, rate limits, and best practices for using the Payabli APIs. 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 how to authenticate, 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](/guides/platform-tokenization-overview). API tokens are used for authentication, and payment method tokenization exchange sensitive payment method information for secure tokens. Your API tokens carry privileges, so be sure to keep them secure! **Don't share your private API tokens** in public areas such as GitHub, client-side code, or public domains. When you authenticate to the API, send the API token in the request header with the key **requestToken**. ```bash title="Example header" {5} curl --request POST \ --url 'https://api-sandbox.payabli.com/api/Endpoint'\ --header 'accept: application/json' \ --header 'content-type: application/*+json' \ --header '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. 1. Navigate to **Developers > API Tokens**, then click **Create API Token**. 2. In the modal, configure your API token. See the configuration options table below. 3. When finished, save your work.
Configuration option Description
Token Mode **Public** tokens are for embedded components, including Creator components. **Private** tokens are for Payabli APIs and payment devices.
Token Type The organization API token type is the most commonly used, and gives partners and paypoints access to most endpoints. The application API token is more advanced, and is used for authentication and managing entities. You rarely need to use an application API token. See the [API Token Types](#api-token-types) section for more information.
Token Lifetime API tokens can have a lifetime of between 1 and 24 months. Remember that you can delete unused or compromised API tokens at any time from the dashboard.
IP Restrictions Use this option to create an allowlist of IP addresses that can make requests with this API token. Leaving this option blank allows **all** IP addresses to make requests with this API token.
Creator Token? Select **Yes** to use this API token with Creator components. The API token type must be **Public** . Creator API tokens require that you configure domain restrictions.
Domain Restrictions Only available with Creator API tokens. For security, you must add the domains that you embed Creator components on. For example, if they're embedded on `https://app.myproduct.com` , then add `https://app.myproduct` here.
Description A descriptive name for the API token. This description appears in the dashboard and helps identify the API token.
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. 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**. 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. 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. User API tokens are valid for 120 minutes after creation, but expire after 1800 seconds (30 minutes) of inactivity. How to generate a user API token To generate a [user API token](/developers/api-reference/user/authenticate-user) you need: 1. Application API token (provided by the Payabli team to the Partner or Merchant). 2. User email and user password (the user's Payabli login credentials). ```bash curl --location --request POST 'https://api-sandbox.payabli.com/api/User/auth' \ --header 'requestToken: a.thisistheapplication.token' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data-raw '{ "email": "useremail@here.com", "psw": "xxxxxxxxxx" }' ``` 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 limits 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.
Number of requests Period
200 Minute
3000 15 Minutes
10000 Hourly
### 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.
Description Default Limit
Max number of declines per card, hourly 3
Max number of declines per IP address, hourly 3
Max declines per paypoint, hourly 10
Max declines per payor, hourly 3
Max transactions per paypoint in 15 minutes 250
Max transactions per card hourly 10
## 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.
Request type Timeout
Write requests (POST, PUT, DELETE) 30 seconds
Read requests (GET) 90 seconds
## 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](https://en.wikipedia.org/wiki/Universally_unique_identifier) 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. When using an idempotency key, your request header looks something like this: ```curl curl --request POST \ --url https://api.payabli.com/api/MoneyIn/getpaid \ --header "accept: application/json" \ --header "content-type: application/*+json" \ --header "idempotencyKey: dc125696-0c78-11ee-be56-0242ac120002" \ --header "requestToken: " ``` ### 409 conflict If you send an idempotencyKey more than once before it expires, you get a `409 Conflict` response: ```bash HTTP Response: 409 Conflict Duplicated idempotencyKey: 12345 ``` If you get this error when running a payment transaction, you can [query a list of transactions](/developers/api-reference/query/get-list-of-transactions-for-an-entrypoint) to pull in any information about a transaction that was approved but timed out. ### Use webhooks to avoid duplicate transactions \[#idempotency-webhooks] Payabli recommends using webhooks to help avoid duplicate transactions. All of the [Money In webhooks](/guides/pay-ops-notifications-webhooks-overview#pay-in-events) 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. You can get the list of active paypoints for your organization by making a request to the [List Paypoints](/developers/api-reference/paypoint/get-list-of-paypoints-for-an-organization) 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. ```json ... "EntryPoints": [ { "IdEntry": 100, "EntryName": "8cfec329267", ... } ] ``` 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.