Create a Payment

POST https://api.open-finance.ai/v2/payments

This creates a payment and returns its id plus a hosted payUrl. At minimum
you send paymentInformation (amount, currency, description) and identify the
payee — either a merchantId (see Merchants (Payees)) or the creditor's
account details. Requires a Bearer token (see Authentication); rejected
requests (validation, disallowed redirect URL, sandbox gate, …) return the
standard error shape — see Errors.

⚠️

Payments require a connection. To make or receive a payment, the user

must have a linked bank (a Connection), and the payment must involve one of
their connected accounts — either as the debtor (paying from a connected
account) or the creditor (receiving into a connected account). If neither
side is a connected account, the payment can't proceed. Connections are created
only in the Financy UI — see Connections.

Financy payment fees

The request body is identical for app and API-key callers. For each new ILS
payment, Financy snapshots the organization's plan and fee when the payment is
created, then accrues that fee once — on the first successful completion.

For bulkPaymentInformation, the percentage and maximum are calculated for
each entry and then summed. The ₪0.50 minimum applies once to the complete bulk
payment, so a bulk request can exceed the single-entry maximum shown above.

Ultra examples: ₪1 → ₪0.50, ₪250 → ₪0.50, ₪1,000 → ₪2.00, and ₪1,350
or more → ₪2.70. A failed or canceled payment is not charged. Retries and
duplicate webhooks do not accrue the fee twice. Sandbox/fake providers, ATM
payments, non-ILS payments, and organizations outside Financy remain excluded.

paymentInformation

Describes what to charge and (unless you pass a merchantId) who to pay:

✳️

Provide the payee either by setting merchantId at the top level or

by giving creditorName + creditorAccountType + creditorAccountNumber
here. Omitting both returns Merchant Id or creditor info is required.

Top-level fields

📘

This covers the common fields. POST /v2/payments also accepts

bulkPaymentInformation and periodicPaymentInformation (for bulk and
recurring payments) and request-to-pay options — see the API Reference for
the full, field-by-field list.

Bulk payments (bulkPaymentInformation)

Every bulk payment must include the top-level version field with the exact
value v1.8. The leading v is part of the value; "version": "1.8" is
invalid.

When creating bulk payments, different banks have different requirements for the
paymentInformationId field:

For Discount and Mercantile bulk payments, set the bulkType field:

{
  "version": "v1.8",
  "bulkPaymentInformation": {
    "bulkType": "salaries",
    "debtorAccountNumber": "IL620111111111111111111",
    "debtorAccountType": "iban",
    "payments": [...]
  }
}

If you previously sent paymentInformationId as "salaries" or "suppliers",
that still works — but for new integrations, use bulkType. When both are sent
and disagree, bulkType wins.

Once a bank has been selected, GET /payments/{id} returns the bulkType that
was actually sent, and for Discount and Mercantile paymentInformationId
returns that same value.

Payment rails (paymentService)

If you don't set paymentService, Financy picks the appropriate rail. The three
rails are:

Request

curl -X POST https://api.open-finance.ai/v2/payments \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://your-app.com/payment/done",
    "language": "he",
    "paymentInformation": {
      "amount": 149.90,
      "currency": "ILS",
      "description": "Order #4471"
    }
  }'

Response

{
  "id": "01J8X...",
  "payUrl": "https://api.open-finance.ai/journey/01J8X..."
}

• id — the paymentId you use for status polling and for the direct-init step.
• payUrl — the hosted journey. Hosted flow: redirect the user here and skip
  to Payment Status. Direct flow: ignore payUrl and continue to
  Initiate a Payment (Direct).

💡

Set callbackInformation to be pushed the outcome instead of polling — see

Payment Webhooks. For what each status means, see Payment Statuses & FAQ.