Integrate mobile money into any application.

Authorization: Bearer sk_live_a1b2c3d4e5f6789...

# Request 5,000 UGX from a customer's Airtel Money wallet
curl -X POST https://yiyopay.com/api/v1/payments \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": 5000,
    "currency": "UGX",
    "payer_phone": "0700123456",
    "payer_name": "Jane Doe",
    "purpose": "Order #1001"
  }'

<?php
$ch = curl_init('https://yiyopay.com/api/v1/payments');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('YIYOPAY_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-1001',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount'      => 5000,
        'payer_phone' => '0700123456',
        'purpose'     => 'Order #1001',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
echo $response['data']['payment']['yiyopay_ref'];

const res = await fetch('https://yiyopay.com/api/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization':   `Bearer ${process.env.YIYOPAY_KEY}`,
    'Content-Type':    'application/json',
    'Idempotency-Key': 'order-1001',
  },
  body: JSON.stringify({
    amount:      5000,
    payer_phone: '0700123456',
    purpose:     'Order #1001',
  }),
});
const { data: { payment } } = await res.json();
console.log(payment.yiyopay_ref);

import os, requests

r = requests.post(
    "https://yiyopay.com/api/v1/payments",
    headers={
        "Authorization":   f"Bearer {os.environ['YIYOPAY_KEY']}",
        "Idempotency-Key": "order-1001",
    },
    json={"amount": 5000, "payer_phone": "0700123456", "purpose": "Order #1001"},
)
payment = r.json()["data"]["payment"]
print(payment["yiyopay_ref"])

{
  "success": true,
  "message": "",
  "data": {
    "payment": {
      "id":           1234,
      "yiyopay_ref":  "YPCOL2508259A3B1C",
      "status":       "processing",
      "amount":       5000,
      "fee_amount":   125,
      "total_amount": 5125,
      "merchant_net": 5000,
      "currency":     "UGX",
      "payer_phone":  "256700123456",
      "provider":     "airtel",
      "created_at":   "2025-08-26T14:22:11Z"
    }
  }
}

curl -X POST https://yiyopay.com/api/v1/payments \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"amount":10000,"payer_phone":"0772000000","purpose":"Invoice #42"}'

# Retry the exact same call — you get the original response, no new charge
curl -X POST https://yiyopay.com/api/v1/payments \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"amount":10000,"payer_phone":"0772000000","purpose":"Invoice #42"}'

// Use your order ID as the idempotency key
function collect($order_id, $amount, $phone) {
    $ch = curl_init('https://yiyopay.com/api/v1/payments');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('YIYOPAY_KEY'),
            'Idempotency-Key: order-' . $order_id,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'amount'=>$amount, 'payer_phone'=>$phone, 'purpose'=>"Order #{$order_id}",
        ]),
    ]);
    return json_decode(curl_exec($ch), true);
}

// Poll until terminal state or 60 seconds
function wait_for_payment($ref, $max_seconds = 60) {
    $deadline = time() + $max_seconds;
    while (time() < $deadline) {
        $ch = curl_init('https://yiyopay.com/api/v1/payments/' . $ref);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('YIYOPAY_KEY')],
        ]);
        $p = json_decode(curl_exec($ch), true)['data']['payment'];
        if (in_array($p['status'], ['successful', 'failed', 'cancelled', 'expired'])) {
            return $p;
        }
        sleep(3);
    }
    throw new \Exception('Payment timed out');
}

import os, time, requests

def wait_for_payment(ref, max_seconds=60):
    deadline = time.time() + max_seconds
    while time.time() < deadline:
        r = requests.get(
            f"https://yiyopay.com/api/v1/payments/{ref}",
            headers={"Authorization": f"Bearer {os.environ['YIYOPAY_KEY']}"},
        )
        p = r.json()["data"]["payment"]
        if p["status"] in ("successful", "failed", "cancelled", "expired"):
            return p
        time.sleep(3)
    raise TimeoutError("Payment timed out")

async function waitForPayment(ref, maxSeconds = 60) {
  const deadline = Date.now() + maxSeconds * 1000;
  while (Date.now() < deadline) {
    const r = await fetch(`https://yiyopay.com/api/v1/payments/${ref}`, {
      headers: { Authorization: `Bearer ${process.env.YIYOPAY_KEY}` }
    });
    const { data: { payment } } = await r.json();
    if (['successful', 'failed', 'cancelled', 'expired'].includes(payment.status)) {
      return payment;
    }
    await new Promise(r => setTimeout(r, 3000));
  }
  throw new Error('Payment timed out');
}

# Fixed-amount link (customer just approves)
curl -X POST https://yiyopay.com/api/v1/payment-links \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type":        "fixed",
    "title":       "Course fee — Term 3",
    "amount":      250000,
    "description": "Grade 5 tuition · Bright Future Academy"
  }'

# Open link (customer chooses amount)
curl -X POST https://yiyopay.com/api/v1/payment-links \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type":  "open",
    "title": "Donate to our cause"
  }'

// After creating, redirect the customer to the returned URL
$link = yp_create_link('Order #1001', 10000);
header('Location: ' . $link['url']);
exit;

curl -X POST https://yiyopay.com/api/v1/disbursements \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Idempotency-Key: payout-2025-089" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_phone": "0772987654",
    "recipient_name":  "John Kato",
    "amount":  50000,
    "purpose": "Supplier payment · INV-2025-089"
  }'

function pay_supplier($invoice_id, $phone, $name, $amount) {
    $ch = curl_init('https://yiyopay.com/api/v1/disbursements');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('YIYOPAY_KEY'),
            'Idempotency-Key: payout-' . $invoice_id,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'recipient_phone' => $phone,
            'recipient_name'  => $name,
            'amount'          => $amount,
            'purpose'         => "Supplier payment · INV-{$invoice_id}",
        ]),
    ]);
    return json_decode(curl_exec($ch), true);
}

async function paySupplier({ invoiceId, phone, name, amount }) {
  const res = await fetch('https://yiyopay.com/api/v1/disbursements', {
    method: 'POST',
    headers: {
      'Authorization':   `Bearer ${process.env.YIYOPAY_KEY}`,
      'Idempotency-Key': `payout-${invoiceId}`,
      'Content-Type':    'application/json',
    },
    body: JSON.stringify({
      recipient_phone: phone,
      recipient_name:  name,
      amount,
      purpose: `Supplier payment · INV-${invoiceId}`,
    }),
  });
  return res.json();
}

import os, requests

def pay_supplier(invoice_id, phone, name, amount):
    r = requests.post(
        "https://yiyopay.com/api/v1/disbursements",
        headers={
            "Authorization":   f"Bearer {os.environ['YIYOPAY_KEY']}",
            "Idempotency-Key": f"payout-{invoice_id}",
        },
        json={
            "recipient_phone": phone,
            "recipient_name":  name,
            "amount":          amount,
            "purpose":         f"Supplier payment · INV-{invoice_id}",
        },
    )
    return r.json()

// 1. Create the batch
$batch = api('POST', '/api/v1/disbursements/batches', [
    'title'   => 'August 2025 payroll',
    'purpose' => 'payroll',
])['data']['batch'];

// 2. Add recipients (up to 500 per batch)
foreach ($staff as $person) {
    api('POST', "/api/v1/disbursements/batches/{$batch['id']}/recipients", [
        'recipient_phone' => $person['phone'],
        'recipient_name'  => $person['name'],
        'amount'          => $person['salary'],
        'reference'       => $person['employee_id'],
    ]);
}

// 3. Submit (moves batch from 'draft' → 'submitted')
api('POST', "/api/v1/disbursements/batches/{$batch['id']}/submit");

// 4. From here — approval + processing happens in the dashboard or via API

curl -X POST https://yiyopay.com/api/v1/refunds \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_ref": "YPCOL2508259A3B1C",
    "amount":  5000,
    "reason":  "Order cancelled by customer"
  }'

curl "https://yiyopay.com/api/v1/payments?status=successful&from=2025-08-01&limit=100" \
  -H "Authorization: Bearer $YIYOPAY_KEY"

curl -X POST https://yiyopay.com/api/v1/customers \
  -H "Authorization: Bearer $YIYOPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":      "Jane Doe",
    "phone":     "0772000000",
    "email":     "jane@example.com",
    "reference": "STUDENT-2025-042"
  }'

# Request YiyoPay sends to your endpoint:
POST https://your-app.example.com/webhooks/yiyopay
Content-Type: application/json
X-Yiyopay-Event: payment.succeeded
X-Yiyopay-Signature: t=1735048800,v1=abc123def456...

{
  "event":      "payment.succeeded",
  "created_at": "2025-08-26T14:22:47Z",
  "data": {
    "payment": {
      "id":          1234,
      "yiyopay_ref": "YPCOL2508259A3B1C",
      "status":      "successful",
      "amount":      10000,
      "payer_phone": "256772000000",
      "provider":    "mtn"
    }
  }
}

function verify_yiyopay_signature($body_raw, $sig_header, $secret, $tolerance = 300) {
    if (!preg_match('/t=(\d+),v1=([a-f0-9]+)/', $sig_header, $m)) return false;
    [$_, $ts, $sig] = $m;
    // Reject replays — signatures older than 5 minutes are rejected
    if (abs(time() - (int)$ts) > $tolerance) return false;
    $expected = hash_hmac('sha256', $ts . '.' . $body_raw, $secret);
    return hash_equals($expected, $sig);
}

const crypto = require('crypto');

function verifyYiyoPaySignature(rawBody, sigHeader, secret, tolerance = 300) {
  const m = sigHeader.match(/t=(\d+),v1=([a-f0-9]+)/);
  if (!m) return false;
  const [, ts, sig] = m;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > tolerance) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

import hmac, hashlib, time, re

def verify_yiyopay_signature(raw_body: bytes, sig_header: str, secret: str, tolerance: int = 300) -> bool:
    m = re.match(r"t=(\d+),v1=([a-f0-9]+)", sig_header or "")
    if not m: return False
    ts, sig = m.groups()
    if abs(time.time() - int(ts)) > tolerance: return False
    payload = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

<?php
// public/webhooks/yiyopay.php  — the endpoint you registered with YiyoPay

$body   = file_get_contents('php://input');
$sig    = $_SERVER['HTTP_X_YIYOPAY_SIGNATURE'] ?? '';
$secret = getenv('YIYOPAY_WEBHOOK_SECRET');

// 1. Reject anything without a valid signature
if (!verify_yiyopay_signature($body, $sig, $secret)) {
    http_response_code(401);
    exit('invalid signature');
}

$event = json_decode($body, true);

// 2. Idempotency — store the event ID and skip if seen already
$pdo = new PDO('mysql:...');
$stmt = $pdo->prepare('INSERT IGNORE INTO webhook_events (event_id) VALUES (?)');
$stmt->execute([$event['data']['payment']['yiyopay_ref'] . '-' . $event['event']]);
if ($stmt->rowCount() === 0) {
    http_response_code(200); exit('already processed');
}

// 3. Handle the event
switch ($event['event']) {
    case 'payment.succeeded':
        $ref    = $event['data']['payment']['yiyopay_ref'];
        $amount = $event['data']['payment']['amount'];
        // mark the corresponding order/invoice as paid in your DB
        break;

    case 'payment.failed':
        // notify the customer, retry the collection, or mark the order abandoned
        break;

    case 'disbursement.succeeded':
        // mark the payroll line / supplier invoice as paid
        break;
}

// 4. Acknowledge — anything but 2xx and we'll retry
http_response_code(200);
echo 'ok';

const express = require('express');
const crypto  = require('crypto');
const app = express();

// Use raw body parser so we can verify signature exactly
app.post('/webhooks/yiyopay',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const raw = req.body.toString();
    const sig = req.headers['x-yiyopay-signature'];

    if (!verifyYiyoPaySignature(raw, sig, process.env.YIYOPAY_WEBHOOK_SECRET)) {
      return res.status(401).send('invalid signature');
    }

    const event = JSON.parse(raw);
    switch (event.event) {
      case 'payment.succeeded':
        await markOrderPaid(event.data.payment.yiyopay_ref);
        break;
      case 'payment.failed':
        await handleFailure(event.data.payment);
        break;
    }
    res.status(200).send('ok');
  }
);

X-RateLimit-Limit:     100
X-RateLimit-Remaining: 97
X-RateLimit-Reset:     1735048862   # unix timestamp when window resets