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

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 and Customer refund. Supplier payments are covered in Purchasing via the API. The company token is passed in the access-token header (Getting started with the API).

Which methods to call and in what order

Step	Method	Why
1	bankAccounts/api-readList and cashRegistry/api-readList	Get the uuid of accounts and cash desks; these are the values of the paymentEntity field
2	currency/api-readList	Get the uuid of the document currency
3	invoiceForCustomerPayment/api-readByExternalId	Find the Customer order being paid (Order sync)
4	customerPayment/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	Refund money to the customer
7	otherExpenses/api-create	Record an expense (acquiring fee, delivery and so on)
8	interaccountTransfer/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 uuid; note the spelling of the field, with a lowercase p) and payed (the amount). The cash desk or account is specified by paymentEntity.

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). 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:

"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.

How to refund money to a customer

refundToCustomer/api-create requires: expenseItem (expense item), customer, organization, paymentEntity, author and a paymentDetails array with invoice (the Customer order) and refundSum elements. Expense items are available from expenseItems/api-readList.

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), while the money refund is recorded with refundToCustomer. Both steps are described in 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).

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). For expense accounting rules, see Period expenses, taxes and other expenses. An expense request (a payment plan) is created by expenseRequest/api-create.

How to transfer money between accounts

interaccountTransfer/api-create requires organization, paymentEntitySender, paymentEntityRecipient, sum, project and lineOfBusiness. For a transfer between accounts in different currencies, add currency, purchaseCurrency, rate and amountToCredit. Balances in accounts and cash desks are returned by financing-balance/api-readList; see Cash balance in accounts and cash desks.

Webhooks and polling

There is no separate webhook for payments: the webhook types are inventory_balance, product_upsert and order_status (Webhooks). Your system is notified of a payment change by the order_status event if the order status 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.