Phase 7: Payment Consent Setup

Create payment consents with limits and beneficiary restrictions

Phase 7: Payment Consent Setup

Payment consents define what transactions the organization can perform, including limits, allowed beneficiaries, and approval requirements.

Consent Types

Consent Type	Description
TRANSFER	Standard transfers to beneficiaries
RECURRING	Recurring/scheduled payments
BULK	Bulk payment processing
INTERNATIONAL	Cross-border transfers

---

Create Payment Consent

Request

Endpoint: POST /api/v2.1/fintrans/{walletId}/payment-consents/types/transfer

Headers:

Authorization: Bearer {jwt-token}
Content-Type: application/json

Request Body:

{
  "title": "Regular Business Payments Consent",
  "description": "Monthly supplier and vendor payments",
  "validFrom": "2026-01-15T00:00:00.000Z",
  "validTo": "2026-12-31T23:59:59.000Z",
  "maxUsageCount": 500,
  "limits": {
    "perTransaction": {
      "amount": 10000000,
      "currency": "EUR"
    },
    "perDay": {
      "amount": 20000000,
      "currency": "EUR"
    },
    "perMonth": {
      "amount": 50000000,
      "currency": "EUR"
    }
  },
  "beneficiaryRestrictions": {
    "allowedAccounts": [
      "GB82WEST12345698765432",
      "FR7612345678901234567890123",
      "DE89370400440532013000"
    ],
    "allowedTypes": ["INTERNAL", "SEPA", "SWIFT"],
    "allowNewBeneficiaries": false,
    "requireBeneficiaryName": true,
    "requireInvoiceReference": true
  },
  "frequencyLimit": {
    "maxTransactionsPerDay": 50,
    "maxTransactionsPerWeek": 200,
    "maxTransactionsPerMonth": 500
  },
  "approvalRequirements": {
    "requiresApproval": true,
    "approvalThreshold": 5000000,
    "approverRoles": ["TRANSACTION_APPROVER", "ADMIN_USER"],
    "minimumApprovers": 1
  }
}

Response

Status: 201 Created

{
  "code": 201,
  "message": "Payment consent created successfully",
  "data": {
    "id": "consent-3344e8400-e29b-41d4-a716-446655440200",
    "consentType": "PAYMENT_CONSENT",
    "status": "ACCEPTED",
    "title": "Regular Business Payments Consent",
    "validFrom": "2026-01-15T00:00:00.000Z",
    "validTo": "2026-12-31T23:59:59.000Z",
    "maxUsageCount": 500,
    "currentUsageCount": 0,
    "limits": {
      "perTransaction": { "amount": 10000000, "currency": "EUR" },
      "perDay": { "amount": 20000000, "currency": "EUR" },
      "perMonth": { "amount": 50000000, "currency": "EUR" }
    },
    "beneficiaryRestrictions": {
      "allowedAccounts": [...],
      "allowNewBeneficiaries": false
    },
    "frequencyLimit": {
      "maxTransactionsPerDay": 50,
      "maxTransactionsPerWeek": 200,
      "maxTransactionsPerMonth": 500
    },
    "approvalRequirements": {
      "requiresApproval": true,
      "approvalThreshold": 5000000
    },
    "createdAt": "2026-01-15T15:30:00.000Z"
  }
}

---

Consent Limits

Amount Format: All amounts are in minor units (cents). Example: 10000000 = €100,000.00

Limit Type	Description
perTransaction	Maximum amount per single transaction
perDay	Maximum total amount per day
perMonth	Maximum total amount per month

---

Beneficiary Restrictions

Field	Description
allowedAccounts	List of allowed beneficiary IBANs
allowedTypes	Allowed beneficiary types (INTERNAL, SEPA, SWIFT)
allowNewBeneficiaries	Allow payments to new beneficiaries
requireBeneficiaryName	Require beneficiary name verification
requireInvoiceReference	Require invoice reference for payments

When allowNewBeneficiaries is false, transactions to beneficiaries not in allowedAccounts will be rejected.

---

Approval Requirements

Field	Description
requiresApproval	Enable approval workflow
approvalThreshold	Amount threshold for approval (in cents)
approverRoles	Roles that can approve
minimumApprovers	Minimum number of approvers required

Approval Workflow

---

Frequency Limits

Limit	Description
maxTransactionsPerDay	Max transactions in 24 hours
maxTransactionsPerWeek	Max transactions in 7 days
maxTransactionsPerMonth	Max transactions in 30 days

---

List Payment Consents

Request

Endpoint: GET /api/v2.1/fintrans/{walletId}/payment-consents

Response

{
  "code": 200,
  "message": "Payment consents retrieved successfully",
  "data": [
    {
      "id": "consent-3344e8400-e29b-41d4-a716-446655440200",
      "title": "Regular Business Payments Consent",
      "status": "ACCEPTED",
      "validFrom": "2026-01-15T00:00:00.000Z",
      "validTo": "2026-12-31T23:59:59.000Z",
      "currentUsageCount": 5,
      "maxUsageCount": 500
    }
  ]
}

---

Next Step

After setting up payment consents, proceed to Phase 8: Transaction Operations.

Phase 8: Transaction Operations

Execute transfers and manage transactions