PeerTupeer API Reference

v1.0 · REST API · JSON

Introduction

The PeerTupeer API allows you to programmatically submit gift card trades, check rates, manage withdrawals, and receive real-time webhook notifications. All API responses are in JSON format.

Authentication

All API requests (except public endpoints) require an API key passed in the X-API-Key header.

CopyX-API-Key: ptp_live_your_api_key_here

Generate API keys from your Merchant Dashboard → API Keys.

Base URL

Copyhttps://app.peertupeer.com/api/v1

For sandbox testing, use the same base URL but with a sandbox API key (prefixed with ptp_test_).

Rate Limits

API requests are limited to 100 requests per minute per API key. Exceeding this limit returns a 429 Too Many Requests response.

Error Handling

All errors return a JSON object with success: false and a descriptive message.

Copy{
  "success": false,
  "message": "Invalid API key or unauthorized access."
}

GET /rates

Returns all active exchange rates. No authentication required.

Copycurl https://app.peertupeer.com/api/v1/rates.php

Copy$response = file_get_contents('https://app.peertupeer.com/api/v1/rates.php');
$data = json_decode($response, true);

Copyconst res = await fetch('https://app.peertupeer.com/api/v1/rates.php');
const data = await res.json();

Trades

GET /trades — List Trades

Copycurl https://app.peertupeer.com/api/v1/trades.php \
  -H "X-API-Key: ptp_live_your_key"

POST /trades — Create Trade

Copycurl -X POST https://app.peertupeer.com/api/v1/trades.php \
  -H "X-API-Key: ptp_live_your_key" \
  -F "card_type_id=1" \
  -F "country=USA" \
  -F "currency=USD" \
  -F "card_amount=100" \
  -F "front_image=@/path/to/front.jpg" \
  -F "back_image=@/path/to/back.jpg" \
  -F "card_number=XXXX-XXXX-XXXX" \
  -F "receipt_image=@/path/to/receipt.jpg" \
  -F "notes=Optional notes here"

Copy{
  "success": true,
  "message": "Trade submitted successfully.",
  "data": {
    "reference": "PTP1A2B3C4D5E",
    "status": "pending",
    "card_amount": 100,
    "currency": "USD",
    "gross_payout_ghs": 850.00,
    "fee_ghs": 21.25,
    "net_payout_ghs": 828.75
  }
}

GET /trade-status — Check Trade

Copycurl "https://app.peertupeer.com/api/v1/trade-status.php?reference=PTP1A2B3C4D5E" \
  -H "X-API-Key: ptp_live_your_key"

GET /wallet — Wallet Balance

Copycurl https://app.peertupeer.com/api/v1/wallet.php \
  -H "X-API-Key: ptp_live_your_key"

Withdrawals

POST /withdrawals — Create Withdrawal

Copycurl -X POST https://app.peertupeer.com/api/v1/withdrawals.php \
  -H "X-API-Key: ptp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "method": "mtn_momo",
    "account_name": "John Doe",
    "account_number": "0241234567"
  }'

Webhooks

Webhooks are HTTP POST requests sent to your endpoint when events occur. Verify the signature using the X-PeerTupeer-Signature header.

Copy// PHP webhook verification
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PEERTUPEER_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, YOUR_WEBHOOK_SECRET);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
$event = json_decode($payload, true);

Rate Update Callbacks

Subscribe to receive a webhook notification whenever a rate is updated on the platform. This lets your integration stay in sync with current rates without polling.

The rate.updated event is sent to all subscribed URLs whenever an admin changes a rate.

GET /rate-updates — List Subscriptions

Copycurl https://app.peertupeer.com/api/v1/rate-updates.php \
  -H "X-API-Key: ptp_live_your_key"

POST /rate-updates — Subscribe

Copycurl -X POST https://app.peertupeer.com/api/v1/rate-updates.php \
  -H "X-API-Key: ptp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/webhooks/rates"}'

Copy{
  "success": true,
  "message": "Rate update subscription created.",
  "data": {
    "webhook_id": 5,
    "url": "https://yoursite.com/webhooks/rates",
    "event": "rate.updated",
    "secret": "your_webhook_secret"
  }
}

DELETE /rate-updates — Unsubscribe

Copycurl -X DELETE "https://app.peertupeer.com/api/v1/rate-updates.php?id=5" \
  -H "X-API-Key: ptp_live_your_key"

rate.updated Webhook Payload

When a rate changes, your callback URL receives a POST request with this payload:

Copy{
  "event": "rate.updated",
  "timestamp": "2026-05-25T10:30:00Z",
  "data": {
    "card_type_id": 1,
    "card_name": "Amazon",
    "country": "USA",
    "currency": "USD",
    "rate_per_unit": 8.75,
    "platform_fee_pct": 2.5,
    "updated_at": "2026-05-25 10:30:00"
  }
}

Verify the signature using the X-PeerTupeer-Signature header (same as other webhooks).

Sandbox Testing

Use sandbox API keys (prefixed with ptp_test_) to test without real transactions.

Copycurl "https://app.peertupeer.com/api/v1/sandbox.php?action=test-cards"