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

# 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

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

    **Headers:**

    ```http theme={null}
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**

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