Guides
  1. Payment Links
  2. Single Payment
  3. Feezback Link

Configuration Guide

JWT payload configuration guide

🔐

The JWT payload must be signed using your Private Key.

The JWT includes the details of the requested payment:

  • Amount

  • Currency

  • Creditor account

  • Debtor details (optional)

  • UI flow configurations (optional).

Follow this guide to configure your payment link.

Payment Line - JWT Payload Example

{
  "encrypt": true,
  "sub": "user-123",
  "iss": "tpp/{TPP_ID}",
  "srv": "fast/user",
  "ttl": 1800,
  "flow": {
    "id": "default",
    "userWasAuthenticated": false,
    "context": "tx-20250113001",
    "userIdentifier": {
      "type": "ID",
      "value": "216139683",
      "editable": true
    },
    "redirects": {
      "pisSuccess": "https://example.com/success",
      "pisFailure": "https://example.com/failure",
      "pisNotComplete": "https://example.com/not-complete",
      "ttlExpired": "https://example.com/expired"
    },
    "payment": {
      "remittanceInformationUnstructured": "Invoice payment",
      "creditor": {
        "name": "Company Ltd",
        "account": "IL760125380000000693304",
        "accountType": "iban"
      },
      "transfer": {
        "amount": {
          "value": "1.00",
          "editable": true
        },
        "currency": {
          "value": "ILS",
          "editable": false
        }
      }
    }
  }
}

Top level fields

FieldTypeRequiredDescription
encryptbooleanYesMust be true for JWTs sent to a /link endpoint. Place it at the top level, not inside flow.
substringYesA unique debtor identifier. Do not send PII. Apply hashing for PII values.
issstringYesYour organisation ID (tpp_id) provided by Feezback in the format: tpp/{TPP_ID}.
srvstringYesService selector. Use fast/user for Payment links.
ttlnumberNoLink validity in seconds. Defaults to 1800; maximum is 120 days.
flowobjectYesPayment flow configuration.

Flow level fields

FieldTypeRequiredDescription
flow.
id
string
Yes
Flow identifier. Use default unless Feezback configured a different flow for you.
flow.
userWasAuthenticated
boolean
Yes
Indicates whether the debtor was already authenticated before entering the flow. If true, the user will not be able to edit their ID used to login to the bank
flow.
context
string
Recommended
Send a unique transaction identifier to correlate the webhook with your internal transaction.
Max 50 characters.
flow.
userIdentifier
object
Conditional
debtor id or passport number
mandatory if userWasAuthenticated=true
flow.
corporateIdentifier
object
No
flow.
payment
object
Yes
Payment configuration.
flow.
redirects
object
Yes
Redirect URLs for payment outcomes.

Configure userIdentifier

  • The userIdentifier object allows you to set the debtor's identification.
  • Use it in cases you have the debtor's government ID or passport number (for example, after in-app/website authentication).
  • Consider wether you want it editable or locked. Enable editing when you can receive payments from a different ID. Disable editing when you want The transfer from a specific ID holder.
  • All fields within the object are mandatory if the object is sent
  • Defining userIdentifier is optional. If not sent with the JWT, the debtor will be prompted to fill out their ID (you will receive it with the webhook at the end of the process)
FieldTypeDescriptionOptional values
flow.userIdentifier.type
string
Type of identifier used for the user.
  • ID
  • PASSPORT
flow.userIdentifier.value
string
Actual identifier value
a valid Israeli ID / international Passport number*
flow.userIdentifier.editable
boolean
if True, the user may edit their ID. If False, ID is not editable.

*passport number format:
2 character country code - hyphen "-" - Passport number (1–9 alphanumeric characters)
For example:
IL-123456

Configure corporateIdentifier

  • The corporateIdentifier object allows you to set the debtor's corporate identification (in case your debtor is a corporate and you have their business number (ח.פ.)
  • If you don't have it, no worries: the debtor will add it on Feezback screens.

FieldTypeDescriptionOptional values
flow.corporateIdentifier.value
string
Corporate ID number (ח.פ). Only for corporate accounts.
Corporate ID number (ח.פ).
flow.corporateIdentifier.editable
boolean
Indicates whether the user may edit their corporate ID.
True/False
flow.corporateIdentifier.disabled
boolean
Send True to disable payments from corporate accounts.

Configure payment

  • payment object defines the description, amount, creditor, and debtor details.
  • The description, creditor and transfer objects are mandatory.
  • The debtor object is optional. It let's you pre-fill debtor account details if you have them through your app/website/internal flows.
{
  "payment": {
    "remittanceInformationUnstructured": "Invoice payment",
    "creditor": {
      "name": "Company Ltd",
      "account": "IL760125380000000693304",
      "accountType": "iban"
    },
    "transfer": {
      "amount": {
        "value": "1.00",
        "editable": true
      },
      "currency": {
        "value": "ILS",
        "editable": false
      }
    }
  }
}
FieldTypeRequireddescriptionoptional values
payment.
remittance
Information
Unstructured
string
Yes
״סיבת ההעברה״
will appear in the debtor and creditor bank transactions.
Maximum 28 characters. He/En characters only. Special characters not allowed
payment.
creditor.
name
string
Yes
Name of the receiver that will be displayed to the user.
He/En characters only. Special characters not allowed
payment.
creditor.
account
string
Yes
Creditor account number (BBAN/IBAN as defined in the next field).
Whitelisted production accounts only.
payment.
creditor.
accountType
string
Yes
“iban” / “bban” according to the account number format sent.
-IBAN
-BBAN
payment.
transfer.
amount.
value
string or null
Yes
Amount in X.XX format. Minimum 1.00. Send null if the debtor should enter the amount.
payment.
transfer.
amount.
editable
boolean
Yes
If true, the debtor may edit the transfer amount.
payment.
transfer.
currency.
value
string
Yes
send ILS (or see instructions for foreign currency payments)
ILS
payment.
transfer.
currency.
editable
boolean
Yes
see instructions for foreign currency payments)
payment.
transfer.
minimumAmount
string
No
The minimum amount to be entered by the debtor (if editable)
payment.
debtor.
bankCode
number
No
2 digits number from a closed list of supported bank codes. Represents the selected debtor bank.
Accepted only if debtor.account is not sent
payment.
debtor.
aspspChannel
string
No
the online channel on which the debtor account is managed: - -“private”
-“business”
-“corporate”
Accepted only if debtor.account is not sent
flow.
payment.
debtor.
aspspChannelEditable
boolean
No
If false: do not allow changing the value sent with “aspspChannel"/flags. If true, the debtor will be able to edit the value sent in "aspspChannel"/flags.
payment.
debtor.
account
string
No
debtor account number (iban/bban format).
-account number in BBAN format: xx-yyy-zzzzzz
Where xx=bank code, YYY=branch number, zzzzzz=account number (at list 6 digits)
-Account number in IBAN format
payment.
debtor.
accountType
string
No
debtor account number format
-IBAN
-BBAN
payment.
debtor.
editable
string
No
If true: the debtor may edit the debtor details sent. Defaults to “false”.
-True
-False

Production payments can only be sent to creditor accounts that Feezback has whitelisted. If the account is not approved, the request may fail with a creditor-account whitelist error.


Configure flow.redirects

  • Your urls to redirect the debtor to at the end of the process (optional)
  • If not set, the flow will end at Feezback's Success/Rejection screen.
  • URLs may not exceed 128 characters

FieldTypeDescription
flow.redirects.pisSuccess
string (URL)
URL to redirect the user after a successful transfer authorization.
flow.redirects.pisFailure
string (URL)
URL to redirect the user if transfer authorization fails.
flow.redirects.pisNotComplete
string (URL)
URL to redirect the user if transfer authorization awaits further approval.
flow.redirects.ttlExpired
string (URL)
URL to redirect the user if transfer link expired.

Flags

If you use flags, place them at the top level of the JWT, outside flow.
*A common integration mistake is nesting flags inside flow.

{
  "encrypt": true,
  "sub": "user-123",
  "iss": "tpp/{TPP_ID}",
  "srv": "fast/user",
  "flags": {
    "maskAccount": true
  },
  "flow": {
    "id": "default"
  }
}

FieldTypeDescription
privateAccountbooleanset default psuIdType to ‘private’. Accepted only if debtor.account is sent
businessAccountbooleanset default psuIdType to ‘business’. Accepted only if debtor.account is sent
corporateAccountbooleanset default psuIdType to ‘corporate’. Accepted only if debtor.account is sent
maskAccountbooleanif true: debtorAccount number will be masked on the UI (if received in the JWT).
displaySuccessScreenbooleansend “false” to skip Feezback’s success screen and redirect the user directly to the pisSuccess URL

Updated 12 days ago

Did this page help you?