---
title: "Prepare a top-up and return the hosted payment link"
method: POST
path: "/credits/topup"
tags: ["Credits"]
---

# Prepare a top-up and return the hosted payment link

`POST /credits/topup`

## Request

- Base URL: `https://api.epovest.com/v1`
- URL: `https://api.epovest.com/v1/credits/topup`
- Auth: HTTP bearer

Emits the top-up invoice and returns the hosted payment page: nothing is charged by the call
itself. Hand `payment_url` to the person; they approve the amount there, and once they pay,
the balance updates on its own and the trackers that ran out of credit resume. The amount
goes in one of two units, one per speaker: send exactly one of them, and a key set to `null`
counts as absent. Amounts are always in the wallet currency of the account, which `GET
/credits` gives. The response echoes the amount in both units. Owner only.

## Request body

- object
  - `amount` union: Major units of the wallet currency: `50` means 50.00, `12.5` means 12.50. Use it when the person names the amount, and pass exactly the number they said.
    - number
    - string
  - `amount_minor` integer, nullable: Minor units: `5000` means 50.00. Use it when the person leaves the amount to you: take one of the `suggested_topups[]` of `GET /credits` and pass its `amount_minor`.

## Response `200`

The hosted payment page, and the amount in both units.

- object
  - `payment_url` string, uri, required
  - `amount` string, required: The amount in major units.
  - `amount_minor` integer, required
  - `currency` string, required: The wallet currency, upper case.

## Other responses

- `400`: `bad_request`: malformed body or parameter; the message says what.
- `401`: `unauthenticated`: missing, unknown or revoked key.
- `403`: `insufficient_scope`: the credential may not do this, either because the key lacks the scope, or, on a one-click connection, because the person lacks the role the action needs (manager, or owner to start, pause and top up). On that path, read it as "this person may not do this" and tell them which role the action needs.
- `409`: `email_unverified` (the account owner verifies their email in the app first) or `no_billing_contact` (the account has no owner to bill).
- `422`: `below_min_topup`: the amount is under the floor, given back as `min_topup` and `min_topup_minor`.
- `429`: `rate_limited`: 120 requests per minute per credential, sliding window. Retry after `Retry-After` seconds.
- `503`: `service_unavailable`: a backend is unreachable; retry later.

---

[API](https://skmtc.dev/epovest/apis/epovest-api.md) · [All operations](https://skmtc.dev/epovest/apis/epovest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/epovest/apis/epovest-api/revisions/7a78ee27ecbb?raw)