# Leapa API

One HTTPS endpoint for what the dashboard does: customers, invoices, BurundiPay, payouts and refunds.

The Leapa API is how your own software does what you would otherwise do by hand in the dashboard. It creates customers, issues invoices, collects over BurundiPay, sends payouts and refunds, and reads back everything that happened.

It is a REST API. Resources have predictable URLs, requests and responses are JSON, and the answer to every request is a standard HTTP status code.

<Callout type="danger" title="Card numbers never come to your server">
	Nothing in this reference accepts a card number, a security code or an
	expiry date, and that is deliberate. Handling those puts your servers inside
	the scope of PCI DSS, the card industry's security standard, which is a
	compliance programme rather than a feature you add. The [payment
	widget](/docs/widgets/integration) collects the card in the payer's own
	browser, sends it straight to Leapa, and hands you back a `source_id` you
	can safely store and reuse.
</Callout>

## The two servers

Leapa runs one API in two places. They are separate worlds: an account, a customer or an invoice created on one does not exist on the other.

| Environment | Base URL | What it moves |
| --- | --- | --- |
| Production | `https://api.leapa.co/v2` | Real money |
| Development | `https://dev.api.leapa.co/v2` | Nothing. Test cards and test balances only |

Build against development. Every example in this reference names the production host, so change the host, not the path, when you are testing.

`v2` is the version of the API. It is part of the base URL rather than of each path, so a path in this reference reads `/customers` and the request goes to `https://api.leapa.co/v2/customers`. The version changes only when a change would break existing callers, and this reference always documents the current one.

<Callout type="warning" title="A key belongs to one server">
	A key issued for development is rejected by production, and the reverse. If
	a request that worked yesterday starts answering `401`, check the host
	before you check the key.
</Callout>

## What a request looks like

Four things, every time:

1. The method and the URL, which the endpoint page states at the top.
2. Your API key, as a bearer token. See [Authentication](/docs/api/authentication).
3. `Content-Type: application/json`, when you are sending a body.
4. The body itself, as JSON.

```bash
curl -X GET "https://api.leapa.co/v2/customers" \
  -H "Authorization: Bearer $LEAPA_API_KEY" \
  -H "Accept: application/json"
```

## What an answer looks like

A `2xx` status and the resource, as JSON. Anything from `400` up is an error in one fixed shape, described in [Errors](/docs/api/errors).

## Where to start

If you are collecting money in Burundi, start with [BurundiPay](/docs/api/burundipay/request-payment): it is the rail most Burundian payers already have on their phone, and it settles against an invoice.

If you are billing, the order is [create a customer](/docs/api/customers/create), [create an invoice](/docs/api/invoices/create), then [send it](/docs/api/invoices/send).

If you are taking cards, put the [payment widget](/docs/widgets/integration) on your page. It is a single HTML element, it talks to this same API, and it is the only supported way to reach a card. Once it has saved one, [pay an invoice with that saved card](/docs/api/invoices/pay-with-saved-card) from your own server.

---

_Generated from the Leapa documentation at leapa.co/docs._