> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Create payment consent

> Create a payment consent and receive a magicLinkToken containing the authentication code for execution.

## Endpoint

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

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash theme={null}
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

```json theme={null}
{
  "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"
}
```

<Note>
  Decode the `magicLinkToken` JWT and extract the `answer` field. That value is the `authenticationCode` required to execute a prepared operation.
</Note>

## Missing Headers Error Example

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


## OpenAPI

````yaml openapi.yaml POST /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}
openapi: 3.1.0
info:
  title: Business BFF API
  version: 1.0.0
  description: Backend for Frontend - Business Panels Orchestration Layer
servers:
  - url: https://sandbox.finhub.cloud
    description: Sandbox Environment
security: []
tags:
  - name: AML
    description: Anti-Money Laundering checks and transaction monitoring
  - name: Admin - Consent Management
    description: Operations for managing consent templates and definitions
  - name: B2B Customer - Organization
    description: B2B organization registration and management
  - name: B2C Customer - Individual
    description: Individual customer registration and lifecycle management
  - name: BFF Admin - Tenant Initialization
    description: Lazy tenant initialization for fast startup
  - name: Catalog Hierarchy
    description: Hierarchical catalog management APIs
  - name: Catalog-Process Mapping
    description: APIs for catalog-process relationship management
  - name: Consent
    description: Payment consent creation and approval
  - name: Draft Management
  - name: External Events
    description: Kafka-to-HTTP bridge event ingestion and query
  - name: FinCard Virtual - Webhooks
    description: FinCard Virtual Card Webhook receiver
  - name: FinCard Virtual Account
    description: FinCard Virtual Card Account API proxy
  - name: FinCard Virtual Card Holder
    description: FinCard Virtual Card Holder API proxy
  - name: FinCard Virtual Cards
    description: FinCard Virtual Card API proxy
  - name: FinCard Virtual Common
    description: FinCard Virtual Card Common API proxy
  - name: FinCard Virtual Wallet
    description: FinCard Virtual Card Wallet API v2 proxy
  - name: FinTrans - Operations
    description: Financial transaction operations
  - name: Internal Webhooks
    description: Internal service-to-service webhook trigger (HMAC-secured)
  - name: MFE Preload
    description: MFE preload endpoints for SSR optimization
  - name: MFE Registry
    description: MFE Registry management endpoints
  - name: Payment Consent Management
    description: Operations for managing payment consents and validation
  - name: Person
    description: Person details for process context
  - name: Products
    description: Product Catalog Management API
  - name: Reference Data
    description: Shared reference data (countries, etc.)
  - name: Tenant Lifecycle
    description: Tenant mode transitions and lifecycle management
  - name: Tenant Registration
    description: Self-registration and tenant onboarding
  - name: Transfers
    description: Transfer prepare/execute aliases for muse-proxy compatibility
  - name: Verification
    description: Customer verification (KYC/KYB/AML) management
  - name: Wallet
    description: Wallet operations and balance management
  - name: Webhooks
    description: Webhook subscription and delivery management
paths:
  /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}:
    post:
      tags:
        - FinTrans - Operations
      summary: Create payment consent
      description: Create a payment consent for a specific operation type
      parameters:
        - name: accountId
          schema:
            type: string
            format: uuid
            examples:
              - 00000000-0000-0000-0000-000000000000
          in: path
          required: true
        - description: >-
            Operation kind for payment consent (aligned with wallet operation
            types)
          name: operationType
          schema:
            enum:
              - TRANSFER
              - TOPUP
              - EXTERNAL
              - INTERNAL
              - EXCHANGE
              - WITHDRAW
              - PAYMENT
            examples:
              - TRANSFER
          in: path
          required: true
        - name: X-Tenant-ID
          in: header
          required: true
          schema:
            type: string
            example: tenant-demo-001
        - name: X-User-ID
          in: header
          required: false
          schema:
            type: string
        - name: X-Forwarded-For
          in: header
          required: true
          description: Client IP address
          schema:
            type: string
            example: 127.0.0.1
        - name: X-Forwarded-From
          in: header
          required: true
          description: Client source identifier
          schema:
            type: string
            example: client-app
        - name: platform
          in: header
          required: true
          description: Client platform
          schema:
            type: string
            example: mobile
        - name: deviceId
          in: header
          required: true
          description: Device identifier
          schema:
            type: string
            example: device-demo-001
        - name: Authorization
          in: header
          required: true
          description: Bearer JWT
          schema:
            type: string
            example: >-
              Bearer
              eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZW1vLXVzZXIifQ.demo-signature
      requestBody:
        description: Payment consent payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentConsentRequest'
        required: true
      responses:
        '201':
          description: Payment consent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponsePaymentConsentResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
components:
  schemas:
    CreatePaymentConsentRequest:
      type: object
      description: Create payment consent request
      properties:
        maxAmount:
          $ref: '#/components/schemas/AmountRequest'
          type: object
          examples:
            - value: '50000'
              currency: EUR
              scale: 2
          description: Maximum amount configuration
          x-mint: '{"group":"createpaymentconsentrequest","order":1}'
          example:
            value: '50000'
            currency: EUR
            scale: 2
        allowedBeneficiaries:
          type: array
          examples:
            - - aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
          items:
            type: string
          description: Allowed beneficiary identifiers
          x-mint: '{"group":"createpaymentconsentrequest","order":2}'
          example:
            - aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
        validFrom:
          type: string
          examples:
            - '2026-03-26T00:00:00.000Z'
          description: Consent validity start date (YYYY-MM-DD)
          x-mint: '{"group":"createpaymentconsentrequest","order":3}'
          example: '2026-03-26T00:00:00.000Z'
        validUntil:
          type: string
          examples:
            - '2027-03-26T00:00:00.000Z'
          description: Consent validity end date (YYYY-MM-DD)
          x-mint: '{"group":"createpaymentconsentrequest","order":4}'
          example: '2027-03-26T00:00:00.000Z'
        description:
          type: string
          examples:
            - Transfer processing consent for organization payments
          description: Human-readable consent description
          x-mint: '{"group":"createpaymentconsentrequest","order":5}'
          example: Transfer processing consent for organization payments
        title:
          type: string
          examples:
            - Business Payment Consent
          description: Consent title
          x-mint: '{"group":"createpaymentconsentrequest","order":6}'
          example: Business Payment Consent
        paymentType:
          type: string
          examples:
            - TRANSFER
          description: Payment type
          x-mint: '{"group":"createpaymentconsentrequest","order":7}'
          example: TRANSFER
        parameters:
          $ref: '#/components/schemas/ConsentParameters'
          type: object
          description: Advanced consent parameters
          x-mint: '{"group":"createpaymentconsentrequest","order":8}'
    BaseResponsePaymentConsentResponse:
      type: object
      description: Standard API response wrapper with payment consent in data
      properties:
        code:
          type: integer
          format: int32
          examples:
            - 201
          description: HTTP-style status code
          example: 201
        data:
          $ref: '#/components/schemas/PaymentConsentResponse'
          type: object
          description: Payment consent
        message:
          type: string
          examples:
            - Success
          description: Result message
          example: Success
    AmountRequest:
      type: object
      properties:
        value:
          type: string
        scale:
          type: integer
          format: int32
        currency:
          type: string
    ConsentParameters:
      type: object
      properties:
        maxAmount:
          type: integer
          format: int32
          examples:
            - 50000
          description: Maximum permitted amount
          x-mint: '{"group":"createpaymentconsentrequest.consentparameters","order":1}'
          example: 50000
        currency:
          type: string
          examples:
            - EUR
          description: Currency for monetary limits
          x-mint: '{"group":"createpaymentconsentrequest.consentparameters","order":2}'
          example: EUR
        allowedOperations:
          type: array
          examples:
            - - sepa_transfer_internal
          items:
            type: string
          description: Allowed operation types
          x-mint: '{"group":"createpaymentconsentrequest.consentparameters","order":3}'
          example:
            - sepa_transfer_internal
    PaymentConsentResponse:
      type: object
      description: Payment consent response payload
      properties:
        consentId:
          type: string
        id:
          type: string
        operationType:
          type: string
        status:
          type: string
        walletId:
          type: string
        accountId:
          type: string
        message:
          type: string
        magicLinkToken:
          type: string

````