Documentation Développeur

curl -X POST http://localhost:4040/v1/escrows \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ref": "order_1042",
    "amount": 25000,
    "currency": "CDF",
    "commission_amount": 2500,
    "callback_url": "https://shop.cd/hooks/payinstant",
    "parties": [
      { "role": "payer", "phone": "0972148867", "external_id": "buyer_1" },
      { "role": "payee", "phone": "0998001122", "display_name": "Seller" }
    ]
  }'

<?php
$payload = [
  'merchant_ref' => 'order_1042',
  'amount' => 25000,
  'currency' => 'CDF',
  'commission_amount' => 2500,
  'callback_url' => 'https://shop.cd/hooks/payinstant',
  'parties' => [
    ['role' => 'payer', 'phone' => '0972148867'],
    ['role' => 'payee', 'phone' => '0998001122', 'display_name' => 'Seller'],
  ],
];

$ch = curl_init('http://localhost:4040/v1/escrows');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PAYINSTANT_SECRET_KEY'),
    'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);
$res = json_decode(curl_exec($ch), true);
$escrowId = $res['data']['id'];

import { randomUUID } from "node:crypto";

const res = await fetch("http://localhost:4040/v1/escrows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYINSTANT_SECRET_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchant_ref: "order_1042",
    amount: 25000,
    currency: "CDF",
    commission_amount: 2500,
    callback_url: "https://shop.cd/hooks/payinstant",
    parties: [
      { role: "payer", phone: "0972148867" },
      { role: "payee", phone: "0998001122", display_name: "Seller" },
    ],
  }),
});
const { data } = await res.json();
console.log(data.id, data.status);

// ⚠️ Ne jamais appeler /v1/escrows avec sk_ depuis le navigateur.
// Exposez plutôt un endpoint sur VOTRE backend, puis :
async function createEscrowFromCheckout(orderId) {
  const res = await fetch("/api/payinstant/escrows", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ orderId }),
  });
  return res.json();
}

// app/api/payinstant/escrows/route.ts
import { randomUUID } from "crypto";
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const body = await req.json();
  const res = await fetch(`${process.env.KANGA_BASE_URL}/v1/escrows`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PAYINSTANT_SECRET_KEY}`,
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      merchant_ref: body.orderId,
      amount: body.amount,
      currency: "CDF",
      parties: body.parties,
    }),
  });
  const json = await res.json();
  return NextResponse.json(json, { status: res.status });
}

import os, uuid, requests

r = requests.post(
    "http://localhost:4040/v1/escrows",
    headers={
        "Authorization": f"Bearer {os.environ['PAYINSTANT_SECRET_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "merchant_ref": "order_1042",
        "amount": 25000,
        "currency": "CDF",
        "commission_amount": 2500,
        "parties": [
            {"role": "payer", "phone": "0972148867"},
            {"role": "payee", "phone": "0998001122", "display_name": "Seller"},
        ],
    },
)
print(r.json()["data"]["id"])

curl -X POST http://localhost:4040/v1/escrows/$ID/collect \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_number": "0972148867",
    "method": "airtel",
    "firstname": "Paul",
    "lastname": "Client",
    "email": "paul@example.com"
  }'

$ch = curl_init("http://localhost:4040/v1/escrows/{$escrowId}/collect");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PAYINSTANT_SECRET_KEY'),
    'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'customer_number' => '0972148867',
    'method' => 'airtel',
    'firstname' => 'Paul',
    'lastname' => 'Client',
    'email' => 'paul@example.com',
  ]),
]);
$status = json_decode(curl_exec($ch), true)['data']['status']; // collecting

await fetch(`http://localhost:4040/v1/escrows/${id}/collect`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYINSTANT_SECRET_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_number: "0972148867",
    method: "airtel",
    firstname: "Paul",
    lastname: "Client",
    email: "paul@example.com",
  }),
});

// app/api/payinstant/collect/route.ts
export async function POST(req: Request) {
  const { id, ...body } = await req.json();
  const res = await fetch(
    `${process.env.KANGA_BASE_URL}/v1/escrows/${id}/collect`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.PAYINSTANT_SECRET_KEY}`,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    },
  );
  return Response.json(await res.json(), { status: res.status });
}

# Libérer au vendeur
curl -X POST http://localhost:4040/v1/escrows/$ID/release \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

# Ou rembourser l'acheteur
curl -X POST http://localhost:4040/v1/escrows/$ID/refund \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

function kanga_post(string $path): array {
  $ch = curl_init('http://localhost:4040' . $path);
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      'Authorization: Bearer ' . getenv('PAYINSTANT_SECRET_KEY'),
      'Idempotency-Key: ' . bin2hex(random_bytes(16)),
      'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{}',
  ]);
  return json_decode(curl_exec($ch), true);
}

kanga_post("/v1/escrows/{$id}/release");
// kanga_post("/v1/escrows/{$id}/refund");

async function release(id) {
  const res = await fetch(`http://localhost:4040/v1/escrows/${id}/release`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PAYINSTANT_SECRET_KEY}`,
      "Idempotency-Key": crypto.randomUUID(),
    },
  });
  if (!res.ok) throw new Error((await res.json()).error);
  return res.json();
}

<?php
/** functions.php ou plugin — release après livraison WooCommerce */
function kanga_release_escrow($escrow_id) {
  $res = wp_remote_post(
    trailingslashit(getenv('KANGA_BASE_URL')) . "v1/escrows/{$escrow_id}/release",
    [
      'headers' => [
        'Authorization' => 'Bearer ' . getenv('PAYINSTANT_SECRET_KEY'),
        'Idempotency-Key' => wp_generate_uuid4(),
        'Content-Type' => 'application/json',
      ],
      'body' => '{}',
      'timeout' => 30,
    ]
  );
  return json_decode(wp_remote_retrieve_body($res), true);
}

add_action('woocommerce_order_status_completed', function ($order_id) {
  $escrow_id = get_post_meta($order_id, '_kanga_escrow_id', true);
  if ($escrow_id) kanga_release_escrow($escrow_id);
});

import express from "express";
import crypto from "crypto";

const app = express();
app.post("/hooks/payinstant", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  const sig = req.get("x-kanga-signature") || "";
  const expected = crypto
    .createHmac("sha256", process.env.KANGA_WEBHOOK_SECRET)
    .update(raw)
    .digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send("invalid signature");
  }
  const event = JSON.parse(raw);
  // event.event === "escrow.held" | "escrow.released" | …
  res.json({ ok: true });
});

<?php
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_KANGA_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, getenv('KANGA_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig)) {
  http_response_code(401);
  exit('invalid signature');
}
$event = json_decode($raw, true);
// $event['event'], $event['data']
http_response_code(200);
echo json_encode(['ok' => true]);

// app/api/hooks/payinstant/route.ts
import { createHmac, timingSafeEqual } from "crypto";

export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get("x-kanga-signature") || "";
  const expected = createHmac("sha256", process.env.KANGA_WEBHOOK_SECRET!)
    .update(raw)
    .digest("hex");
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return new Response("invalid signature", { status: 401 });
  }
  const event = JSON.parse(raw);
  // handle event.event
  return Response.json({ ok: true });
}

import hmac, hashlib
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/payinstant")
def kanga_hook():
    raw = request.get_data()
    sig = request.headers.get("X-Payinstant-Signature", "")
    expected = hmac.new(
        os.environ["KANGA_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)
    event = request.get_json(force=True)
    return {"ok": True}

<?php
add_action('rest_api_init', function () {
  register_rest_route('kanga/v1', '/webhook', [
    'methods' => 'POST',
    'permission_callback' => '__return_true',
    'callback' => function (WP_REST_Request $req) {
      $raw = $req->get_body();
      $sig = $req->get_header('x-kanga-signature');
      $expected = hash_hmac('sha256', $raw, getenv('KANGA_WEBHOOK_SECRET'));
      if (!hash_equals($expected, (string) $sig)) {
        return new WP_Error('invalid_sig', 'Invalid signature', ['status' => 401]);
      }
      $event = json_decode($raw, true);
      if (($event['event'] ?? '') === 'escrow.held') {
        // marquer commande payée…
      }
      return ['ok' => true];
    },
  ]);
});
// URL callback : https://votresite.cd/wp-json/kanga/v1/webhook