Create payment consent

Create a payment consent for a specific operation type

POST /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}

Create payment consent

cURL

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

201

{
  "code": 201,
  "data": {
    "consentId": "<string>",
    "id": "<string>",
    "operationType": "<string>",
    "status": "<string>",
    "walletId": "<string>",
    "accountId": "<string>",
    "message": "<string>",
    "magicLinkToken": "<string>"
  },
  "message": "Success"
}

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 '{
    "paymentType": "TRANSFER",
    "title": "Payment Consent for Transfer Operations",
    "description": "Consent for processing transfer transactions",
    "parameters": {
      "validity": {
        "startDate": "2026-01-01",
        "endDate": "2027-12-31",
        "maxUsageCount": 500
      },
      "beneficiaries": {
        "allowNewBeneficiaries": false,
        "requireBeneficiaryName": true,
        "allowedAccounts": [
          "DE89370400440532013000",
          "FR1420041010050500013M02606"
        ],
        "allowedTypes": ["SEPA", "INTERNAL"]
      },
      "limits": {
        "maxAmountPerTransaction": { "amount": 10000, "currency": "EUR" },
        "maxAmountPerDay": { "amount": 50000, "currency": "EUR" },
        "maxTransactionsPerDay": 50
      }
    }
  }'

Response Example

{
  "code": 200,
  "data": {
    "consentId": "d519e2da-0084-4021-b98e-4de7ecf2551e",
    "operationType": "TRANSFER",
    "status": "APPROVED",
    "accountId": "d7d94804-4d8b-45af-862f-77cbcef740f4",
    "message": "Consent created successfully",
    "magicLinkToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Success"
}

The magicLinkToken JWT contains an answer field with the authentication code needed for executing the prepared order. The consentId must be referenced when preparing and executing financial operations.

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

Show child attributes

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

Show child attributes

Response

201

application/json

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

Show child attributes

message · string

Result message

Example:

"Success"