> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner prepaid balance

> Check your partner balance, pay for a booking, and handle insufficient funds and refunds through the REST API.

The partner balance is a prepaid balance belonging to your partner account. It uses Stripe Treasury underneath once live. On dev, it uses a stub ledger: no Stripe call is made and no real money moves.

> [!NOTE]
>
> This is a dev/local preview of the public API 0.88.0 contract, available only to enabled partners. Funding, commission credits and withdrawals are not yet available. Sandbox and production remain disabled until launch.

Balance payments are **REST-only**. They are not offered through the MCP servers or the CLI.

## Check the balance

Use your tenant-bound API key to read your partner's balance:

```bash theme={null}
curl 'https://api.dev.gojinko.com/v1/balance' \
  --header 'X-API-Key: <TENANT_BOOKING_KEY>'
```

`GET /v1/balance` returns:

| Field | Meaning |
| - | - |
| `available_money` | The money available to pay for bookings. |
| `pending_debits_money` | Money in pending debits. |
| `funding_instructions` | Funding information for the account. In dev, this describes the stub; it does not provide a live funding facility. |

The dev stub's initial balance is configured by the operator. A partner without an initial credit has no funds to spend. Reading a balance does not reserve it for a booking; another payment can spend it before you submit.

## Pay for a booking

Prepare a trip with its selected items and travelers, then call `POST /v1/checkout` with its `trip_id`. See [Trips and checkout](https://docs.dev.gojinko.com/guides/trips-and-checkout.md).

Use the returned `quote_id`. Submit a balance payment only when checkout's `accepted_payment_types` includes `type: "balance"`. Discovery lists it only when the feature is enabled, your partner is entitled and the quote currency matches the balance currency. Read discovery on each checkout; do not cache it.

Send the typed payment to the public API with an `Idempotency-Key`:

```bash theme={null}
curl --request POST 'https://api.dev.gojinko.com/v1/agent_payment/submit' \
  --header 'X-API-Key: <TENANT_BOOKING_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_ATTEMPT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "trip_id": "<TRIP_ID>",
    "quote_id": "<QUOTE_ID>",
    "payment": {"type": "balance"}
  }'
```

The `payment` object needs only `type: "balance"`; no card or shared payment token is required. A posted debit produces `payment_status: "authorized"`, then fulfillment proceeds as for other payments. Authorization alone does not mean the booking is confirmed.

The answer is the same payment outcome as for every typed payment: read it and follow its `recovery.action` as described in [Payment outcomes and retries](https://docs.dev.gojinko.com/guides/payment-outcomes.md), including how to retry with the same `Idempotency-Key` after a timeout. Read `GET /v1/trip/{trip_id}` for the booking status. A competing submission after an attempt has already been debited returns 409.

## Insufficient balance

`INSUFFICIENT_BALANCE` (HTTP 403) means the available balance cannot cover the quote. The payment is refused before acceptance, with `recovery.action: "stop"`.

Fund the balance or pay another way using an available checkout payment method. **Do not retry with a new key to bypass this refusal.** Funding is not yet available in this slice; on dev, the operator configures the stub's initial credit. Replaying the same key returns the original result.

See [Payment outcome codes](https://docs.dev.gojinko.com/concepts/errors.md#payment-outcome-codes) for the other codes a balance payment can return.

## Cancellations and refunds

When a balance-paid booking is cancelled and refunded, the refund credits the balance back. It does not issue a Stripe card refund. Follow the booking's cancellation and refund status, then check `GET /v1/balance` to see the restored funds. A cancellation request alone is not proof that the refund has completed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.