# Payments and expenses via the API: customer payment, refund, expenses

URL: https://bimpsoft.com/en/help/developers/payments-via-api/
Updated: 2026-11-06

> A Customer payment is created by customerPayment/api-create with paymentDetails, which ties the amount to a Customer order. A Customer refund is refundToCustomer/api-create, other expenses are otherExpenses/api-create, and a transfer between accounts is interaccountTransfer/api-create. The cash desk or bank account is set in the paymentEntity field.

## What we are building

Passing cash transactions from your system to Bimp: online customer payments, refunds, expenses, and transfers between a cash desk and an account. The business logic of payments is described in [Customer payment](https://bimpsoft.com/en/help/sales/customer-payment/) and [Customer refund](https://bimpsoft.com/en/help/sales/customer-refund/). Supplier payments are covered in [Purchasing via the API](https://bimpsoft.com/en/help/developers/purchasing-via-api/). The company token is passed in the `access-token` header ([Getting started with the API](https://bimpsoft.com/en/help/developers/api-getting-started/)).

## Which methods to call and in what order

| Step | Method | Why |
|---|---|---|
| 1 | [`bankAccounts/api-readList`](/en/help/developers/api-reference/bank-accounts/#api-read-list) and [`cashRegistry/api-readList`](/en/help/developers/api-reference/cash-registry/#api-read-list) | Get the `uuid` of accounts and cash desks; these are the values of the `paymentEntity` field |
| 2 | [`currency/api-readList`](/en/help/developers/api-reference/currency/#api-read-list) | Get the `uuid` of the document currency |
| 3 | [`invoiceForCustomerPayment/api-readByExternalId`](/en/help/developers/api-reference/invoice-for-customer-payment/#api-read-by-external-id) | Find the Customer order being paid ([Order sync](https://bimpsoft.com/en/help/developers/sync-orders/)) |
| 4 | [`customerPayment/api-create`](/en/help/developers/api-reference/customer-payment/#api-create) | Create a Customer payment for the order |
| 5 | `customerPayment/api-readList` | Check whether the payment already exists (the `orders` filter) |
| 6 | [`refundToCustomer/api-create`](/en/help/developers/api-reference/refund-to-customer/#api-create) | Refund money to the customer |
| 7 | [`otherExpenses/api-create`](/en/help/developers/api-reference/other-expenses/#api-create) | Record an expense (acquiring fee, delivery and so on) |
| 8 | [`interaccountTransfer/api-create`](/en/help/developers/api-reference/interaccount-transfer/#api-create) | Transfer money between cash desks and accounts |
| 9 | `customerPayment/api-cancel` | Cancel an erroneous payment |

## How to create a Customer payment

`customerPayment/api-create` requires the customer `counterparty` and the currency `currency`. The link to the order is set by the `paymentDetails` array: each element contains `invoiceForCustomerpayment` (the [Customer order](https://bimpsoft.com/en/help/sales/customer-order/) uuid; note the spelling of the field, with a lowercase `p`) and `payed` (the amount). The cash desk or account is specified by `paymentEntity`.

```bash
curl -X POST https://app.bimpsoft.com/org2/customerPayment/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "<buyer-uuid>",
    "currency": "<uah-currency-uuid>",
    "organization": "<organization-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "date": "2026-11-06T10:40:00",
    "number": "myshop-10452",
    "comment": "Оплата карткою, замовлення myshop №10452",
    "commission": 62,
    "paymentDetails": [
      { "invoiceForCustomerpayment": "<order-uuid>", "payed": 12400 }
    ]
  }'
```

Response: `{ "success": true, "data": { "uuid": "<payment-uuid>" } }`.

The `commission` field is the payment system fee; `calculationRate` (in a `paymentDetails` element) is the cross rate if the payment currency differs from the order currency ([One payment for several orders in different currencies](https://bimpsoft.com/en/help/sales/multi-currency-payment-allocation/)). After saving, the order's `sumPayed` increases and the amount remaining to be paid decreases.

**Paying several orders with one payment.** Add elements to `paymentDetails`:

```json
"paymentDetails": [
  { "invoiceForCustomerpayment": "<order-1-uuid>", "payed": 5000 },
  { "invoiceForCustomerpayment": "<order-2-uuid>", "payed": 7400 }
]
```

**Advances and overpayments.** The rules for accounting for advances and overpayments are described in Customer payment, advances and overpayments.

## How to change or cancel a payment

`customerPayment/api-update` takes `uuid` and the fields to change (`number`, `comment`, `date`, `paymentEntity`, `commission`, `currency`, `paymentDetails`). `customerPayment/api-cancel` with `uuid` cancels the document. Payment statuses are returned by `customerPayment/api-readStatuses`.

## How to avoid duplicate payments

The specification has no external ID methods for payments, so protect yourself like this:

1. Pass your payment system's payment ID in the document's `number` or `comment`.
2. Before creating a payment, call `customerPayment/api-readList` with the filter `orders: ["<order-uuid>"]` and a period in `periodable`. If a payment with that `number` already exists, do not create one.
3. Create a payment only after your payment system confirms it, not when the order is placed.
4. Keep a "payment ID, Bimp payment `uuid`" pair in your own database.

Find the order the payment belongs to by external ID, not by document number: [External IDs](https://bimpsoft.com/en/help/developers/api-external-ids/).

## How to refund money to a customer

`refundToCustomer/api-create` requires: `expenseItem` ([expense item](https://bimpsoft.com/en/help/getting-started/income-and-expense-items/)), `customer`, `organization`, `paymentEntity`, `author` and a `paymentDetails` array with `invoice` (the Customer order) and `refundSum` elements. Expense items are available from [`expenseItems/api-readList`](/en/help/developers/api-reference/expense-items/#api-read-list).

```bash
curl -X POST https://app.bimpsoft.com/org2/refundToCustomer/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expenseItem": "<expense-item-uuid>",
    "customer": "<buyer-uuid>",
    "organization": "<organization-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "author": "<employee-uuid>",
    "documentSum": 3100,
    "paymentDetails": [ { "invoice": "<order-uuid>", "refundSum": 3100 } ]
  }'
```

A Customer return of goods is a separate document ([`customer-inventories-return/api-create`](/en/help/developers/api-reference/customer-inventories-return/#api-create)), while the money refund is recorded with `refundToCustomer`. Both steps are described in [Customer return](https://bimpsoft.com/en/help/sales/customer-return/) and Customer refund.

## How to record an expense or income

`otherExpenses/api-create` records an expense not related to purchasing goods: `organization`, `expenseItem` and `paymentEntity` are required, and in `paymentDetails` each row needs `sum`, `project`, `lineOfBusiness`, `expenseItem` (and, if needed, `invoiceForCustomerPayment` to assign the expense to an order).

```bash
curl -X POST https://app.bimpsoft.com/org2/otherExpenses/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<organization-uuid>",
    "expenseItem": "<expense-item-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "date": "2026-11-06T11:00:00",
    "comment": "Комісія еквайрингу за 05.11",
    "paymentDetails": [
      {
        "sum": 186,
        "expenseItem": "<expense-item-uuid>",
        "project": "<project-uuid>",
        "lineOfBusiness": "<line-of-business-uuid>"
      }
    ]
  }'
```

Similarly, `otherIncome/api-create` records other income (`incomeItem`; income items are in [`incomeItems/api-readList`](/en/help/developers/api-reference/income-items/#api-read-list)). For expense accounting rules, see [Period expenses, taxes and other expenses](https://bimpsoft.com/en/help/finance/period-expenses/). An expense request (a payment plan) is created by [`expenseRequest/api-create`](/en/help/developers/api-reference/expense-request/#api-create).

## How to transfer money between accounts

`interaccountTransfer/api-create` requires `organization`, `paymentEntitySender`, `paymentEntityRecipient`, `sum`, `project` and `lineOfBusiness`. For a [transfer between accounts](https://bimpsoft.com/en/help/finance/transfers/) in different currencies, add `currency`, `purchaseCurrency`, `rate` and `amountToCredit`. Balances in accounts and cash desks are returned by [`financing-balance/api-readList`](/en/help/developers/api-reference/financing-balance/#api-read-list); see [Cash balance in accounts and cash desks](https://bimpsoft.com/en/help/reports/cash-balance-report/).

## Webhooks and polling

There is no separate webhook for payments: the webhook types are `inventory_balance`, `product_upsert` and `order_status` ([Webhooks](https://bimpsoft.com/en/help/developers/webhooks/)). Your system is notified of a payment change by the `order_status` event if the [order status](https://bimpsoft.com/en/help/sales/order-statuses/) changes on payment and the event body contains `sumPayed`. Otherwise, call `customerPayment/api-readList` every few minutes with the `periodable` period and the `orders` filter.

## Common errors

**The payment was created, but the order is not marked as paid.** Cause: `invoiceForCustomerpayment` is not specified in `paymentDetails`, or a different order is specified. Solution: check the spelling of the field and the uuid; note that the field is called `invoiceForCustomerpayment`, not `invoiceForCustomerPayment`.

**A `currency` validation error.** Cause: a currency code (`UAH`) was passed instead of a uuid. Solution: take the uuid from `currency/api-readList`.

**`paymentEntity` not found.** Cause: the uuid of an account of another organization was passed, or it is not a uuid. Solution: use the `uuid` from `bankAccounts/api-readList` or `cashRegistry/api-readList`.

**A double payment after a repeated request.** Cause: `api-create` was repeated without a check. Solution: the rules in the section "How to avoid duplicate payments"; cancel the extra payment with `customerPayment/api-cancel`.

**Error 429.** The request limit was exceeded, see [Limits](https://bimpsoft.com/en/help/developers/api-limits/).

## FAQ

**How do I record an online store payment in Bimp?**

Call customerPayment/api-create: specify the customer, the currency, paymentEntity (cash desk or account) and, in paymentDetails, the Customer order uuid and the payed amount.

**Where do I get paymentEntity?**

It is the uuid of your company's bank account (bankAccounts/api-readList) or cash desk (cashRegistry/api-readList).

**Can one payment close several orders?**

Yes. In paymentDetails add a separate element with invoiceForCustomerpayment and payed for each order.

**How do I cancel a payment?**

Call customerPayment/api-cancel with the payment uuid. For a Supplier payment, use paymentToSupplier/api-cancel.