API reference

Libraries

Orboni’s own libraries call the API for you: every operation, with retries that never create a payment twice, paging, an error class for each error type, and webhook verification. They have no dependencies and are free, under the MIT license.

LanguageInstallNeedsSource
Node.js, TypeScriptnpm install orboniNode.js 20 or later; also Deno, Bun and edge runtimesgithub.com/orboni/orboni-node
PHPcomposer require orboni/orboni-phpPHP 8.1 or later, with curl and jsongithub.com/orboni/orboni-php
Pythonpip install orboniPython 3.9 or latergithub.com/orboni/orboni-python

Take a payment

Make a checkout session on your server with your secret key and send the buyer to its url. Amounts are in the currency’s smallest unit: cents, or whole yen.

import Orboni from 'orboni';

const orboni = new Orboni(process.env.ORBONI_SECRET_KEY);

const session = await orboni.checkout.sessions.create(
  {
    amount: 2490, // $24.90
    currency: 'usd',
    client_reference_id: 'order_1042',
    success_url: 'https://shop.example/thanks',
    cancel_url: 'https://shop.example/cart',
  },
  { idempotencyKey: 'order_1042' },
);

res.redirect(session.url);

Verify a webhook

Pass the request’s body exactly as it arrived, the Webhook-Signature header and your endpoint’s signing secret (whsec_…). You get the event, or an error to answer with 400. While you roll a secret, pass both.

app.post('/webhooks/orboni', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = await orboni.webhooks.constructEvent(
      req.body,
      req.headers['webhook-signature'],
      process.env.ORBONI_WEBHOOK_SECRET,
    );
  } catch (error) {
    return res.status(400).send(error.message);
  }
  if (event.type === 'checkout.session.completed') {
    // fulfil event.data.object.client_reference_id, once
  }
  res.sendStatus(200);
});

What they do for you

  • Every POST carries an Idempotency-Key: yours when you give one (an order ID is a good one), else one the library makes. A retry, the library’s or yours, never makes a second session or refund.
  • A network failure, a timeout, 409, 429 and 5xx are tried again, twice by default: after Retry-After when the answer has one, else after half a second, one, two… Another 4xx is not.
  • A refused call is an error of the class named after its type, with the param at fault and the HTTP status. Branch on the class or the type, never on the message.
  • A list call answers one page, and can walk every page for you: by starting_after while has_more, or backwards from ending_before.
  • Webhook verification checks the time (five minutes either way by default), compares in constant time, takes several secrets while one is rolled, and needs no API key.
  • The answers are the API’s objects, field for field: what the API reference says of a field holds in every library.

Errors

typeNode and PythonPHP
invalid_request_errorInvalidRequestErrorInvalidRequestException
amount_too_smallAmountTooSmallErrorAmountTooSmallException
idempotency_errorIdempotencyErrorIdempotencyException
authentication_errorAuthenticationErrorAuthenticationException
permission_errorPermissionErrorPermissionException
receiving_frozenReceivingFrozenErrorReceivingFrozenException
account_past_dueAccountPastDueErrorAccountPastDueException
rate_limit_errorRateLimitErrorRateLimitException
rate_unavailableRateUnavailableErrorRateUnavailableException
api_errorAPIErrorApiException
no answerConnectionError (Python: APIConnectionError)ConnectionException
a webhook that failsSignatureVerificationErrorSignatureVerificationException

Each is a subclass of the library’s base class: OrboniError in Node and Python, Orboni\Exception\OrboniException in PHP. What each type means: Errors in the API reference.

Another language

The API is plain HTTPS and JSON in Stripe’s shape, so any HTTP client works: the Quick start shows it in cURL, PHP, Node, Python, Ruby, Go, Java and C#, and Webhooks how to check a signature in all of them but cURL. The API is also described as OpenAPI 3.1 at /openapi.json, built from the code, for a client generator or an AI assistant.

This page as Markdown, for a program or an AI assistant: /docs/libraries.md. Something missing or unclear? Write to us from the dashboard’s Help & Support.