Bulk Payment Initialization

Initialize multiple payments to different recipients directly with a specific bank, bypassing the Open Finance bank selection UI. Use this when you already know which bank the user will pay from.

When to Use This Flow

Use Case	Recommended Flow
You don't know the user's bank	Use Bulk Payment Creation
You know the user's bank	Use this flow (Init)
User should choose their bank	Use Bulk Payment Creation
Direct integration with specific bank	Use this flow (Init)

Prerequisites

API credentials from the Open Finance dashboard
Valid clientId and clientSecret
Provider ID (bank identifier) for the user's bank

Step 1: Create Token

Create an access token to authenticate your API requests.

Endpoint: POST https://api.open-finance.ai/oauth/token

Request

{
  "userId": "your-user-id",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

Step 2: Initialize Bulk Payment

Initialize a bulk payment directly with the specified bank.

Endpoint: POST https://api.open-finance.ai/v2/pay/open-banking-init

Security: Bearer token with create:payments scope

Important: Unlike the Bulk Payment Creation endpoint, this endpoint requires providerId and allows a minimum of 1 payment (instead of 2).

Request Example

{
  "psuId": "123456789",
  "providerId": "hapoalim",
  "redirectUrl": "https://yourapp.com/payment-complete",
  "bulkPaymentInformation": {
    "debtorAccountNumber": "IL620108000000012345678",
    "debtorAccountType": "iban",
    "batchBookingPreferred": true,
    "payments": [
      {
        "amount": 5000,
        "currency": "ILS",
        "description": "Invoice #1001",
        "creditorAccountNumber": "IL620108000000099999999",
        "creditorAccountType": "iban",
        "creditorName": "Supplier A Ltd"
      },
      {
        "amount": 3500,
        "currency": "ILS",
        "description": "Invoice #1002",
        "creditorAccountNumber": "IL620108000000088888888",
        "creditorAccountType": "iban",
        "creditorName": "Supplier B Ltd"
      }
    ]
  }
}

Request Parameters

Key	Type	Description	Example	Required
`psuId`	string	Payment service user identifier (national ID)	`"123456789"`	Yes
`providerId`	string	Bank identifier	`"hapoalim"`, `"leumi"`, `"mizrahi"`	Yes
`language`	string	UI language	`"en"` or `"he"`	No
`redirectUrl`	string	URL to redirect after authorization	`"https://yourapp.com/callback"`	No
`bulkPaymentInformation`	object	Bulk payment details	See below	Yes

bulkPaymentInformation Object

Key	Type	Description	Example	Required
`debtorAccountNumber`	string	Funding account number	`"IL620108000000012345678"`	Yes
`debtorAccountType`	string	Funding account type	`"iban"` or `"bban"`	Yes
`batchBookingPreferred`	boolean	Request batch processing at bank	`true`	No
`paymentInformationId`	string	Custom reference ID (max 35 chars)	`"BATCH-2024-001"`	No
`requestedExecutionDate`	string	Future execution date (ISO format)	`"2024-02-15"`	No
`requestedExecutionTime`	string	Future execution datetime (ISO format)	`"2024-02-15T10:00:00Z"`	No
`payments`	array	Array of payment entries (minimum 1)	See below	Yes

Note: requestedExecutionDate and requestedExecutionTime are mutually exclusive. Provide only one.

Payment Entry Object

Key	Type	Description	Example	Required
`amount`	number	Payment amount	`5000`	Yes
`currency`	string	Currency code (must be ILS)	`"ILS"`	Yes
`description`	string	Payment reference	`"Invoice #1001"`	Yes
`creditorAccountNumber`	string	Recipient account number	`"IL620108000000099999999"`	Conditional
`creditorAccountType`	string	Recipient account type	`"iban"` or `"bban"`	Conditional
`creditorName`	string	Recipient name	`"Supplier A Ltd"`	Conditional
`merchantId`	string	Pre-configured merchant ID	`"merchant-001"`	Conditional

Note: For each payment entry, provide either merchantId OR creditor information (creditorAccountNumber, creditorAccountType, creditorName).

Response

{
  "id": "01HQXYZ123456789ABCDEF",
  "scaOAuth": "https://www.bankhapoalim.co.il/authenticate?token=abc123...",
  "status": "RCVD"
}

Key	Type	Description
`id`	string	Unique payment identifier
`scaOAuth`	string	Direct URL to bank's authentication page
`status`	string	Initial payment status (typically `RCVD`)

Step 3: Redirect to Bank

Redirect the user directly to the scaOAuth URL. The user will:

Authenticate with their bank (no bank selection needed)
Review and authorize all payments in the bulk
Be redirected to your redirectUrl

Payment Flow

Your App                    Open Finance                 Bank
   |                             |                         |
   |-- POST /open-banking-init ->|                         |
   |                             |-- Init with provider -->|
   |<-- { id, scaOAuth } --------|<-- Ready ---------------|
   |                             |                         |
   |-- Redirect to scaOAuth -----|------------------------>|
   |                             |                         |
   |                             |     User authenticates  |
   |                             |     User authorizes     |
   |                             |                         |
   |<-- Redirect to redirectUrl -|<------------------------|
   |                             |                         |

Key Differences from Journey Flow

Aspect	Journey (Create)	Direct (Init)
Endpoint	`POST /payments`	`POST /pay/open-banking-init`
Minimum payments	2	1
Provider selection	User selects in UI	You specify `providerId`
Returns	`payUrl`	`scaOAuth`
Initial status	`INIT`	`RCVD`
Use case	Unknown bank	Known bank

Validation Rules

Payment Count

Minimum 1 payment required in the payments array

Currency

All payments must use ILS currency
Mixed currencies are not supported

Provider

providerId is required
Must be a valid, active provider

Date Rules

requestedExecutionDate and requestedExecutionTime are mutually exclusive
Future dates must be valid business days

Account Validation

Creditor and debtor accounts cannot be the same
Each creditor account must be in the organization's allowed list

Error Responses

Status	Error	Description
400	`providerId is required`	Missing provider identifier
400	`All payments must be in ILS`	Non-ILS currency detected
400	`Cannot provide both requestedExecutionDate and requestedExecutionTime`	Mutually exclusive fields
400	`Creditor and debtor accounts are the same`	Same account error
401	`Unauthorized`	Invalid or expired token
404	`Provider not found`	Invalid provider ID
404	`Merchant not found`	Invalid merchant ID

Examples

Single Supplier Payment (Known Bank)

{
  "psuId": "123456789",
  "providerId": "leumi",
  "redirectUrl": "https://myapp.com/payment-complete",
  "bulkPaymentInformation": {
    "debtorAccountNumber": "IL620108000000012345678",
    "debtorAccountType": "iban",
    "payments": [
      {
        "amount": 15000,
        "currency": "ILS",
        "description": "Invoice INV-2024-0500",
        "creditorAccountNumber": "IL620108000000099999999",
        "creditorAccountType": "iban",
        "creditorName": "Tech Solutions Ltd"
      }
    ]
  }
}

Multi-Vendor Payment with Future Date

{
  "psuId": "987654321",
  "providerId": "mizrahi",
  "bulkPaymentInformation": {
    "debtorAccountNumber": "IL620108000000055555555",
    "debtorAccountType": "iban",
    "requestedExecutionDate": "2024-03-01",
    "paymentInformationId": "VENDORS-MAR-2024",
    "payments": [
      {
        "amount": 8500,
        "currency": "ILS",
        "description": "Q1 Software License",
        "merchantId": "vendor-software-co"
      },
      {
        "amount": 3200,
        "currency": "ILS",
        "description": "Office Supplies Feb",
        "merchantId": "vendor-office-mart"
      },
      {
        "amount": 12000,
        "currency": "ILS",
        "description": "Consulting Services",
        "creditorAccountNumber": "IL620108000000066666666",
        "creditorAccountType": "iban",
        "creditorName": "Business Consulting Ltd"
      }
    ]
  }
}

Batch Payroll via Known Bank

{
  "psuId": "555666777",
  "providerId": "hapoalim",
  "redirectUrl": "https://hr-system.com/payroll-done",
  "bulkPaymentInformation": {
    "debtorAccountNumber": "IL620108000000077777777",
    "debtorAccountType": "iban",
    "batchBookingPreferred": true,
    "paymentInformationId": "PAYROLL-FEB-2024",
    "payments": [
      {
        "amount": 18000,
        "currency": "ILS",
        "description": "Salary Feb 2024",
        "creditorAccountNumber": "IL620108000000011111111",
        "creditorAccountType": "iban",
        "creditorName": "Yael Mizrahi"
      },
      {
        "amount": 22000,
        "currency": "ILS",
        "description": "Salary Feb 2024",
        "creditorAccountNumber": "IL620108000000022222222",
        "creditorAccountType": "iban",
        "creditorName": "Oren Shapira"
      }
    ]
  }
}

Get Payment Status

Check the status of a bulk payment.

Endpoint: GET https://api.open-finance.ai/v2/payments/{PAYMENT_ID}

Response

{
  "paymentId": "01HQXYZ123456789ABCDEF",
  "status": "ACCC",
  "paymentProduct": "bulk-payments"
}

For a complete list of payment statuses, see Payment Statuses.