Create a Mandate with the Open Finance Journey

Use this when you do not know your customer's bank or account. You create a link, send it to the customer, and the Open Finance journey does the rest.

Step 1: Create Token

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

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

Step 2: Create the Mandate Link

Endpoint: POST https://api.open-finance.ai/v2/mandates

Security: Bearer token with create:mandates scope

Request Example

{
  "useJourney": true,
  "redirectUrl": "https://yourapp.com/mandate-complete",
  "mandateInformation": {
    "creditorInstitutionCode": "23954",
    "maxAmount": 1000,
    "endDate": "2027-10-19",
    "mandateReference": "SUB-1042"
  }
}

Request Fields

Field	Required	Description
`useJourney`	Yes	`true` to get a journey link.
`mandateInformation.creditorInstitutionCode`	Yes	Your institution code (קוד מוסד) at Masav.
`mandateInformation.maxAmount`	No	Limit per charge, at least `1`. Omit it for a mandate without a limit.
`mandateInformation.frequency`	No	How often you charge. Requires `providerId` (see below).
`mandateInformation.startDate`	No	First charge date, `YYYY-MM-DD`. Requires `providerId`.
`mandateInformation.endDate`	No	Expiry date, `YYYY-MM-DD`. Without it the mandate is valid until cancelled.
`mandateInformation.mandateReference`	No	Your reference (מספר אסמכתא), up to 35 characters.
`providerId`	No	Pin the bank the customer must use, e.g. `hapoalim`.
`psuId`	No	The customer's ID number. Prefilled in the journey, and the customer must use it.
`allowBusiness`	No	Let the customer choose a business account and enter a company number.
`includeFakeProviders`	No	Offer sandbox banks in the journey.
`redirectUrl`	No	Where the customer goes when the journey ends. Must be in your allowed domains.

Response (201)

{
  "mandateId": "01J9ZK2P7R4V1W6X3M5L0A8B7C",
  "mandateStatus": "INACTIVE",
  "mandateUrl": "https://api.open-finance.ai/su/01J9ZK2P9S3T0U5V2W4X6Y8Z1A"
}

The link is valid for 24 hours.

Step 3: The Customer Completes the Journey

The customer reads what a mandate is and their rights, and accepts the terms.
They see your terms (charge limit, frequency, expiry), pick their bank, and enter their ID, branch and account number.
The journey creates the mandate at the bank (POST /v2/mandates/{mandateId}/init, called by the journey, not by you) and sends the customer to the bank to approve.
After approval, the customer returns to redirectUrl and you receive the webhook.

If the customer leaves before approving at the bank and opens the link again, the journey goes straight back to the bank approval step.

What Is Checked, and When

Check	When	Message
`maxAmount` at least 1	Link creation	`400` validation error
`endDate` after today and after `startDate`	Link creation, and again when the customer starts	`mandateInformation.endDate must be after today (YYYY-MM-DD).`
`frequency` or `startDate` without `providerId`	Link creation	`providerId is required when mandateInformation.frequency is set, because a time period is supported only by some providers: hapoalim, mizrahi.`
A pinned bank that does not support a term	Link creation	`PARAMETER_NOT_SUPPORTED`, naming the supported banks

Without a pinned bank, the journey hides the banks that do not support the frequency or first charge date you set. A bank that cannot take another term is refused when the customer picks it, with the same message.

Step 4: Track the Mandate

Listen to the webhook, or call GET https://api.open-finance.ai/v2/mandates/{mandateId}/status for the live status. See Overview for the statuses.