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"
    ]
  }
}
'
import requests

url = "https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}"

payload = {
    "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"]
    }
}
headers = {
    "X-Tenant-ID": "<x-tenant-id>",
    "X-Forwarded-For": "<x-forwarded-for>",
    "X-Forwarded-From": "<x-forwarded-from>",
    "platform": "<platform>",
    "deviceId": "<deviceid>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    'X-Tenant-ID': '<x-tenant-id>',
    'X-Forwarded-For': '<x-forwarded-for>',
    'X-Forwarded-From': '<x-forwarded-from>',
    platform: '<platform>',
    deviceId: '<deviceid>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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']
    }
  })
};

fetch('https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "X-Forwarded-For: <x-forwarded-for>",
    "X-Forwarded-From: <x-forwarded-from>",
    "X-Tenant-ID: <x-tenant-id>",
    "deviceId: <deviceid>",
    "platform: <platform>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}"

	payload := strings.NewReader("{\n  \"maxAmount\": {\n    \"value\": \"50000\",\n    \"currency\": \"EUR\",\n    \"scale\": 2\n  },\n  \"allowedBeneficiaries\": [\n    \"aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee\"\n  ],\n  \"validFrom\": \"2026-03-26T00:00:00.000Z\",\n  \"validUntil\": \"2027-03-26T00:00:00.000Z\",\n  \"description\": \"Transfer processing consent for organization payments\",\n  \"title\": \"Business Payment Consent\",\n  \"paymentType\": \"TRANSFER\",\n  \"parameters\": {\n    \"maxAmount\": 50000,\n    \"currency\": \"EUR\",\n    \"allowedOperations\": [\n      \"sepa_transfer_internal\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Tenant-ID", "<x-tenant-id>")
	req.Header.Add("X-Forwarded-For", "<x-forwarded-for>")
	req.Header.Add("X-Forwarded-From", "<x-forwarded-from>")
	req.Header.Add("platform", "<platform>")
	req.Header.Add("deviceId", "<deviceid>")
	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}")
  .header("X-Tenant-ID", "<x-tenant-id>")
  .header("X-Forwarded-For", "<x-forwarded-for>")
  .header("X-Forwarded-From", "<x-forwarded-from>")
  .header("platform", "<platform>")
  .header("deviceId", "<deviceid>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"maxAmount\": {\n    \"value\": \"50000\",\n    \"currency\": \"EUR\",\n    \"scale\": 2\n  },\n  \"allowedBeneficiaries\": [\n    \"aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee\"\n  ],\n  \"validFrom\": \"2026-03-26T00:00:00.000Z\",\n  \"validUntil\": \"2027-03-26T00:00:00.000Z\",\n  \"description\": \"Transfer processing consent for organization payments\",\n  \"title\": \"Business Payment Consent\",\n  \"paymentType\": \"TRANSFER\",\n  \"parameters\": {\n    \"maxAmount\": 50000,\n    \"currency\": \"EUR\",\n    \"allowedOperations\": [\n      \"sepa_transfer_internal\"\n    ]\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Tenant-ID"] = '<x-tenant-id>'
request["X-Forwarded-For"] = '<x-forwarded-for>'
request["X-Forwarded-From"] = '<x-forwarded-from>'
request["platform"] = '<platform>'
request["deviceId"] = '<deviceid>'
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"maxAmount\": {\n    \"value\": \"50000\",\n    \"currency\": \"EUR\",\n    \"scale\": 2\n  },\n  \"allowedBeneficiaries\": [\n    \"aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee\"\n  ],\n  \"validFrom\": \"2026-03-26T00:00:00.000Z\",\n  \"validUntil\": \"2027-03-26T00:00:00.000Z\",\n  \"description\": \"Transfer processing consent for organization payments\",\n  \"title\": \"Business Payment Consent\",\n  \"paymentType\": \"TRANSFER\",\n  \"parameters\": {\n    \"maxAmount\": 50000,\n    \"currency\": \"EUR\",\n    \"allowedOperations\": [\n      \"sepa_transfer_internal\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "code": 201,
  "data": {
    "consentId": "<string>",
    "id": "<string>",
    "operationType": "<string>",
    "status": "<string>",
    "walletId": "<string>",
    "accountId": "<string>",
    "message": "<string>",
    "magicLinkToken": "<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"