# Libraries

Part of the Orboni API reference: https://orboni.com/docs. This page: https://orboni.com/docs/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.

| Language | Install | Needs | Source |
| --- | --- | --- | --- |
| Node.js, TypeScript | `npm install orboni` | Node.js 20 or later; also Deno, Bun and edge runtimes | https://github.com/orboni/orboni-node |
| PHP | `composer require orboni/orboni-php` | PHP 8.1 or later, with curl and json | https://github.com/orboni/orboni-php |
| Python | `pip install orboni` | Python 3.9 or later | https://github.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.

```javascript
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);
```

```php
$orboni = new \Orboni\OrboniClient(getenv('ORBONI_SECRET_KEY'));

$session = $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',
], ['idempotency_key' => 'order_1042']);

header('Location: '.$session->url, true, 303);
```

```python
import os
import orboni

client = orboni.Orboni(os.environ["ORBONI_SECRET_KEY"])

session = client.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",
    idempotency_key="order_1042",
)

return 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.

```javascript
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);
});
```

```php
try {
    $event = \Orboni\Webhook::constructEvent(
        file_get_contents('php://input'),
        $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? null,
        getenv('ORBONI_WEBHOOK_SECRET'),
    );
} catch (\Orboni\Exception\SignatureVerificationException $e) {
    http_response_code(400);
    exit($e->getMessage());
}

if ($event->type === 'checkout.session.completed') {
    // fulfil $event->data->object->client_reference_id, once
}
http_response_code(200);
```

```python
@app.post("/webhooks/orboni")
def orboni_webhook():
    try:
        event = orboni.Webhook.construct_event(
            request.get_data(),
            request.headers.get("Webhook-Signature"),
            os.environ["ORBONI_WEBHOOK_SECRET"],
        )
    except orboni.SignatureVerificationError as e:
        return str(e), 400

    if event.type == "checkout.session.completed":
        pass  # fulfil event.data.object.client_reference_id, once
    return "", 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

| type | Node and Python | PHP |
| --- | --- | --- |
| `invalid_request_error` | `InvalidRequestError` | `InvalidRequestException` |
| `amount_too_small` | `AmountTooSmallError` | `AmountTooSmallException` |
| `idempotency_error` | `IdempotencyError` | `IdempotencyException` |
| `authentication_error` | `AuthenticationError` | `AuthenticationException` |
| `permission_error` | `PermissionError` | `PermissionException` |
| `receiving_frozen` | `ReceivingFrozenError` | `ReceivingFrozenException` |
| `account_past_due` | `AccountPastDueError` | `AccountPastDueException` |
| `rate_limit_error` | `RateLimitError` | `RateLimitException` |
| `rate_unavailable` | `RateUnavailableError` | `RateUnavailableException` |
| `api_error` | `APIError` | `ApiException` |
| no answer | `ConnectionError` (Python: `APIConnectionError`) | `ConnectionException` |
| a webhook that fails | `SignatureVerificationError` | `SignatureVerificationException` |

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, https://orboni.com/docs#errors.

## Another language

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