Cutelia Payments API

Stripe-style REST API for accepting local Caribbean bank payments (MCB / BDC / APC / Orco via Sentoo). Base URL: https://cutelia.org

Authentication

Every request must include an Authorization: Bearer header with your secret key.

Authorization: Bearer sk_live_...

Test keys (sk_test_...) route to Sentoo mock mode. Live keys (sk_live_...) hit real banks once activated.

Create a checkout session

curl -X POST https://cutelia.org/api/public/v1/checkout-sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{
    "amount": 4500,
    "currency": "XCG",
    "description": "Order #12345",
    "customer_email": "buyer@example.com",
    "success_url": "https://plaza-karibe.com/checkout/success",
    "cancel_url": "https://plaza-karibe.com/checkout/cancel",
    "metadata": {"order_id": "12345"}
  }'

Response includes a url — redirect the customer there. Amounts are integer cents (XCG · 100).

Retrieve a payment

curl https://cutelia.org/api/public/v1/payments/pay_... \
  -H "Authorization: Bearer sk_test_..."

Webhooks

Register a webhook endpoint from the admin dashboard. We send POST requests with a Cutelia-Signature header:

Cutelia-Signature: t=1730000000,v1=<hex_hmac_sha256>

signed_payload = "{timestamp}.{raw_json_body}"
signature       = HMAC_SHA256(signing_secret, signed_payload)

Events emitted:

  • checkout.session.completed
  • payment.succeeded
  • payment.failed
  • payment.cancelled

Retry schedule: 1m, 5m, 30m, 2h, 12h, 24h. We give up after 6 attempts and mark the delivery as failed.

Errors

{"error": {"message": "Invalid API key", "code": "error"}}