Payment Initialization Documentation

Prerequisites

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

Create Token

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

Method: POST

Request Body

Headers

Example Request

{
  "userId": "avi@open-finance.ai",
  "clientId": "{{CLIENT_ID}}",
  "clientSecret": "{{CLIENT_SECRET}}"
}

Example Response (Status 200)

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

Error Responses

• 401 Unauthorized
  JSON

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

• 400 Bad Request
  JSON

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

• 500 Internal Server Error
  JSON

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

• JSON

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

Open Banking Payment Initialization

URL: /pay/open-banking-init

Method: POST

Summary

Initiate a payment with a provider.

Security

• oAuth2ClientCredentials: create:payments

Request Body

Payment Information

Example Request

{
  "providerId": "leumi",
  "paymentService": "masav",
  "paymentInformation": {
    "amount": 100,
    "currency": "ILS",
    "description": "Test Payment",
    "creditorAccountType": "iban",
    "creditorAccountNumber": "IL730200040000000552717",
    "creditorName": "John Doe"
  }
}

Example Response (Status 201)

{
  "paymentId": "01HWQ9WMP7NA57YEQ7DQWZHQ5G",
  "status": "PENDING",
  "scaOAuth": "https://auth.provider.com/oauth2/authorize"
}

Error Responses

• 400 Bad Request
  • Missing payment info or invalid provider.
  JSON

  {
    "type": "CLIENT_ERROR",
    "message": "Needs to provide paymentId or new payment info"
  }
  

• 401 Unauthorized
  • Invalid or missing token.
  JSON

  {
    "message": "Unauthorized"
  }
  

• 404 Not Found
  • Payment or provider not found.
  JSON

  {
    "type": "CLIENT_ERROR",
    "message": "Payment not found with this id"
  }
  

• 500 Internal Server Error
  • Unexpected error.
  JSON

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

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

Example Response (Status 200)

{
  "id": "01HA4AEFZS6WQSE46G2NH2FRR1",
  "userId": "avi@open-finance.ai",
  "providerId": "mizrahi-sandbox",
  "status": "RCVD",
  "amount": "2",
  "currency": "ILS",
  "description": "sdfsdf"
}

Using Sandbox for Payment Initiation

Overview

The sandbox environment allows you to simulate payment initiation with predefined account numbers and statuses. Use the following steps to initiate a payment in the sandbox and interpret the resulting statuses.

Steps

1. Use one of the predefined account numbers below when initiating a payment.
2. Depending on the account number used, the payment will finalize with the corresponding status.
3. When creating the payment you need to mark it as includeFakeProviders: true

Sandbox Account Numbers and Statuses

Example Request

{
  "providerId": "leumi",
  "paymentService": "masav",
  "includeFakeProviders": true,
  "paymentInformation": {
    "amount": 100,
    "currency": "ILS",
    "description": "Test Sandbox Payment",
    "creditorAccountType": "bban",
    "creditorAccountNumber": "31-114-436003",
    "creditorName": "John Doe"
  }
}

Example Response (Status 201)

{
  "paymentId": "01HWQ9WMP7NA57YEQ7DQWZHQ5G",
  "status": "RCVD",
  "scaOAuth": "https://url-to-provider.com"
}