Skip to main content
POST
/
api
/
v2.1
/
fintrans
/
{accountId}
/
payment-consents
/
types
/
{operationType}
Create payment consent
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --header 'deviceId: <deviceid>' \
  --header 'platform: <platform>' \
  --data '
{
  "maxAmount": {
    "value": "50000",
    "currency": "EUR",
    "scale": 2
  },
  "allowedBeneficiaries": [
    "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
  ],
  "validFrom": "2026-03-26T00:00:00.000Z",
  "validUntil": "2027-03-26T00:00:00.000Z",
  "description": "Transfer processing consent for organization payments",
  "title": "Business Payment Consent",
  "paymentType": "TRANSFER",
  "parameters": {
    "maxAmount": 50000,
    "currency": "EUR",
    "allowedOperations": [
      "sepa_transfer_internal"
    ]
  }
}
'
{
  "code": 201,
  "data": {
    "consentId": "<string>",
    "id": "<string>",
    "operationType": "<string>",
    "status": "<string>",
    "walletId": "<string>",
    "accountId": "<string>",
    "message": "<string>"
  },
  "message": "Success"
}

​
Endpoint

POST /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}
This endpoint requires X-Forwarded-From and a device header. The backend accepts any of: deviceId, X-Device-Id, device-id.

​
Sample cURL

curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "metadata": {
      "parameters": {
        "validity": {
          "endDate": "2027-12-31",
          "startDate": "2025-10-01",
          "maxUsageCount": 100
        },
        "beneficiaries": {
          "requireBeneficiaryName": true,
          "allowedTypes": [
            "sepa_transfer_internal"
          ],
          "allowedAccounts": [
            "LT213320011000055860"
          ],
          "allowNewBeneficiaries": false
        },
        "limits": {
          "maxTransactionsPerDay": 10,
          "maxAmountPerTransaction": {
            "currency": "EUR",
            "amount": 10000
          },
          "maxAmountPerDay": {
            "currency": "EUR",
            "amount": 20000
          }
        }
      },
      "paymentType": "TRANSFER",
      "questions": {
        "question": "I consent to the processing",
        "answer": ""
      },
      "title": "Payment Consent"
    },
    "verificationData": {
      "consentVersion": "1.0",
      "scope": "Transfer processing",
      "consentPurpose": "Payment Consent"
    },
    "entityId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "verificationStatus": "PENDING",
    "entityType": "ORGANIZATION",
    "verificationType": "CONSENT",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "documentId": "59ddc658-7cfc-4dbe-ac82-c716330b44eb",
    "documentType": "PAYMENT_CONSENT"
  }'

​
Response Example

{
  "code": 200,
  "data": {
    "consentId": "f3822ff0-3986-4fef-84eb-7b517e657b6f",
    "id": "f3822ff0-3986-4fef-84eb-7b517e657b6f",
    "operationType": "transfer",
    "status": "APPROVED",
    "walletId": "d7d94804-4d8b-45af-862f-77cbcef740f4",
    "accountId": "d7d94804-4d8b-45af-862f-77cbcef740f4",
    "message": "Consent created successfully",
    "magicLinkToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Success"
}
Decode the magicLinkToken JWT and extract the answer field. That value is the authenticationCode required to execute a prepared operation.

​
Missing Headers Error Example

{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}

Headers

​
X-Tenant-ID
string
required
Example:

"tenant-demo-001"

​
X-User-ID
string
​
X-Forwarded-For
string
required

Client IP address

Example:

"127.0.0.1"

​
X-Forwarded-From
string
required

Client source identifier

Example:

"client-app"

​
platform
string
required

Client platform

Example:

"mobile"

​
deviceId
string
required

Device identifier

Example:

"device-demo-001"

​
Authorization
string
required

Bearer JWT

Example:

"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZW1vLXVzZXIifQ.demo-signature"

Path Parameters

​
accountId
string<uuid>
required
Example:

"00000000-0000-0000-0000-000000000000"

​
operationType
enum<string>
required

Operation kind for payment consent (aligned with wallet operation types)

Available options:
TRANSFER,
TOPUP,
EXTERNAL,
INTERNAL,
EXCHANGE,
WITHDRAW,
PAYMENT
Example:

"TRANSFER"

Body

application/json

Payment consent payload

Create payment consent request

​
maxAmount
object

Maximum amount configuration

Example:
{
  "value": "50000",
  "currency": "EUR",
  "scale": 2
}
​
allowedBeneficiaries
string[]

Allowed beneficiary identifiers

Example:
["aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"]
​
validFrom
string

Consent validity start date (YYYY-MM-DD)

Example:

"2026-03-26T00:00:00.000Z"

​
validUntil
string

Consent validity end date (YYYY-MM-DD)

Example:

"2027-03-26T00:00:00.000Z"

​
description
string

Human-readable consent description

Example:

"Transfer processing consent for organization payments"

​
title
string

Consent title

Example:

"Business Payment Consent"

​
paymentType
string

Payment type

Example:

"TRANSFER"

​
parameters
object

Advanced consent parameters

Response

Payment consent created

Standard API response wrapper with payment consent in data

​
code
integer<int32>

HTTP-style status code

Example:

201

​
data
object

Payment consent

​
message
string

Result message

Example:

"Success"