IdealBoxPay

Documentation

Take your first payment.

Everything below is the real contract: the routes, the statuses, the failure codes, and the rules a correct integration follows.

How it works

A hosted checkout is a payment link made for one order. Your server creates it and redirects the customer; the page does the rest.

  1. Your server calls POST /v1/payment_links with the amount and your order reference, using a secret key or a restricted key with billing.links.manage.
  2. It redirects the customer to the url in the response.
  3. The customer picks a method and pays. The page handles the phone prompt, the provider’s page and the wait.
  4. You receive payment_intent.succeeded with your reference, and fulfil the order.

Create a checkout

amount, currency and title are required. reference is your order id and comes back on every payment made through the checkout. A checkout takes one payment and closes, unless you send singleUse: false. Limit the methods offered with paymentMethods, set an expiry with expiresAt, and send the payer back to your site with successUrl.

curl https://secure.idealbox.org/v1/payment_links \
  -H "Authorization: Bearer ib_sk_test_4f2a9c1e8b7d6053" \
  -H "Idempotency-Key: order-4471-checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500000",
    "currency": "XAF",
    "title": "Order #4471",
    "reference": "order-4471",
    "successUrl": "https://shop.example.com/orders/4471/thanks",
    "metadata": { "cartId": "c_9" }
  }'

Send the customer to it

Redirect to url, or put it behind a button or in a message. The page shows your business name, logo and colour, then the methods that can take this amount right now.

Know when it is paid

Each attempt is an ordinary payment, so the outcome arrives as payment_intent.succeeded or payment_intent.failed, with your reference and the checkout’s metadata on it.

// The webhook, not the redirect, is what says the order is paid.
// A payer can close the tab before the redirect; the webhook still arrives.
if (event.type === 'payment_intent.succeeded') {
  const payment = event.data.object;
  await orders.markPaid(payment.reference, {   // the reference you sent
    paymentId: payment.id,
    amount: payment.amount,
  });
}

Check or close a checkout

Retrieve a checkout to see its status and the payments made through it. Close it if the order is cancelled before it is paid; a payment already under way still completes.

curl https://secure.idealbox.org/v1/payment_links/plink_01JAY9W3K8TQ2M5ZB7XF4RC6VD \
  -H "Authorization: Bearer ib_sk_test_4f2a9c1e8b7d6053"