Turbo - API Documentation

Turbo API

Welcome to the Turbo REST API documentation.

To find your API key, please visit Settings > API in the Turbo dashboard.

In the provided examples, please swap <TURBO_API_KEY> with your API key and supply it as api_key when using this API.

Supported API calls:

Create QR Code

with Metadata

Customers

Payment Status

for an ID

Create QR Code #

Path:
https://api.tur.bo/qr

Request method:
POST

Required fields:
amount

Creates a QR code containing a Turbo payment link.

When QR codes are generated, we also create an internal invoice and PDF document attached to the invoice. These invoices can be viewed in the Turbo dashboard, which also shows their current payment status.

Example usage:

  
  curl \
  -X POST \
  -d api_key=<TURBO_API_KEY> \
  -d amount=1.00 \
  https://api.tur.bo/qr

  
  <?php
  $api_url ='https://api.tur.bo';
  $api_path='/qr';
  $api_key ='<TURBO_API_KEY>';
  $amount  =1.00;
  $fields  =array( 'api_key'=>$api_key,'amount'=>$amount );
  $opts    =array( 'form_params'=>$fields );
  
  try {
    $client  =new GuzzleHttp\Client( array( 'base_uri'=>$api_url ) );
    $response=$client->post( $api_path,$opts );
    $json    =$response->getBody();
    
    echo $json;
  }
  catch( Exception $e ) {
    echo 'error = ',$e->getMessage(),"\n";
  }
  ?>

JSON response:

  
  {
  "error":false,
  "msg":"OK",
  "created":1698859189,
  "amount":"1.00",
  "type":"qr",
  "status":"created",
  "id":"abc123",
  "url":"https://tur.bo/<your_username>/<payment_token>",
  "qr":"https://api.tur.bo/images/abc123.png",
  "metadata":[]
  }

Create QR Code with Metadata #

Metadata are fields passed to the Turbo API and returned back. These extra fields can be supplied as additional POST fields to our API.

One scenario where this would be useful, is to supply a customer name and account number to tie the payment to the customer and their corresponding account.

We will return these values in two places:

1) In the API JSON response object in the metadata array.

2) In webhooks when payments are completed. To receive these webhooks from our server, please set a webhook URL under Settings > Payments in the Turbo dashboard.

Example usage:


curl \
-X POST \
-d api_key=<TURBO_API_KEY> \
-d amount=1.00 \
-d customer=ABC123 \
-d account_number=XYZ456 \
https://api.tur.bo/qr


<?php
$api_url ='https://api.tur.bo';
$api_path='/qr';
$api_key ='<TURBO_API_KEY>';
$amount  =1.00;
$metadata=array( 'customer'=>'ABC123','account_number'=>'XYZ456' );
$fields  =array( 'api_key'=>$api_key,'amount'=>$amount,$metadata );
$opts    =array( 'form_params'=>$fields );

try {
  $client  =new GuzzleHttp\Client( array( 'base_uri'=>$api_url ) );
  $response=$client->post( $api_path,$opts );
  $json    =$response->getBody();
  
  echo $json;
}
catch( Exception $e ) {
  echo 'error = ',$e->getMessage(),"\n";
}
?>

JSON metadata response:


{
"error":false,
"msg":"OK",
"created":1698859189,
"amount":"1.00",
"type":"qr",
"status":"created",
"id":"abc123",
"url":"https://tur.bo/<your_username>/<payment_token>",
"qr":"https://api.tur.bo/images/abc123.png",
"metadata":[{ "customer":"ABC123","account_number":"XYZ456" }]
}

JSON response fields:

Key	Value
error	true or false depending on if an error has occurred in the API request
msg	OK if all is well, otherwise will include descriptive error text
created	timestamp for QR code creation
amount	payment amount to be collected
type	qr
status	created
id	ID of the QR code that can be used for looking up payment status
url	the payment URL for this item
qr	URL where the QR code can be accessed
metadata	a list of any extra fields passed to the Turbo API about the payment

Customers #

Path:
https://api.tur.bo/customers

Request method:
POST

No required fields

Optional fields:
id

View all customers. The optional filter id can be used to view a single customer's information.

Example usage:

  
  curl \
  -X POST \
  -d api_key=<TURBO_API_KEY> \
  https://api.tur.bo/customers

  
  <?php
  $api_url ='https://api.tur.bo';
  $api_path='/customers';
  $api_key ='<TURBO_API_KEY>';
  $fields  =array( 'api_key'=>$api_key );
  $opts    =array( 'form_params'=>$fields );

  try {
    $client  =new GuzzleHttp\Client( array( 'base_uri'=>$api_url ) );
    $response=$client->post( $api_path,$opts );
    $json    =$response->getBody();

    echo $json;
  }
  catch( Exception $e ) {
    echo 'error = ',$e->getMessage(),"\n";
  }
  ?>

JSON response:

  
  {
  "error": false,
  "msg": "OK",
  "type": "customers",
  "customers": [
  {
  "id": "123",
  "first_name": "Bob",
  "last_name": "Example",
  "created":"2023-11-01 11:19:49",
  "email": "[email protected]",
  "phone": "(000) 000-0000"
  }
  ]
  }

JSON response fields:

Key	Value
error	true or false depending on if an error has occurred in the API request
msg	OK if all is well, otherwise will include descriptive error text
type	customers
customers[]	list of all customers
customers.id	customer ID
customers.first_name	customer first name
customers.last_name	customer last name
customers.created	timestamp for customer creation
customers.email	customer email address
customers.phone	customer phone number

Payment Status #

Path:
https://api.tur.bo/status

Request method:
POST

No required fields

Optional fields:
id

Returns the payment status on a previously generated QR code. If no id parameter is given, all results are returned.

Example usage:


curl \
-X POST \
-d api_key=<TURBO_API_KEY> \
https://api.tur.bo/status


<?php
$api_url ='https://api.tur.bo';
$api_path='/status';
$api_key ='<TURBO_API_KEY>';
$fields  =array( 'api_key'=>$api_key );
$opts    =array( 'form_params'=>$fields );

try {
  $client  =new GuzzleHttp\Client( array( 'base_uri'=>$api_url ) );
  $response=$client->post( $api_path,$opts );
  $json    =$response->getBody();

  echo $json;
}
catch( Exception $e ) {
  echo 'error = ',$e->getMessage(),"\n";
}
?>

JSON response:


{
"error":false,
"msg":"OK",
"type":"payment",
"line_items":[{
  "id":"abc123",
  "amount":"$1.00",
  "status":"pending",
  "url":"https://tur.bo/<your_username>/<payment_token>",
  "qr":"https://api.tur.bo/images/abc123.png",
  "created":"2023-11-01 11:19:49",
  "convenience_fee":{"setting":null,"status":"disabled","value":null}
  },
  
  ...
  
  ]
}

Payment Status for an ID #

Return the status of a specific payment by ID. The id can be found in the JSON when QR codes are created.

To get the status of a payment with id=abc123:

Example usage:


curl \
-X POST \
-d api_key=<TURBO_API_KEY> \
-d id=abc123 \
https://api.tur.bo/status


<?php
$api_url ='https://api.tur.bo';
$api_path='/status';
$api_key ='<TURBO_API_KEY>';
$id      ='abc123';
$fields  =array( 'api_key'=>$api_key,'id'=>$id );
$opts    =array( 'form_params'=>$fields );

try {
  $client  =new GuzzleHttp\Client( array( 'base_uri'=>$api_url ) );
  $response=$client->post( $api_path,$opts );
  $json    =$response->getBody();
  
  echo $json;
}
catch( Exception $e ) {
  echo 'error = ',$e->getMessage(),"\n";
}
?>

JSON metadata response:


{
"error":false,
"msg":"OK",
"type":"payment",
"line_items":[{
  "id":"abc123",
  "amount":"$1.00",
  "status":"pending",
  "qr":"https://api.tur.bo/images/abc123.png",
  "created":"2023-11-01 11:19:49",
  "convenience_fee":{"setting":null,"status":"disabled","value":null}
  }]
}

JSON response fields:

Key	Value
error	true or false depending on if an error has occurred in the API request
msg	OK if all is well, otherwise will include descriptive error text
type	payment
line_items[]	list of all payment links
line_items.id	payment link ID
line_items.amount	payment amount
line_items.status	payment status can be pending, completed, or refunded
line_items.url	the payment URL for this item
line_items.qr	URL where the QR code can be accessed
line_items.created	timestamp for QR code creation
line_items.convenience_fee[]	convenience fee settings
line_items.convenience_fee.setting	when convenience fee is enabled, setting can be flat or percentage
line_items.convenience_fee.status	status is enabled if convenience fee is on, and disabled when off
line_items.convenience_fee.value	the dollar amount charged