---
updatedAt: 2026-09-23T02:34:54.000Z
agentTools:
  projectIndex: https://docs.kyshi.co/llms.txt
---

# Transactions

`kyshi.transactions` creates and inspects one-time collections. For when to use each flow, see the [Transactions](transactions) guide.

# Methods

| Method                         | Endpoint                                  |
| :----------------------------- | :---------------------------------------- |
| `initialize(params, options?)` | `POST /v1/transactions/initialize`        |
| `charge(params, options?)`     | `POST /v1/transactions/charge`            |
| `verify(reference, options?)`  | `GET /v1/transactions/verify/{reference}` |
| `retrieve(id, options?)`       | `GET /v1/transactions/history/{id}`       |
| `list(params?, options?)`      | `GET /v1/transactions/history`            |

# Hosted Checkout

```ts
const checkout = await kyshi.transactions.initialize({
  email: 'customer@example.com',
  amount: 1000,
  localCurrency: 'NGN',
  amountCurrency: 'local',
  reference: 'ORDER-10001',
  redirectUrl: 'https://merchant.example.com/payments/callback',
});

console.log(checkout.authorizationUrl);
```

Be deliberate about `amountCurrency`. It defaults to `settlement`, so sending `1000` meaning Naira while relying on the default charges roughly 1500× too much. See [Countries And Currencies](countries-and-currencies).

# Bank Transfer Charge

```ts
const charge = await kyshi.transactions.charge({
  email: 'customer@example.com',
  amount: 5000,
  localCurrency: 'NGN',
  amountCurrency: 'local',
  reference: 'ORDER-10002',
  chargeType: 'BANK_TRANSFER',
});
```

The customer types the amount themselves, so underpayment and overpayment are possible. See [Virtual Accounts](virtual-accounts).

# Verify Before Giving Value

```ts
const transaction = await kyshi.transactions.verify('ORDER-10001');

if (transaction.status === 'SUCCESS') {
  await fulfilOnce('ORDER-10001');   // idempotent
}
```

This is the only signal you should release goods on. The checkout redirect is a UI event, not proof of payment.

Note `transaction.status` is the transaction state (`SUCCESS`, `PENDING`, `FAILED`, `IN_REVIEW`, `REVERSAL`, `COLLECTED`) — not a boolean. See [Statuses And Lifecycles](statuses).

# Reconcile

```ts
const history = await kyshi.transactions.list({ page: 1, limit: 50 });
const one = await kyshi.transactions.retrieve('transaction-id');
```

Filter to a closed time range when reconciling. The default order is newest first, so paging through live data can shift rows between pages.

# Next

* [Transactions guide](transactions) — flows, failure handling, reconciliation
* [Configuration](configuration) — retries and idempotency