Payment Consents API

APIs for creating, validating, and managing payment consents and transaction approvals. Payment consents provide authorization framework for recurring payments and transfers.

Base URL: https://sandbox.finhub.cloud/api/v2.1/fintrans

For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

Why Payment Consents Matter

Payment consents provide pre-authorization for financial operations: Benefits:

✅ Faster transaction processing (no manual approval each time)
✅ Automated recurring payments
✅ Controlled spending with limits
✅ Beneficiary restrictions
✅ Audit trail for compliance

Use Cases:

Recurring supplier payments
Salary disbursements
Subscription payments
Automated invoice payments

Prerequisites

Before creating payment consents:

Account must be ACTIVATED
Beneficiaries pre-registered (if using beneficiary restrictions)
User has appropriate role (ADMIN_USER or TRANSACTION_APPROVER)

Available Operations

Create Consent

POST /payment/consent

Validate Payment

POST /payment/consent/validate

Get Pending

GET /consents/pending

Sign Consent

POST /consents/{consentId}/sign

Production Endpoint: The actual working endpoint is
POST /fintrans/{walletId}/payment-consents/types/{operationType}This differs from the generic /payment/consent endpoint. Always use the wallet-specific endpoint.

Creates a new payment consent with comprehensive parameters including transaction limits, beneficiary restrictions, and validity periods.

Endpoint

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

Path Parameters

walletId

string

required

Wallet/Account identifier
Example: wallet_abc123

operationType

string

required

Operation type for the consent
Valid Values: transfer, payment, withdrawal, bill_payment

Headers

Authorization

string

required

Bearer token for authentication

X-Tenant-ID

string

required

Tenant identifier

Content-Type

string

required

Must be application/json

Request Body

paymentType

string

required

Payment type classificationValid Values:

TRANSFER - Standard transfer operations
BILL_PAYMENT - Bill payment operations
RECURRING - Recurring/subscription payments
INTERNATIONAL - International transfers

title

string

required

Human-readable consent titleExample: "Business Payment Consent for Transfers"

description

string

Detailed description of consent purposeExample: "Monthly supplier payments with €50K limit"

parameters

object

required

Consent parameters object containing validity, limits, and restrictions

Show parameters structure

validity

object

required

Validity period configuration

Show validity properties

startDate

string

required

Consent start date (ISO 8601 format)Example: "2026-01-13T00:00:00Z"

endDate

string

required

Consent end date (ISO 8601 format)Example: "2026-12-31T23:59:59Z"

maxUsageCount

integer

Maximum number of times consent can be usedExample: 500

limits

object

required

Transaction limit configuration

Show limits properties

maxAmountPerTransaction

object

required

Maximum amount per single transactionStructure: { "amount": 10000, "currency": "EUR" }

maxAmountPerDay

object

required

Maximum cumulative amount per dayStructure: { "amount": 50000, "currency": "EUR" }

maxAmountPerMonth

object

required

Maximum cumulative amount per monthStructure: { "amount": 200000, "currency": "EUR" }

maxTransactionsPerDay

integer

Maximum number of transactions per dayExample: 50

maxTransactionsPerWeek

integer

Maximum number of transactions per weekExample: 250

beneficiaries

object

Beneficiary restriction configuration

Show beneficiaries properties

allowedAccounts

array

Whitelist of allowed beneficiary IBANs or IDsExample: ["LT123456789...", "LT987654321..."]

allowedTypes

array

Allowed transfer typesValid Values: ["INTERNAL", "SEPA", "SWIFT"]

allowNewBeneficiaries

boolean

Whether new beneficiaries can be addedExample: false (strict mode)

requireBeneficiaryName

boolean

Whether beneficiary name validation is requiredExample: true

validityPeriod

string

ISO 8601 duration formatExamples:

"P30D" - 30 days
"P3M" - 3 months
"P1Y" - 1 year

validUntil

string

Alternative expiration timestamp (ISO 8601)Example: "2026-12-31T23:59:59Z"

Complete Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/wallet_abc123/payment-consents/types/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentType": "TRANSFER",
    "title": "Business Payment Consent for Transfers",
    "description": "Monthly supplier payments with controlled limits",
    "parameters": {
      "validity": {
        "startDate": "2026-01-13T00:00:00Z",
        "endDate": "2026-12-31T23:59:59Z",
        "maxUsageCount": 500
      },
      "limits": {
        "maxAmountPerTransaction": {
          "amount": 10000,
          "currency": "EUR"
        },
        "maxAmountPerDay": {
          "amount": 50000,
          "currency": "EUR"
        },
        "maxAmountPerMonth": {
          "amount": 200000,
          "currency": "EUR"
        },
        "maxTransactionsPerDay": 50,
        "maxTransactionsPerWeek": 250
      },
      "beneficiaries": {
        "allowedTypes": ["INTERNAL", "SEPA", "SWIFT"],
        "allowNewBeneficiaries": true,
        "requireBeneficiaryName": true
      }
    },
    "validityPeriod": "P1Y",
    "validUntil": "2026-12-31T23:59:59Z"
  }'

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/wallet_abc123/payment-consents/types/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentType": "TRANSFER",
    "title": "Restricted Supplier Payment Consent",
    "description": "Payments only to approved suppliers",
    "parameters": {
      "validity": {
        "startDate": "2026-01-13T00:00:00Z",
        "endDate": "2026-06-30T23:59:59Z",
        "maxUsageCount": 100
      },
      "limits": {
        "maxAmountPerTransaction": {
          "amount": 5000,
          "currency": "EUR"
        },
        "maxAmountPerDay": {
          "amount": 20000,
          "currency": "EUR"
        },
        "maxAmountPerMonth": {
          "amount": 80000,
          "currency": "EUR"
        },
        "maxTransactionsPerDay": 10,
        "maxTransactionsPerWeek": 50
      },
      "beneficiaries": {
        "allowedAccounts": [
          "LT123456789012345678",
          "LT987654321098765432"
        ],
        "allowedTypes": ["SEPA"],
        "allowNewBeneficiaries": false,
        "requireBeneficiaryName": true
      }
    },
    "validityPeriod": "P6M"
  }'

{
  "code": 201,
  "message": "Payment consent created successfully",
  "data": {
    "consentId": "pcons_7f8a9b0c1d",
    "walletId": "wallet_abc123",
    "paymentType": "TRANSFER",
    "status": "ACTIVE",
    "title": "Business Payment Consent for Transfers",
    "parameters": {
      "validity": {
        "startDate": "2026-01-13T00:00:00Z",
        "endDate": "2026-12-31T23:59:59Z",
        "maxUsageCount": 500,
        "currentUsageCount": 0
      },
      "limits": {
        "maxAmountPerTransaction": { "amount": 10000, "currency": "EUR" },
        "maxAmountPerDay": { "amount": 50000, "currency": "EUR" },
        "maxAmountPerMonth": { "amount": 200000, "currency": "EUR" },
        "remainingDailyLimit": { "amount": 50000, "currency": "EUR" },
        "remainingMonthlyLimit": { "amount": 200000, "currency": "EUR" }
      },
      "beneficiaries": {
        "allowedTypes": ["INTERNAL", "SEPA", "SWIFT"],
        "allowNewBeneficiaries": true,
        "requireBeneficiaryName": true
      }
    },
    "createdAt": "2026-01-13T10:30:00Z",
    "updatedAt": "2026-01-13T10:30:00Z",
    "createdBy": "user_admin123"
  }
}

Production Pattern: The response includes remainingDailyLimit and remainingMonthlyLimit which track available spending capacity. These values decrease as payments are made against the consent.

Validate Payment

Validates a payment request against active consent parameters.

Request

Consent identifier

amount

object

required

Payment amount to validate

beneficiaryId

string

Beneficiary identifier

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/payment/consent/validate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "consentId": "pcons_12345",
    "amount": {
      "value": 500.00,
      "currency": "EUR"
    },
    "beneficiaryId": "ben_67890"
  }'

{
  "success": true,
  "data": {
    "valid": true,
    "remainingLimit": {
      "value": 4500.00,
      "currency": "EUR"
    }
  }
}

Signs a consent request for approval.

Request

accountId

string

required

Account identifier

operationType

string

required

Operation type

Consent identifier

signatureMethod

string

required

Signature method: OTP, BIOMETRIC, DIGITAL

signatureValue

string

required

Signature value (e.g., OTP code)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/acc_12345/types/transfer/consents/pcons_12345/sign" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "signatureMethod": "OTP",
    "signatureValue": "123456"
  }'

{
  "success": true,
  "data": {
    "consentId": "pcons_12345",
    "signatureId": "sig_001",
    "status": "SIGNED",
    "signedAt": "2024-01-15T10:35:00Z"
  }
}

Limits

Control spending with transaction, daily, and monthly limits:

{
  "limits": {
    "perTransaction": {
      "amount": 10000,
      "currency": "EUR"
    },
    "perDay": {
      "amount": 50000,
      "currency": "EUR"
    },
    "perMonth": {
      "amount": 200000,
      "currency": "EUR"
    }
  }
}

Beneficiary Restrictions

Control who can receive payments:

{
  "beneficiaryRestrictions": {
    "allowedAccounts": ["ben_12345", "ben_67890"],
    "allowedTypes": ["INTERNAL", "SEPA"],
    "allowNewBeneficiaries": false,
    "requireBeneficiaryName": true,
    "requireInvoiceReference": true
  }
}

Frequency Limits

Control transaction frequency:

{
  "frequencyLimit": {
    "maxTransactionsPerDay": 10,
    "maxTransactionsPerWeek": 50,
    "maxTransactionsPerMonth": 200
  }
}

Approval Requirements

Require multi-level approvals for high-value transactions:

{
  "approvalRequirements": {
    "requiresApproval": true,
    "approvalThreshold": 50000,
    "approverRoles": ["COMPLIANCE_OFFICER", "ADMIN_USER"],
    "minimumApprovers": 2
  }
}

Status	Description	Can Use
ACCEPTED	Active and valid	✅ Yes
PENDING	Awaiting approval	❌ No
EXPIRED	Validity period ended	❌ No
REVOKED	Manually cancelled	❌ No
SUSPENDED	Temporarily disabled	❌ No

Response Codes

Code	Description
`200`	Consent validated successfully
`201`	Consent created successfully
`400`	Payment validation failed or invalid parameters
`403`	Insufficient permissions
`404`	Consent not found
`422`	Consent expired or revoked
`500`	Internal server error

API Schema Reference

For the complete OpenAPI schema specification, see the API Schema Mapping document.

Standard Headers

Complete HTTP headers reference

Beneficiaries

Manage payment beneficiaries

Transfers

Execute transfers using consents

Approvals

Manage transaction approvals

Changelog

Version	Date	Changes
v1.0	2026-01-13	Comprehensive payment consents documentation

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Payment Consents API

Payment Consents API

Why Payment Consents Matter

Prerequisites

Available Operations

Create Consent

Validate Payment

Get Pending

Sign Consent

Endpoint

Path Parameters

Headers

Request Body

Complete Code Examples

Validate Payment

Request

Code Examples

Request

Code Examples

Limits

Beneficiary Restrictions

Frequency Limits

Approval Requirements

Response Codes

API Schema Reference

Standard Headers

Beneficiaries

Transfers

Approvals

Changelog

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Payment Consents API

​Why Payment Consents Matter

​Prerequisites

​Available Operations

Create Consent

Validate Payment

Get Pending

Sign Consent

​Create Payment Consent (Production Endpoint)

​Endpoint

​Path Parameters

​Headers

​Request Body

​Complete Code Examples

​Example 1: Basic Transfer Consent

​Example 2: Strict Beneficiary-Restricted Consent

​Validate Payment

​Request

​Code Examples

​Sign Consent

​Request

​Code Examples

​Consent Parameters

​Limits

​Beneficiary Restrictions

​Frequency Limits

​Approval Requirements

​Consent Status

​Response Codes

​API Schema Reference

​Related Endpoints

Standard Headers

Beneficiaries

Transfers

Approvals

​Changelog

Payment Consents API

Why Payment Consents Matter

Prerequisites

Available Operations

Create Payment Consent (Production Endpoint)

Endpoint

Path Parameters

Headers

Request Body

Complete Code Examples

Example 1: Basic Transfer Consent

Example 2: Strict Beneficiary-Restricted Consent

Validate Payment

Request

Code Examples

Sign Consent

Request

Code Examples

Consent Parameters

Limits

Beneficiary Restrictions

Frequency Limits

Approval Requirements

Consent Status

Response Codes

API Schema Reference

Related Endpoints

Changelog