# Оплати і витрати через API: оплата покупця, повернення, витрати

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

> Оплату від покупця створює customerPayment/api-create з paymentDetails, що прив'язує суму до замовлення покупця. Повернення коштів покупцю — refundToCustomer/api-create, інші витрати — otherExpenses/api-create, переказ між рахунками — interaccountTransfer/api-create. Касу або банківський рахунок вказують у полі paymentEntity.

## Що будуємо

Передавання грошових операцій з вашої системи в Bimp: онлайн-оплати покупців, повернення коштів, витрати, [переказ](https://bimpsoft.com/help/finance/transfers/) між касою і рахунком. Бізнес-логіка оплат описана в статтях [Оплата від покупця](https://bimpsoft.com/help/sales/customer-payment/) і [Повернення коштів покупцю](https://bimpsoft.com/help/sales/customer-refund/). Оплати постачальникам розглянуто в статті [Закупівлі через API](https://bimpsoft.com/help/developers/purchasing-via-api/). Токен компанії передається в заголовку `access-token` ([Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/)).

## Які методи і в якому порядку

| Крок | Метод | Навіщо |
|---|---|---|
| 1 | [`bankAccounts/api-readList`](/help/developers/api-reference/bank-accounts/#api-read-list) і [`cashRegistry/api-readList`](/help/developers/api-reference/cash-registry/#api-read-list) | Отримати `uuid` рахунків і кас — це значення поля `paymentEntity` |
| 2 | [`currency/api-readList`](/help/developers/api-reference/currency/#api-read-list) | Отримати `uuid` валюти документа |
| 3 | [`invoiceForCustomerPayment/api-readByExternalId`](/help/developers/api-reference/invoice-for-customer-payment/#api-read-by-external-id) | Знайти [замовлення покупця](https://bimpsoft.com/help/sales/customer-order/), яке оплачується ([Синхронізація замовлень](https://bimpsoft.com/help/developers/sync-orders/)) |
| 4 | [`customerPayment/api-create`](/help/developers/api-reference/customer-payment/#api-create) | Створити оплату від покупця на замовлення |
| 5 | `customerPayment/api-readList` | Перевірити, чи оплата вже є (фільтр `orders`) |
| 6 | [`refundToCustomer/api-create`](/help/developers/api-reference/refund-to-customer/#api-create) | Повернути кошти покупцю |
| 7 | [`otherExpenses/api-create`](/help/developers/api-reference/other-expenses/#api-create) | Записати витрату (комісія еквайрингу, доставка тощо) |
| 8 | [`interaccountTransfer/api-create`](/help/developers/api-reference/interaccount-transfer/#api-create) | Перенести кошти між касами і рахунками |
| 9 | `customerPayment/api-cancel` | Скасувати помилкову оплату |

## Як створити оплату від покупця

`customerPayment/api-create` вимагає покупця `counterparty` і валюту `currency`. Зв'язок із замовленням задає масив `paymentDetails`: кожен елемент містить `invoiceForCustomerpayment` (uuid замовлення покупця; зверніть увагу на написання поля — з малою літерою `p`) і `payed` (сума). Касу або рахунок вказує `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 }
    ]
  }'
```

Відповідь: `{ "success": true, "data": { "uuid": "<payment-uuid>" } }`.

Поле `commission` — комісія платіжної системи; `calculationRate` (в елементі `paymentDetails`) — крос-курс, якщо валюта оплати відрізняється від валюти замовлення ([Одна оплата на кілька замовлень у різних валютах](https://bimpsoft.com/help/sales/multi-currency-payment-allocation/)). Після збереження в замовленні збільшується `sumPayed`, а залишок до сплати зменшується.

**Оплата кількох замовлень одним платежем.** Додайте елементи в `paymentDetails`:

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

**Аванс і переплата.** Правила обліку авансів і переплат описані в статті Оплата від покупця, аванси та переплати. 

## Як змінити або скасувати оплату

`customerPayment/api-update` приймає `uuid` і поля, що змінюються (`number`, `comment`, `date`, `paymentEntity`, `commission`, `currency`, `paymentDetails`). `customerPayment/api-cancel` з `uuid` скасовує документ. Статуси оплат повертає `customerPayment/api-readStatuses`.

## Як не створити дублі оплат

Для оплат у специфікації немає методів зовнішніх ID, тому захищайтеся так:

1. Передавайте ID платежу вашої платіжної системи в `number` або `comment` документа.
2. Перед створенням оплати викличте `customerPayment/api-readList` з фільтром `orders: ["<order-uuid>"]` і періодом у `periodable`. Якщо платіж з таким `number` уже є — не створюйте.
3. Створюйте оплату лише після підтвердження платежу вашою платіжною системою, а не при оформленні замовлення.
4. Ведіть у своїй базі пару «ID платежу — `uuid` оплати Bimp». 

Замовлення, до якого належить оплата, знаходьте за зовнішнім ID, а не за номером документа: [Зовнішні ID](https://bimpsoft.com/help/developers/api-external-ids/).

## Як повернути кошти покупцю

`refundToCustomer/api-create` вимагає: `expenseItem` ([стаття витрат](https://bimpsoft.com/help/getting-started/income-and-expense-items/)), `customer`, `organization`, `paymentEntity`, `author` і масив `paymentDetails` з елементами `invoice` (замовлення покупця) та `refundSum`. Статті витрат — [`expenseItems/api-readList`](/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 } ]
  }'
```

Повернення товару від покупця — окремий документ ([`customer-inventories-return/api-create`](/help/developers/api-reference/customer-inventories-return/#api-create)), а грошове повернення оформлюється `refundToCustomer`. Обидва кроки описані в статтях [Повернення товару від покупця](https://bimpsoft.com/help/sales/customer-return/) та Повернення коштів покупцю.

## Як записати витрату або дохід

`otherExpenses/api-create` фіксує витрату, не пов'язану із закупівлею товару: `organization`, `expenseItem`, `paymentEntity` обов'язкові, а в `paymentDetails` для кожного рядка — `sum`, `project`, `lineOfBusiness`, `expenseItem` (за потреби `invoiceForCustomerPayment`, щоб віднести витрату на замовлення).

```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>"
      }
    ]
  }'
```

Аналогічно `otherIncome/api-create` записує інший дохід (`incomeItem`, статті доходів — [`incomeItems/api-readList`](/help/developers/api-reference/income-items/#api-read-list)). Правила обліку витрат — [Витрати періоду, податки та інші витрати](https://bimpsoft.com/help/finance/period-expenses/). Заявку на витрату (план платежу) створює [`expenseRequest/api-create`](/help/developers/api-reference/expense-request/#api-create).

## Як перенести кошти між рахунками

`interaccountTransfer/api-create` вимагає `organization`, `paymentEntitySender`, `paymentEntityRecipient`, `sum`, `project` і `lineOfBusiness`. Для переказу між рахунками в різних валютах додайте `currency`, `purchaseCurrency`, `rate` і `amountToCredit`. Залишки на рахунках і в касах повертає [`financing-balance/api-readList`](/help/developers/api-reference/financing-balance/#api-read-list) — див. [Залишок коштів на рахунках і в касах](https://bimpsoft.com/help/reports/cash-balance-report/).

## Вебхуки і опитування

Окремого вебхука на оплати немає: типи вебхуків — `inventory_balance`, `product_upsert` і `order_status` ([Вебхуки](https://bimpsoft.com/help/developers/webhooks/)). Про зміну оплати вашу систему сповістить подія `order_status`, якщо [статус замовлення](https://bimpsoft.com/help/sales/order-statuses/) змінюється при оплаті, а в тілі події є `sumPayed`. Інакше раз на кілька хвилин викликайте `customerPayment/api-readList` з періодом `periodable` і фільтром `orders`. 

## Типові помилки

**Оплата створилась, але замовлення не позначено оплаченим.** Причина: у `paymentDetails` не вказано `invoiceForCustomerpayment` або вказано інше замовлення. Рішення: перевірте написання поля і uuid; зверніть увагу, що поле називається `invoiceForCustomerpayment`, а не `invoiceForCustomerPayment`.

**Помилка валідації `currency`.** Причина: передано код валюти (`UAH`) замість uuid. Рішення: візьміть uuid із `currency/api-readList`.

**Не знайдено `paymentEntity`.** Причина: передано uuid рахунку іншої організації або не uuid. Рішення: використовуйте `uuid` з `bankAccounts/api-readList` або `cashRegistry/api-readList`.

**Подвійна оплата після повтору запиту.** Причина: `api-create` повторили без перевірки. Рішення: правила в розділі «Як не створити дублі оплат»; зайву оплату скасуйте методом `customerPayment/api-cancel`.

**Помилка 429.** Перевищено ліміт запитів, див. [Ліміти](https://bimpsoft.com/help/developers/api-limits/).

## FAQ

**Як зафіксувати в Bimp оплату з інтернет-магазину?**

Викличте customerPayment/api-create: вкажіть покупця, валюту, paymentEntity (касу або рахунок) і в paymentDetails — uuid замовлення покупця та суму payed.

**Де взяти paymentEntity?**

Це uuid банківського рахунку (bankAccounts/api-readList) або каси (cashRegistry/api-readList) вашої компанії.

**Чи можна одним платежем закрити кілька замовлень?**

Так. У paymentDetails додайте окремий елемент з invoiceForCustomerpayment і payed для кожного замовлення.

**Як скасувати оплату?**

Викличте customerPayment/api-cancel з uuid оплати. Для оплати постачальнику — paymentToSupplier/api-cancel.