Build protected payment flows with TrustLink.

1. Overview

The TrustLink Escrow API allows online stores, marketplaces, and social commerce tools to programmatically issue protected payment links for Ghanaian Mobile Money transactions (MTN MoMo, Telecel Cash, and AT Money).

When an escrow is created via API, TrustLink issues a unique payment contract with a hosted checkout URL. Buyers complete Mobile Money payment on the checkout page, locking funds securely in escrow until item delivery is confirmed.

2. Quickstart

Get up and running with the TrustLink Escrow API in 5 simple steps:

1. Create or access a verified vendor account

   Sign up at signup or log into your seller account at login.

2. Generate your Secret API Key

   Navigate to the Vendor Dashboard Settings tab to generate your unique x-api-key credential.

3. Store key securely in server environment variables

   Keep your secret key inside server configuration variables (e.g. TRUSTLINK_API_KEY). Never expose it in client-side code.

4. Send a POST request to create an escrow

   Issue an HTTP POST request to https://www.trustlinkgh.online/api/v1/escrows with required transaction details.

5. Redirect buyer to checkoutUrl

   Redirect the buyer to the returned checkoutUrl or display it in your store UI to complete Mobile Money authorization.

3. Authentication

The API uses custom HTTP header authentication via the x-api-key header. Every request from your application server must include this credential.

x-api-key: YOUR_SECRET_API_KEY

If the x-api-key header is omitted, the server returns an HTTP 401 Unauthorized error. If the key is invalid or revoked, the server returns an HTTP 403 Forbidden response.

5. Create an Escrow

Creates a new escrow record in state PENDING_PAYMENT and returns a hosted checkout URL for the buyer.

6. Request Fields

The request body must be a JSON object containing the following parameters:

Note: All transactions default to Ghana Cedis (GH₵ / GHS). Additional currency fields are not required.

7. Code Examples & Example Response

curl -X POST "https://www.trustlinkgh.online/api/v1/escrows" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "amount": 450.00,
    "description": "Used iPhone 13 Pro",
    "buyerPhone": "+233550000000",
    "buyerEmail": "buyer@example.com",
    "customReference": "ORDER-1234"
  }'

const response = await fetch("https://www.trustlinkgh.online/api/v1/escrows", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.TRUSTLINK_API_KEY // Use server environment variable
  },
  body: JSON.stringify({
    amount: 450.00,
    description: "Used iPhone 13 Pro",
    buyerPhone: "+233550000000",
    buyerEmail: "buyer@example.com",
    customReference: "ORDER-1234"
  })
});

const data = await response.json();
console.log(data);

import os
import requests

url = "https://www.trustlinkgh.online/api/v1/escrows"
headers = {
    "Content-Type": "application/json",
    "x-api-key": os.environ.get("TRUSTLINK_API_KEY")
}
payload = {
    "amount": 450.00,
    "description": "Used iPhone 13 Pro",
    "buyerPhone": "+233550000000",
    "buyerEmail": "buyer@example.com",
    "customReference": "ORDER-1234"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

<?php
$apiKey = getenv('TRUSTLINK_API_KEY');
$url = 'https://www.trustlinkgh.online/api/v1/escrows';

$payload = json_encode([
    'amount' => 450.00,
    'description' => 'Used iPhone 13 Pro',
    'buyerPhone' => '+233550000000',
    'buyerEmail' => 'buyer@example.com',
    'customReference' => 'ORDER-1234'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

Example Response (HTTP 201 Created)

{
  "id": "escrow_8f9a2b3c4d",
  "status": "PENDING_PAYMENT",
  "checkoutUrl": "https://www.trustlinkgh.online/checkout.html?id=escrow_8f9a2b3c4d",
  "customReference": "ORDER-1234"
}

8. Errors & Status Codes

The TrustLink Escrow API returns standard HTTP status codes to indicate request success or failure:

9. Transaction States

Every escrow contract created in TrustLink follows a strictly monitored transaction state machine. UI elements and Firestore listeners map these constants to official status colors:

Exceptions: Escrows under dispute move to DISPUTED and resolve to REFUNDED or authorized completion.

10. Webhooks Notice

11. WooCommerce Integration

TrustLink Escrow provides an official WordPress payment gateway plugin for WooCommerce stores located in trustlink-woocommerce-plugin/.

To inspect or install the WooCommerce plugin source code, refer to the repository plugin directory.

12. API Key Security Guidelines

Protect your integration credentials by following these security rules:

• Never commit secret keys: Add key configuration files to .gitignore.
• Server-side requests only: Always invoke the API from secure server code or Cloud Functions. Never call /api/v1/escrows directly from frontend JavaScript in the browser.
• Rotate compromised keys: If a key is accidentally leaked in a repository or log, immediately revoke it in your Vendor Dashboard Settings and issue a new key.

13. Developer Support

Need assistance integrating TrustLink Escrow into your platform?