URL: /baas/api/integration/flows/organization-customer/payment-consent-setup

---
title: 'Phase 7: Payment Consent Setup'
description: '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

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{walletId}/payment-consents/types/transfer`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "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
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `201 Created`

    ```json
    {
      "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"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Consent Limits

<Info>
  **Amount Format:** All amounts are in minor units (cents). Example: `10000000` = €100,000.00
</Info>

| 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 |

<Warning>
  When `allowNewBeneficiaries` is `false`, transactions to beneficiaries not in `allowedAccounts` will be rejected.
</Warning>

---

## 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

```mermaid
flowchart LR
    A[Transaction Initiated] --> B{Amount > Threshold?}
    B -->|No| C[Auto-Approved]
    B -->|Yes| D[Pending Approval]
    D --> E{Approver Action}
    E -->|Approve| F[Executed]
    E -->|Reject| G[Rejected]
```

---

## 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

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{walletId}/payment-consents`
  </Tab>
  <Tab title="Response">
    ```json
    {
      "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
        }
      ]
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

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

<Card title="Phase 8: Transaction Operations" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/transaction-operations">
  Execute transfers and manage transactions
</Card>