API reference

npm install https://soncopay.example/assets/sdk/soncopay-node-2.2.0.tgz

curl -O https://soncopay.example/assets/sdk/soncopay-php-2.2.0.zip
unzip soncopay-php-2.2.0.zip

pip install https://soncopay.example/assets/sdk/soncopay-2.2.0-py3-none-any.whl

import SoncoPay from 'soncopay-node';
// const { SoncoPay } = require('soncopay-node');

const sp = new SoncoPay(process.env.SONCOPAY_API_KEY);

const payment = await sp.payments.create({
  amount: '25.00',
  currency: 'USD',
  order_id: 'demo-1042',
  return_url: 'https://shop.example/thanks',
});
res.redirect(303, payment.checkout_url);

require __DIR__ . '/soncopay-php/autoload.php';

use SoncoPay\Client;

$sp = new Client(getenv('SONCOPAY_API_KEY'));

$payment = $sp->payments->create([
    'amount'     => '25.00',
    'currency'   => 'USD',
    'order_id'   => 'demo-1042',
    'return_url' => 'https://shop.example/thanks',
]);
header('Location: ' . $payment['checkout_url'], true, 303);

import os
from soncopay import SoncoPay

sp = SoncoPay(os.environ["SONCOPAY_API_KEY"])

payment = sp.payments.create(
    amount="25.00",
    currency="USD",
    order_id="demo-1042",
    return_url="https://shop.example/thanks",
)
return redirect(payment["checkout_url"], code=303)

app.post('/webhooks/soncopay', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = SoncoPay.webhooks.constructEvent(req.body, req.headers, process.env.SONCOPAY_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send('invalid signature');
  }
  if (event.event === 'payment.paid') {
    // deliver event.data.order_id
  }
  res.sendStatus(200);
});

use SoncoPay\Webhook;
use SoncoPay\Exception\SignatureVerificationException;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SONCOPAY_SIGNATURE'] ?? null;

try {
    $event = Webhook::constructEvent($payload, $signature, getenv('SONCOPAY_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit('invalid signature');
}
if ($event->event === 'payment.paid') {
    // deliver $event->data['order_id']
}
http_response_code(200);

from soncopay import construct_event, SignatureVerificationError

@app.post("/webhooks/soncopay")
def soncopay_webhook():
    try:
        event = construct_event(request.get_data(), request.headers.get("X-SoncoPay-Signature"), SECRET)
    except SignatureVerificationError:
        abort(400)
    if event.event == "payment.paid":
        # deliver event.data["order_id"]
    return "", 200

curl https://soncopay.example/v1/balances -H "X-Api-Key: sp_test_…"

import SoncoPay from 'soncopay-node';

const sp = new SoncoPay(process.env.SONCOPAY_API_KEY);   // sp_test_… or sp_live_…
const { balances } = await sp.balances();

$sp = new SoncoPay\Client(getenv('SONCOPAY_API_KEY'));   // sp_test_… or sp_live_…
$b = $sp->balances();

from soncopay import SoncoPay

sp = SoncoPay()   # reads SONCOPAY_API_KEY: sp_test_… or sp_live_…
b = sp.balances()

curl -X POST https://soncopay.example/v1/payments \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"amount":"25","currency":"USD","order_id":"1042","return_url":"https://shop.example/thanks",
       "payer":{"name":"Demo Customer","email":"[email protected]","reference":"client-42"}}'

const payment = await sp.payments.create({
  amount: '25',
  currency: 'USD',
  order_id: '1042',
  return_url: 'https://shop.example/thanks',
  payer: { name: 'Demo Customer', email: '[email protected]', reference: 'client-42' },
});
payment.checkout_url;

$payment = $sp->payments->create([
    'amount'     => '25',
    'currency'   => 'USD',
    'order_id'   => '1042',
    'return_url' => 'https://shop.example/thanks',
    'payer'      => ['name' => 'Demo Customer', 'email' => '[email protected]', 'reference' => 'client-42'],
]);
$payment['checkout_url'];

payment = sp.payments.create(
    amount="25",
    currency="USD",
    order_id="1042",
    return_url="https://shop.example/thanks",
    payer={"name": "Demo Customer", "email": "[email protected]", "reference": "client-42"},
)
payment["checkout_url"]

{
  "id": "pay_3f9a5c0d21e4b7a6c8d1",
  "object": "payment",
  "livemode": false,
  "status": "new",
  "amount": "25", "currency": "USD",
  "order_id": "1042",
  "checkout_url": "…/pay/pay_3f9a5c0d21e4b7a6c8d1",
  "payer": { "name": "Demo Customer", "email": "[email protected]", "reference": "client-42" },
  "expires_at": "2026-10-01T15:30:00+00:00",
  …
}

curl https://soncopay.example/v1/methods -H "X-Api-Key: sp_test_…"

const { methods, payment_methods } = await sp.methods();

$m = $sp->methods();
$m['methods']; $m['payment_methods'];

m = sp.methods()
m["methods"], m["payment_methods"]

curl -X POST https://soncopay.example/v1/payments/pay_3f9a5c0d21e4b7a6c8d1/method \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"method":"crypto","asset":"USDT","network":"TRON"}'

const p = await sp.payments.chooseMethod('pay_3f9a5c0d21e4b7a6c8d1', {
  method: 'crypto', asset: 'USDT', network: 'TRON',
});
p.pay_address; p.pay_amount;

$p = $sp->payments->chooseMethod('pay_3f9a5c0d21e4b7a6c8d1', [
    'method' => 'crypto', 'asset' => 'USDT', 'network' => 'TRON',
]);

p = sp.payments.choose_method("pay_3f9a5c0d21e4b7a6c8d1", "crypto", asset="USDT", network="TRON")
p["pay_address"], p["pay_amount"]

{ "method": "crypto", "asset": "USDT", "network": "TRON" }

# the payment now carries:
# pay_address, pay_amount (send exactly this amount), network, expires_at

{ "method": "binance_pay" }

# the payment now carries:
# pay_url (open it or show it as a QR code), pay_amount in USDT

{ "method": "card" }

# the payment now carries:
# pay_url = https://…/pay/{id}/redirect : send the customer there,
# they pay on the secure card page and come back to the payment page

# Côte d'Ivoire: Orange Money, amount in XOF (no decimals)
curl -X POST https://soncopay.example/v1/payments \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"amount":"5000","currency":"XOF","country":"CI","order_id":"demo-1043","method":"orange_ci","phone":"+2250700000000"}'

# Cameroon: MTN Mobile Money, amount in XAF (no decimals)
curl -X POST https://soncopay.example/v1/payments \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"amount":"5000","currency":"XAF","country":"CM","order_id":"demo-1044","method":"mtn_cm","phone":"+237670000000"}'

// Côte d'Ivoire: Orange Money, amount in XOF (no decimals)
const p = await sp.payments.create({
  amount: '5000', currency: 'XOF', country: 'CI', order_id: 'demo-1043',
  method: 'orange_ci', phone: '+2250700000000',
});
p.method_code;   // 'orange_ci'
p.instructions;  // text to show the customer
if (p.pay_url) res.redirect(303, p.pay_url);   // redirect mode

// Cameroon: MTN Mobile Money, amount in XAF (no decimals)
const q = await sp.payments.create({
  amount: '5000', currency: 'XAF', country: 'CM', order_id: 'demo-1044',
  method: 'mtn_cm', phone: '+237670000000',
});

// the operators of one country, from GET /v1/methods
const { methods } = await sp.methods();
methods.filter((m) => m.kind === 'mobile_money' && m.countries.includes('SN'));

// or later, on an existing payment (another operator of the same country)
await sp.payments.chooseMethod(p.id, { method: 'mobile_money', code: 'wave_ci', phone: '+2250700000000' });

// Côte d'Ivoire: Orange Money, amount in XOF (no decimals)
$p = $sp->payments->create([
    'amount' => '5000', 'currency' => 'XOF', 'country' => 'CI', 'order_id' => 'demo-1043',
    'method' => 'orange_ci', 'phone' => '+2250700000000',
]);
$p['method_code'];   // 'orange_ci'
$p['instructions'];  // text to show the customer
if ($p['pay_url'] !== null) {
    header('Location: ' . $p['pay_url'], true, 303);   // redirect mode
}

// Cameroon: MTN Mobile Money, amount in XAF (no decimals)
$q = $sp->payments->create([
    'amount' => '5000', 'currency' => 'XAF', 'country' => 'CM', 'order_id' => 'demo-1044',
    'method' => 'mtn_cm', 'phone' => '+237670000000',
]);

// or later, on an existing payment (another operator of the same country)
$sp->payments->chooseMethod($p['id'], ['method' => 'mobile_money', 'code' => 'wave_ci', 'phone' => '+2250700000000']);

# Côte d'Ivoire: Orange Money, amount in XOF (no decimals)
p = sp.payments.create(amount="5000", currency="XOF", country="CI", order_id="demo-1043",
                       method="orange_ci", phone="+2250700000000")
p["method_code"], p["instructions"]   # "orange_ci", text to show the customer
if p["pay_url"]:
    return redirect(p["pay_url"], code=303)   # redirect mode

# Cameroon: MTN Mobile Money, amount in XAF (no decimals)
q = sp.payments.create(amount="5000", currency="XAF", country="CM", order_id="demo-1044",
                       method="mtn_cm", phone="+237670000000")

# or later, on an existing payment (another operator of the same country)
sp.payments.choose_method(p["id"], "mobile_money", code="wave_ci", phone="+2250700000000")

# Senegal: Wave, XOF
curl -X POST https://soncopay.example/v1/payouts \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"method":"wave_sn","phone":"+221770000000","amount":"10000","reference":"demo-payout-8"}'

# Cameroon: Orange Money, XAF
curl -X POST https://soncopay.example/v1/payouts \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"method":"orange_cm","phone":"+237690000000","amount":"15000","reference":"demo-payout-9"}'

await sp.payouts.create({ method: 'wave_sn', phone: '+221770000000', amount: '10000', reference: 'demo-payout-8' });   // XOF
await sp.payouts.create({ method: 'orange_cm', phone: '+237690000000', amount: '15000', reference: 'demo-payout-9' }); // XAF

$sp->payouts->create(['method' => 'wave_sn', 'phone' => '+221770000000', 'amount' => '10000', 'reference' => 'demo-payout-8']);   // XOF
$sp->payouts->create(['method' => 'orange_cm', 'phone' => '+237690000000', 'amount' => '15000', 'reference' => 'demo-payout-9']); // XAF

sp.payouts.create(method="wave_sn", phone="+221770000000", amount="10000", reference="demo-payout-8")    # XOF
sp.payouts.create(method="orange_cm", phone="+237690000000", amount="15000", reference="demo-payout-9")  # XAF

curl https://soncopay.example/v1/payments/pay_3f9a5c0d21e4b7a6c8d1 -H "X-Api-Key: sp_test_…"

curl "https://soncopay.example/v1/payments?status=paid&limit=50" -H "X-Api-Key: sp_test_…"

# test mode
curl -X POST https://soncopay.example/v1/payments/pay_3f9a5c0d21e4b7a6c8d1/simulate -H "X-Api-Key: sp_test_…"

const p = await sp.payments.retrieve('pay_3f9a5c0d21e4b7a6c8d1');

const { items, has_more } = await sp.payments.list({ status: 'paid', limit: 50 });

await sp.payments.simulate(p.id);   // test mode

$p = $sp->payments->retrieve('pay_3f9a5c0d21e4b7a6c8d1');

$page = $sp->payments->list(['status' => 'paid', 'limit' => 50]);
$page['has_more'];

$sp->payments->simulate($p['id']);   // test mode

p = sp.payments.retrieve("pay_3f9a5c0d21e4b7a6c8d1")

page = sp.payments.list(status="paid", limit=50)
page["has_more"]

sp.payments.simulate(p["id"])   # test mode

curl https://soncopay.example/v1/balances -H "X-Api-Key: sp_test_…"

const { balances, reserved } = await sp.balances();

$b = $sp->balances();
$b['balances']; $b['reserved'];

b = sp.balances()
b["balances"], b["reserved"]

{
  "livemode": false,
  "balances": { "USDT": "124.5", "XOF": "35000" },
  "reserved": { "USDT": "51" }
}

curl "https://soncopay.example/v1/ledger?asset=USDT&limit=100" -H "X-Api-Key: sp_test_…"

const { items } = await sp.ledger.list({ asset: 'USDT', limit: 100 });
for await (const entry of sp.ledger.listAll({ asset: 'USDT' })) { … }

$page = $sp->ledger->list(['asset' => 'USDT', 'limit' => 100]);
foreach ($sp->ledger->listAll(['asset' => 'USDT']) as $entry) { … }

page = sp.ledger.list(asset="USDT", limit=100)
for entry in sp.ledger.list_all(asset="USDT"):
    …

curl https://soncopay.example/v1/fees -H "X-Api-Key: sp_test_…"

const fees = await sp.fees();

$fees = $sp->fees();

fees = sp.fees()

{
  "livemode": false,
  "payment": { "percent": "0.5", "fixed_usd": "0", "percent_source": "global", "fixed_source": "global" },
  "per_method": [ { "code": "orange_ci", "name": "Orange Money", "kind": "mobile_money", "percent": "1.5", … } ],
  "payout_fees": { "USDT:TRON": "1", … },
  "limits": { "min_payment_usd": 1, "min_payout_usd": 5 }
}

curl -X POST https://soncopay.example/v1/payouts \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "asset": "USDT", "network": "TRON", "amount": "150",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "reference": "withdraw-77" }'

const payout = await sp.payouts.create({
  asset: 'USDT', network: 'TRON', amount: '150',
  address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE', reference: 'withdraw-77',
});

$payout = $sp->payouts->create([
    'asset' => 'USDT', 'network' => 'TRON', 'amount' => '150',
    'address' => 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE', 'reference' => 'withdraw-77',
]);

payout = sp.payouts.create(
    asset="USDT", network="TRON", amount="150",
    address="TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", reference="withdraw-77",
)

curl https://soncopay.example/v1/payouts/po_8b2d… -H "X-Api-Key: sp_test_…"

curl https://soncopay.example/v1/payout-fees -H "X-Api-Key: sp_test_…"

const po = await sp.payouts.retrieve('po_8b2d…');
po.status; po.rail; po.tx_hash;

const { fees, min_payout_usd } = await sp.payouts.fees();

$po = $sp->payouts->retrieve('po_8b2d…');
$po['status'];

$fees = $sp->payouts->fees();

po = sp.payouts.retrieve("po_8b2d…")
po["status"]

fees = sp.payouts.fees()

# 1. save it: status 'pending_confirmation'
curl -X POST https://soncopay.example/v1/payout-destinations \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"crypto","asset":"USDT","network":"TRON","address":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE","label":"Treasury"}'

# 2. a team member confirms it in the dashboard (the password is asked again)
# 3. pay out to it once usable is true
curl -X POST https://soncopay.example/v1/payouts \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"destination_id":"pd_5c1e…","amount":"50","reference":"demo-payout-9"}'

// 1. save it: status 'pending_confirmation'
const dest = await sp.payoutDestinations.create({
  kind: 'crypto', asset: 'USDT', network: 'TRON',
  address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE', label: 'Treasury',
});
// 2. a team member confirms it in the dashboard (the password is asked again)
// 3. pay out to it once dest.usable is true
try {
  await sp.payouts.create({ destination_id: dest.id, amount: '50', reference: 'demo-payout-9' });
} catch (err) {
  if (err.code === 'destination_cooling_down') console.log(err.usableFrom);
  else throw err;
}

const { items, settings } = await sp.payoutDestinations.list({ status: 'active' });
await sp.payoutDestinations.update(dest.id, { label: 'Main wallet' });
await sp.payoutDestinations.disable(dest.id);

// mobile money destination: status 'pending_confirmation'
$dest = $sp->payoutDestinations->create([
    'kind' => 'mobile_money', 'method' => 'wave_sn',
    'phone' => '+221770000000', 'label' => 'Demo payouts',
]);
// confirmed in the dashboard, then:
try {
    $sp->payouts->create(['destination_id' => $dest['id'], 'amount' => '10000']);
} catch (ApiException $e) {
    if ($e->getErrorCode() === 'destination_cooling_down') {
        echo $e->getUsableFrom();
    }
}

$page = $sp->payoutDestinations->list(['kind' => 'mobile_money']);
$page['settings']['cooldown_hours'];
$sp->payoutDestinations->retrieve($dest['id']);

# bank account: status "pending_confirmation"
dest = sp.payout_destinations.create(
    kind="bank", holder="Demo Store", bank_name="Demo Bank",
    account_number="BJ0610100100144390000769", country="BJ", currency="XOF",
)
# confirmed in the dashboard, then:
try:
    payout = sp.payouts.create(destination_id=dest["id"], amount="50000")
    payout["status"]   # "awaiting_manual", then "completed" with bank_reference
except ApiError as e:
    if e.code == "destination_cooling_down":
        print(e.usable_from)

page = sp.payout_destinations.list(kind="bank")
sp.payout_destinations.disable(dest["id"])

{
  "id": "pd_5c1e…", "object": "payout_destination", "livemode": true,
  "kind": "mobile_money", "label": "Demo payouts", "currency": "XOF",
  "status": "active", "usable": false, "usable_from": "2026-10-03T09:00:00+00:00",
  "details": { "method_code": "wave_sn", "country": "SN", "phone_masked": "+221•••••000" },
  "created_via": "api", "confirmed_at": "2026-10-02T09:00:00+00:00", …
}

{
  "detail": "…",
  "code": "destination_cooling_down",
  "usable_from": "2026-10-03T09:00:00+00:00"
}

curl -X PUT https://soncopay.example/v1/settlement/routes \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"scope":"USDT","destination_id":"pd_3c1e…"}'

{
  "event": "payment.settled",
  "data": {
    "id": "pay_3f9a…", "status": "paid", "net_amount": "24.8886",
    "settlement": {
      "mode": "auto", "status": "settled",
      "payout_id": "po_7b2d…", "payout_amount": "23.8886",
      "payout_fee": "1", "asset": "USDT"
    }, …
  }
}

curl https://soncopay.example/v1/payouts/po_8b2d…/timeline -H "X-Api-Key: sp_test_…"
# or /v1/payments/{id}/timeline

const tl = await sp.payouts.timeline(payout.id);   // or sp.payments.timeline(payment.id)
for (const e of tl.events) console.log(e.occurred_at, e.step, e.status);

$tl = $sp->payouts->timeline($payout['id']);   // or $sp->payments->timeline($id)
foreach ($tl['events'] as $e) {
    echo $e['occurred_at'], ' ', $e['step'], PHP_EOL;
}

tl = sp.payouts.timeline(payout["id"])   # or sp.payments.timeline(payment_id)
for e in tl["events"]:
    print(e["occurred_at"], e["step"], e["status"])

{
  "object": "timeline",
  "subject": { "type": "payout", "id": "po_8b2d…", "status": "completed" },
  "livemode": true, "trace_id": "4f0c…",
  "events": [
    { "step": "requested", "label": "Payout requested", "status": "queued",
      "occurred_at": "2026-10-02T09:00:00+00:00", "data": { "amount": "50", "fee": "1", "asset": "USDT" } },
    { "step": "submitted", "label": "Sent for processing", "status": "submitting", … },
    { "step": "completed", "label": "Completed", "status": "completed", "data": { "tx_hash": "…" } }
  ]
}

curl "https://soncopay.example/v1/statements?currency=USDT&from=2026-10-01&to=2026-10-31" \
  -H "X-Api-Key: sp_test_…"

curl "https://soncopay.example/v1/statements.csv?currency=USDT&from=2026-10-01" \
  -H "X-Api-Key: sp_test_…" -o statement.csv

const st = await sp.statements.list({ currency: 'USDT', from: '2026-10-01', to: '2026-10-31' });
st.opening; st.closing;
for await (const line of sp.statements.listAll({ currency: 'USDT', from: '2026-10-01' })) {
  // follows next_cursor for you
}
const csv = await sp.statements.csv({ currency: 'USDT', from: '2026-10-01', to: '2026-10-31' });

$st = $sp->statements->list(['currency' => 'USDT', 'from' => '2026-10-01', 'to' => '2026-10-31']);
foreach ($sp->statements->listAll(['currency' => 'USDT']) as $line) {
    // follows next_cursor for you
}
$csv = $sp->statements->csv(['currency' => 'USDT', 'from' => '2026-10-01']);

st = sp.statements.list(currency="USDT", from_="2026-10-01", to="2026-10-31")
for line in sp.statements.list_all(currency="USDT", from_="2026-10-01"):
    pass   # follows next_cursor for you
csv = sp.statements.csv(currency="USDT", from_="2026-10-01", to="2026-10-31")

{
  "livemode": true, "currency": "USDT",
  "from": "2026-10-01T00:00:00+00:00", "to": "2026-11-01T00:00:00+00:00",
  "currencies": ["USDT"],
  "opening": { "USDT": "100" },
  "lines": [
    { "id": 5120, "date": "2026-10-02T09:12:40+00:00", "currency": "USDT",
      "type": "payment", "label": "Payment received", "description": null,
      "amount": "25.0137", "balance_after": "125.0137",
      "operation": { "type": "payment", "id": "pay_3f9a…" } },
    …
  ],
  "closing": { "USDT": "124.8886" },
  "next_cursor": null
}

curl -X POST https://soncopay.example/v1/invoices \
  -H "X-Api-Key: sp_test_…" \
  -H "Idempotency-Key: demo-invoice-1042" \
  -H "Content-Type: application/json" \
  -d '{"customer":{"name":"Demo Customer","email":"[email protected]","phone":"+2250700000000",
        "consent":{"email":true,"sms":true}},"currency":"XOF","due_days":7,
       "lines":[{"description":"Demo service","quantity":1,"unit_amount":"15000"}],"send":true}'

const invoice = await sp.invoices.create({
  customer: { name: 'Demo Customer', email: '[email protected]', phone: '+2250700000000' },
  currency: 'XOF', due_days: 7, send: true,
  lines: [{ description: 'Demo service', quantity: 1, unit_amount: '15000' }],
}, { idempotencyKey: 'demo-invoice-1042' });
invoice.hosted_url;

$invoice = $sp->invoices->create([
    'customer' => ['name' => 'Demo Customer', 'email' => '[email protected]'],
    'currency' => 'XOF', 'due_days' => 7, 'send' => true,
    'lines' => [['description' => 'Demo service', 'quantity' => 1, 'unit_amount' => '15000']],
], ['idempotency_key' => 'demo-invoice-1042']);
$invoice['hosted_url'];

invoice = sp.invoices.create(
    customer={"name": "Demo Customer", "email": "[email protected]"},
    currency="XOF", due_days=7, send=True,
    lines=[{"description": "Demo service", "quantity": 1, "unit_amount": "15000"}],
    idempotency_key="demo-invoice-1042",
)
invoice["hosted_url"]

curl -X POST https://soncopay.example/v1/subscriptions \
  -H "X-Api-Key: sp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_…","description":"Demo monthly plan","amount":"10000","currency":"XOF",
       "interval":"month","preferred_method":"mobile_money","reminders":{"days_before":[7,3,1]},
       "dunning":{"grace_days":7,"action":"pause"}}'

const sub = await sp.subscriptions.create({
  customer_id: customer.id, description: 'Demo monthly plan', amount: '10000', currency: 'XOF',
  interval: 'month', preferred_method: 'mobile_money',
  reminders: { days_before: [7, 3, 1] }, dunning: { grace_days: 7, action: 'pause' },
});
await sp.billing.advanceTestClock({ advance_days: 30 }); // test mode

$sub = $sp->subscriptions->create([
    'customer_id' => $customer['id'], 'description' => 'Demo monthly plan',
    'amount' => '10000', 'currency' => 'XOF', 'interval' => 'month',
    'reminders' => ['days_before' => [7, 3, 1]], 'dunning' => ['grace_days' => 7, 'action' => 'pause'],
]);

sub = sp.subscriptions.create(
    customer_id=customer["id"], description="Demo monthly plan", amount=10000, currency="XOF",
    interval="month", reminders={"days_before": [7, 3, 1]}, dunning={"grace_days": 7, "action": "pause"},
)
sp.billing.advance_test_clock(days=30)  # test mode

{
  "event": "payment.paid",
  "created_at": "2026-10-01T14:31:07+00:00",
  "data": {
    "id": "pay_3f9a…", "order_id": "1042", "status": "paid",
    "received_amount": "25.0137", "asset": "USDT",
    "fee": "0.1251", "net_amount": "24.8886",
    "payer": { "email": "[email protected]" },
    "settlement": { "mode": "custody", "status": null, "payout_id": null },
    "late": false, …
  }
}

const crypto = require("crypto");
const expected = crypto.createHmac("sha512", process.env.SP_WEBHOOK_SECRET).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-soncopay-signature"] || ""));

$expected = hash_hmac('sha512', file_get_contents('php://input'), getenv('SP_WEBHOOK_SECRET'));
$ok = hash_equals($expected, $_SERVER['HTTP_X_SONCOPAY_SIGNATURE'] ?? '');

import hmac, hashlib
expected = hmac.new(secret.encode(), raw_body, hashlib.sha512).hexdigest()
ok = hmac.compare_digest(expected, request.headers.get("X-SoncoPay-Signature", ""))

{
  "detail": "…",
  "code": "kyb_required"
}