Periodic Payment Initialization

Initialize periodic payments (standing orders) directly with a specific bank, bypassing the Open Finance UI. Use this when you know which bank the user will authorize with.

When to Use This Method

Use Payment Initialization when:

• You already know which bank the user will use
• You're building a custom bank selection UI
• You want to skip the Open Finance journey for a faster experience
• You have the user's bank provider ID from a previous connection

For general payment flows where the bank is unknown, use Periodic Payment Creation instead.

Prerequisites

• API credentials from the Open Finance dashboard
• Valid clientId and clientSecret
• Bank providerId 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 Periodic Payment

Initialize a periodic payment directly with the bank. Returns the bank's authorization URL.

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

Security: Bearer token with create:payments scope

Request Example

{
  "providerId": "hapoalim",
  "psuId": "123456789",
  "redirectUrl": "https://yourapp.com/payment-complete",
  "periodicPaymentInformation": {
    "amount": 500,
    "currency": "ILS",
    "description": "Quarterly tax payment",
    "creditorAccountNumber": "IL620108000000099999999",
    "creditorAccountType": "iban",
    "creditorName": "Tax Authority",
    "debtorAccountNumber": "IL620108000000088888888",
    "debtorAccountType": "iban",
    "startDate": "2024-01-15",
    "endDate": "2024-12-15",
    "frequency": "Quarterly",
    "dayOfExecution": "15",
    "executionRule": "following"
  }
}

Request Parameters

periodicPaymentInformation Object

Important: Unlike the Payment Creation endpoint, the Init endpoint requires debtorAccountNumber and debtorAccountType.

Supported Frequencies

Response

{
  "paymentId": "01HQXYZ123456789ABCDEF",
  "status": "RCVD",
  "scaOAuth": "https://bank-provider.com/oauth/authorize?client_id=..."
}

Step 3: Redirect User

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

1. Authenticate with their bank
2. Authorize the standing order
3. Be redirected to your redirectUrl

Payment Flow

Your App                         Bank
   |                               |
   |-- POST /pay/open-banking-init |
   |   (with providerId)           |
   |                               |
   |<-- { paymentId, scaOAuth } ---|
   |                               |
   |-- Redirect to scaOAuth ------>|
   |                               |
   |   User authenticates & ------>|
   |   authorizes standing order   |
   |                               |
   |<-- Redirect to redirectUrl ---|
   |                               |

Provider-Specific Rules

Different banks have specific requirements:

Leumi

Hapoalim

Validation Rules

Date Validation

• startDate must be today or a future date
• endDate (if provided) must be after startDate

Frequency Rules

• dayOfExecution must be between 1 and 31
• monthsOfExecution is required only for MonthlyVariable frequency
• monthsOfExecution values must be unique (1-12), maximum 11 months

Account Validation

• Creditor and debtor accounts cannot be the same
• Debtor account information is required for this endpoint

Error Responses

Examples

Quarterly Tax Payment (Hapoalim)

{
  "providerId": "hapoalim",
  "psuId": "987654321",
  "redirectUrl": "https://myapp.com/tax-complete",
  "periodicPaymentInformation": {
    "amount": 2500,
    "currency": "ILS",
    "description": "Quarterly VAT payment",
    "creditorAccountNumber": "IL620108000000055555555",
    "creditorAccountType": "iban",
    "creditorName": "Israel Tax Authority",
    "debtorAccountNumber": "IL620108000000066666666",
    "debtorAccountType": "iban",
    "startDate": "2024-01-15",
    "endDate": "2024-12-15",
    "frequency": "Quarterly",
    "dayOfExecution": "15",
    "executionRule": "following"
  }
}

Monthly Payment (Leumi)

{
  "providerId": "leumi",
  "psuId": "123456789",
  "redirectUrl": "https://myapp.com/payment-complete",
  "periodicPaymentInformation": {
    "amount": 1500,
    "currency": "ILS",
    "description": "Monthly service fee",
    "creditorAccountNumber": "IL620108000000011111111",
    "creditorAccountType": "iban",
    "creditorName": "Service Provider Ltd",
    "debtorAccountNumber": "IL620108000000022222222",
    "debtorAccountType": "iban",
    "startDate": "2024-02-01",
    "endDate": "2024-12-31",
    "frequency": "Monthly",
    "dayOfExecution": "1"
  }
}

Note: Leumi example does not include executionRule as it's forbidden for this provider.

Resume Existing Payment

If a payment was started but not completed, you can resume it:

{
  "providerId": "hapoalim",
  "psuId": "123456789",
  "paymentId": "01HQXYZ123456789ABCDEF",
  "redirectUrl": "https://myapp.com/payment-complete"
}

Get Payment Status

Check the status of a periodic payment.

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

Response

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

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

Cancel Periodic Payment

Cancel an active standing order.

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

Note: Only authorized periodic payments can be cancelled.