API Guidelines

Important things to confirm before implementing our API and especially before going to production.

Card Usage

Please ensure you set reasonable expiry dates using validityPeriod for cards or validFrom, validTo, validTimezone for travel cards when issuing cards. Cards should only be active during the time they are in use and otherwise not. This acts as an additional layer against fraud and keeps costs low.

Please terminate any unused cards to avoid unnecessary usage or expenses.

API Rate Limits

Auth0 API Endpoints

Please fetch a new BearerToken only shortly before the TTL runs out on the machine/instance. See also the more detailed explanation here. We have the right to block requests that notably exceed this limit.

Pliant API Endpoints

You are limited to 900 requests per 5 minutes per IP address.

When hitting that limit, the IP address will be blocked, until the number of requests goes below the threshold. You will receive a similar HTTP response then from our endpoints:

HTTP/1.1 429 Too Many Requests
Server: awselb/2.0
Date: Wed, 21 Sep 2022 08:22:06 GMT
Content-Length: 73
Connection: keep-alive
Content-Type: application/json

{
"error": "Sending more than 900 requests in 5 minutes is not allowed"
}

If you are consistently hitting this limit, please contact us with as much detail as possible regarding your use case and we can look into increasing this for you.

Fair API Usage

Be fair when using our API endpoints and do not send unnecessary requests. In case you are violating the fair use policy of Pliants APIs, Pliant has the right to suspend the API services in the event of persistent excessive load.

Batch Endpoints

Our API provides both single (one result per entity ID) and batch (multiple results per entity ID) endpoints for retrieving entity details for cards and transactions. Please favour using batch endpoints whenever possible to minimise the number of individual requests.

Caching Data

Consider caching data on your end to your liking to reduce the number of calls you have to make to the API itself. This also increases your own user experience, as data is already available in your infrastructure.

Retries on Errors

Don't retry failing messages unlimited times. Implement reasonable retry logic on transient errors in your client (e.g. HTTP 5xx), but don't retry on functional errors (e.g. HTTP 4xx). We strongly recommend that you log what your application is sending to us to to improve error handling gradually.

Callbacks

When using callbacks, please adhere to the HTTP status codes. We do retries of failed callback transmission automatically only on the 4xx and 5xx error codes for the maximum of one day. For details please refer to the callback section.

We do offer an endpoint to fetch the callback log, which tracks all events emitted by the platform based on subscriptions. Please utilise this log to troubleshoot issues before contacting us with potential errors.

Issues & Support Requests

Before creating a support request please check our API status page for information about known issues.

Check our API changelog to make sure you don't miss any important updates regarding new features, improvements or depreciation notifications

We don't log all request payloads due to internal data protection governance. To speed up handling your support requests please always include a full curl example of the request when reaching out to us.

For further help please reach out to [email protected].