API documentation


The Paybilla API uses  API keys (client_id, client_secret) to authenticate requests. You can view and manage your API keys in the Paybilla Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Your token will expire in 10 hours.

curl https://initialization-api.paybilla.com/o/token \
-d grant_type="password"
-d scope="write"
-d client_id=""
-d client_secret=""
-d username=""
-d password=""
You should put in header: Content-Type: application/x-www-form-urlencoded . The body parameters example:
{	"refresh_token": "fvQXQghivkpLZ2jHxEGBpZL4d453ul",	"access_token": "EhLwZfBr0tRsg0kaplPq7wHfu6wxW3",	"scope": "write",	"token_type": "Bearer",	"expires_in": 36000

Payment initialization


  • cart_total

    Amount that can be captured from this Payment

  • cart_db_id

    Unique identifier for the order

  • currency

    Three-letter ISO currency code, in lowercase.

  • products
    array of objects

    Object with products

    • name string

      The name of products

    • price string

      Price of product

    • product_type string

      The type of product. Suported values are: Digital, Service, Physical, Bundle, Downladable, Grouped, Subscription

    • quantity string

      Number of products

  • callback_parameters

    Empty Object

  • return_parameters

    Empty Object

{	"cart_total" : 10,	"cart_db_id" : "2eZvKYlo2C2Hx3k1gF",	"currency" : "EUR", "products" :	[	{	"name" : "Product name",	"price" : 10.99,	"product_type" : "Digital",	"quantity" : 1	},	{	"name" : "Product name #2",	"price" : 9.99,	"product_type" : "Digital",	"quantity" : 1	}	],	"callback_parameters" : {},	"return_parameters" : {}
{	"payment_id": "59558852-96da-46d4-8d51-d45da7db08a2",	"auth_hash": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiYSNIViE4U25iIyIsImlhdCI6MTU2OTQwNTkyMiwiZXhwIjoxNTY5NDkyMzIyfQ.7uCo7LXAkwP8c-f5SHInxhn2KBpkr3vgT7l1zZS50hs"

Error response

Paybilla uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Paybilla's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

  • Error Code: 1
    HTTP Response code: 400


    {	"error_code" : 1,	"error_msg" : "Merchant account not active."
    In this case you should check your merchant account or contact support@paybilla.com.
  • Error Code: 2
    HTTP Response code: 400


    {	"error_code" : 2,	"error_msg" : "Please check your merchant dashboard business settings."
  • Error Code: 3
    HTTP Response code: 400


    {	"error_code" : 3,	"error_msg" : "Invalid order: {explanatory message}"
  • Error Code: 4
    HTTP Response code: 400


    {	"error_code" : 4,	"error_msg" : "Can't initiate payment right now, please try again later"

HTTP status code summary

200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
402 - Request FailedThe parameters were valid but the request failed.
404 - Not FoundThe requested resource doesn't exist.
409 - ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server ErrorsSomething went wrong on Paybilla's end. (These are rare.)