Prerequisites

To use this service, you will need API keys from the Open Finance dashboard: https://dashboard.open-finance.ai.

First step

First you have to create a token with your credentials so you can use our API.

Create Token

URL: https://api.open-finance.ai/oauth/token

Method: POST

Request Body

Key	Type	Description	Example	Required
`userId`	string	Unique user identifier	`[email protected]`	true
`clientId`	string	Provided in dashboard	`1234`	true
`clientSecret`	string	Provided in dashboard	`1234`	true

Headers

Key	Value
`Content-Type`	`application/json`

Example Request

{
  "userId": "[email protected]",
  "clientId": "{{CLIENT_ID}}",
  "clientSecret": "{{CLIENT_SECRET}}"
}

Example Response (Status 200)

{
  "tokenType": "Bearer",
  "expiresIn": 86400,
  "accessToken": "iJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InQ4"
}

Error Responses

401 Unauthorized

{
  "type": "CLIENT_ERROR",
  "message": "{\"error\":\"access_denied\",\"error_description\":\"Unauthorized\"}"
}

400 Bad Request

{
  "type": "CLIENT_ERROR",
  "message": "[\"\\\"clientSecret\\\" is required\"]"
}

500 Internal Server Error

{
  "type": "INTERNAL_ERROR",
  "message": "SERVER_ERROR"
}

Second step

After creating the token you can request to create a payment and get back the URL for the payment journey

Create Payment

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

Method: POST

Request Body

Key	Type	Description	Example	Required	Default
`providerIds`	array of strings	Unique bank identifiers	`["leumi"]`	false	Predefined list
`merchantId`	string	Unique merchant identifier	`01JENRQEA8AYG4MCTVCTH9Y6NJ`	false	`null`
`psuId`	string	User ID or Passport	`321547416`	false	`null`
`psuCorporateId`	string	Business ID of a customer	`987654321`	false	`null`
`allowBusiness`	boolean	Can the user pay from a business account	`true`	false	`false`
`isBusiness`	boolean	Does the user have to pay from a business account	`true`	false	`false`
`language`	`en`, `he`	Predetermined language for the payment journey	`true`	false	`null`
`iframe`	bool	Whether to embed the journey in an iframe	`false`	false	`false`
`paymentService`	string	Type of payment service	`masav`	false	`masav`
`directPayOnly`	boolean	Can the user pay only by a direct payment	`true`	false	`false`
`includeFakeProviders`	boolean	Use fake providers for testing	`true`	false	`false`
`paymentInformation`	object	Details of the payment	See below	true
`redirectUrl`	string	The URL to which the user will be redirected after the payment is completed	`https://www.example.com`	false	`null`
`externalId`	string	An external id that will be sent in the post message in iframe mode	`01JENRQEA8AYG4MCTVCTH9Y6NJ`	false	`null`

Payment Information

Key	Type	Description	Example	Required
`amount`	number	Payment amount	`100`	true
`currency`	string	ISO-4217 currency code	`ILS`	true
`description`	string	Payment description	`Transfer for goods`	true
`creditorAccountType`	string	Account type of the creditor	`iban`	true
`creditorAccountNumber`	string	Account number of the creditor	`IL730200040000000552717`	true
`debtorAccountType`	string	Account type of the debtor	`bban`	false
`debtorAccountNumber`	string	Account number of the debtor	`10-944-50151142`	false
`creditorName`	string	Name of the creditor	`John Doe`	true

Callback Information

Key	Type	Description	Example	Required	Default
`webhooks`	object	Webhook configuration	See below	false

Example Request

{
  "providerIds": ["leumi"],
  "psuId": "318422557",
  "paymentInformation": {
    "amount": "100",
    "currency": "ILS",
    "creditorName": "Elon",
    "description": "Test"
  },
  "callbackInformation": {
    "webhooks": {
      "enabled": true,
      "successUrl": "https://www.success.co.il",
      "failUrl": "https://www.fail.co.il"
    }
  }
}

Callback Information

Key	Type	Description	Example	Required
`webhooks`	object	Webhook configuration	See below	false
`successUrl`	string	The URL to redirect the user upon successful payment completion	`https://success.example`	false
`failUrl`	string	The URL to redirect the user upon payment failure	`https://fail.example`	false
`oauth`	object	OAuth configuration used for secure webhook delivery	See below	false
`customHeaders`	object	Custom headers that should be included in webhook requests	`{ "X-Header": "Value" }`	false

Webhook Configuration

Key	Type	Description	Example	Required	Default
`enabled`	bool	Whether webhooks are enabled	`true`	false	`false`
`successUrl`	string	The URL to redirect the user upon successful payment completion	`https://example.com/success`	false
`failUrl`	string	The URL to redirect the user upon a failed payment	`https://example.com/fail`	false

OAuth Configuration

Key	Type	Description	Example	Required	Default
`enabled`	bool	Whether OAuth is required	`true`	false	`false`
`clientId`	string	The client ID for OAuth	`123456`	true
`clientSecret`	string	The client secret for OAuth	`abcdef`	true
`audience`	string	The audience for the OAuth token	`open-finance`	false
`scope`	string	The scope of the OAuth token	`read:accounts`	false
`tokenUrl`	string	The URL to retrieve the OAuth token	`https://auth.example`	false

Example Callback Information

{
  "webhooks": {
    "enabled": true,
    "successUrl": "https://success.example",
    "failUrl": "https://fail.example",
    "oauth": {
      "enabled": true,
      "clientId": "client_id_value",
      "clientSecret": "client_secret_value",
      "audience": "https://api.example.com",
      "scope": "read:accounts write:payments",
      "tokenUrl": "https://auth.example.com/oauth/token"
    },
    "customHeaders": {
      "X-Header-Example": "HeaderValue"
    }
  }
}

Example Response (Status 200)

{
  "id": "01HWQ9WMP7NA57YEQ7DQWZHQ5G",
  "payUrl": "http://localhost:3601/su/01J4S4ASB735D5W9FQDP3DWZ6E"
}

Error Responses

401 Unauthorized

{
  "type": "CLIENT_ERROR",
  "message": "{\"error\":\"access_denied\",\"error_description\":\"Unauthorized\"}"
}

500 Internal Server Error

{
  "type": "INTERNAL_ERROR",
  "message": "SERVER_ERROR"
}

Unexpected error.

{
  "type": "INTERNAL_ERROR",
  "message": "An unexpected server error has occurred"
}

What is next?

After receiving the payUrl you can redirect your client to this URL so they can authorize the payment through their bank. Using the id you got you can request to get the payment and sample it until you get a success status

Payment Statuses

The payment status indicates the payment transfers status.

Please see the following Payment Status Page

Get Payment

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

Method: GET

Headers

Key	Value
`Authorization`	Token created previously

Example Response (Status 200)

{
  "id": "01HA4AEFZS6WQSE46G2NH2FRR1",
  "userId": "[email protected]",
  "providerId": "mizrahi-sandbox",
  "status": "RCVD",
  "amount": "2",
  "currency": "ILS",
  "description": "sdfsdf"
}