> ## 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 Operations
> Add beneficiaries, prepare orders, and execute transfers
# Phase 7: Payment Operations
The final phase covers payment operations: adding beneficiaries, preparing orders, and executing transfers.
## Payment Flow
```mermaid theme={null}
flowchart LR
A[Add Beneficiary] --> B[Prepare Order]
B --> C[Execute Order]
C --> D[Monitor Status]
style A fill:#e3f2fd
style B fill:#fff8e1
style C fill:#e8f5e9
style D fill:#e8f5e9
```
***
## Step 1: Add Beneficiary
Beneficiaries must be pre-registered before making transfers.
**Endpoint:** `POST /api/v2.1/fintrans/{accountId}/beneficiaries`
**Headers:**
```http theme={null}
Authorization: Bearer {jwt-token}
Content-Type: application/json
```
**Request Body:**
```json theme={null}
{
"partyType": "INDIVIDUAL_CUSTOMER",
"firstName": "Jane",
"lastName": "Smith",
"iban": "GB82WEST12345698765432",
"currency": "EUR",
"country": "GB",
"email": "jane.smith@example.com",
"phoneNumber": "+442071234567",
"shortName": "Jane S",
"bicSwiftCode": "WESTGB21",
"networkName": "SEPA",
"bankName": "Westminster Bank",
"bankAddress": "London, UK",
"purposeCode": "FAMILY_SUPPORT"
}
```
**Status:** `201 Created`
```json theme={null}
{
"code": 201,
"message": "Beneficiary created successfully",
"data": {
"beneficiaryId": "benef-cc0e8400-e29b-41d4-a716-446655440060",
"accountId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
"partyType": "INDIVIDUAL_CUSTOMER",
"beneficiaryName": "Jane Smith",
"iban": "GB82WEST12345698765432",
"bic": "WESTGB21",
"bicType": "external",
"currency": "EUR",
"country": "GB",
"networkName": "SEPA",
"pepCheckResult": "VERIFIED",
"status": "active",
"createdAt": "2026-01-14T15:00:00.000Z"
}
}
```
### Beneficiary Party Types
| Party Type | Description |
| --------------------- | -------------------- |
| `INDIVIDUAL_CUSTOMER` | Personal beneficiary |
| `BUSINESS_CUSTOMER` | Business beneficiary |
### PEP Check Results
| Result | Description |
| ---------- | -------------------------- |
| `VERIFIED` | PEP check passed |
| `PENDING` | PEP check in progress |
| `FLAGGED` | Requires additional review |
***
## Step 2: List Beneficiaries
**Endpoint:** `GET /api/v2.1/fintrans/{accountId}/beneficiaries`
**Headers:**
```http theme={null}
Authorization: Bearer {jwt-token}
```
**Status:** `200 OK`
```json theme={null}
{
"code": 200,
"message": "Beneficiaries retrieved successfully",
"data": [
{
"beneficiaryId": "benef-cc0e8400-e29b-41d4-a716-446655440060",
"beneficiaryName": "Jane Smith",
"iban": "GB82WEST12345698765432",
"network": "SEPA",
"status": "active",
"lastUsed": null
}
]
}
```
***
## Step 3: Prepare Transfer Order
**Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/prepare`
**Request Body:**
```json theme={null}
{
"sourceAccount": {
"walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
"iban": "FR7630001007941234567890185"
},
"targetAccount": {
"iban": "GB82WEST12345698765432",
"beneficiaryName": "Jane Smith",
"bic": "WESTGB21"
},
"amount": {
"value": "100000",
"currency": "EUR"
},
"description": "Family support payment",
"reference": "FAM-2026-001"
}
```
**Status:** `200 OK`
```json theme={null}
{
"code": 200,
"message": "Order prepared successfully",
"data": {
"preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
"operationType": "TRANSFER",
"status": "PREPARED",
"amount": {
"value": "100000",
"valueFormatted": "1000.00",
"currency": "EUR"
},
"fees": {
"value": "150",
"valueFormatted": "1.50",
"currency": "EUR"
},
"totalAmount": {
"value": "100150",
"valueFormatted": "1001.50",
"currency": "EUR"
},
"estimatedExecutionTime": "2026-01-14T16:00:00.000Z",
"validUntil": "2026-01-14T18:00:00.000Z",
"warnings": [],
"requiredApprovals": []
}
}
```
### Prepared Order Fields
| Field | Description |
| ----------------- | -------------------------- |
| `preparedOrderId` | ID for executing the order |
| `amount` | Transfer amount |
| `fees` | Transaction fees |
| `totalAmount` | Amount + fees |
| `validUntil` | Order expiry time |
**Order Validity:** Prepared orders expire after 2-3 hours. Execute before `validUntil` timestamp.
***
## Step 4: Execute Transfer Order
**Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/execute`
**Request Body:**
```json theme={null}
{
"preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
"consentConfirmation": {
"confirmed": true,
"confirmationMethod": "EXPLICIT",
"confirmationTimestamp": "2026-01-14T15:45:00.000Z"
}
}
```
**Status:** `200 OK`
```json theme={null}
{
"code": 200,
"message": "Order executed successfully",
"data": {
"executionId": "exec-ee0e8400-e29b-41d4-a716-446655440080",
"orderId": "order-ff0e8400-e29b-41d4-a716-446655440081",
"preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
"status": "EXECUTING",
"executionTimestamp": "2026-01-14T15:45:30.000Z",
"estimatedCompletionTime": "2026-01-14T16:00:00.000Z",
"transactionReference": "TXN-20260114-001",
"confirmationNumber": "CNF-20260114-001"
}
}
```
***
## Order Status Flow
```mermaid theme={null}
flowchart LR
A[PREPARED] --> B[EXECUTING]
B --> C{Outcome}
C -->|Success| D[COMPLETED]
C -->|Failure| E[FAILED]
C -->|Cancelled| F[CANCELLED]
```
### Order Statuses
| Status | Description |
| ----------- | --------------------------------- |
| `PREPARED` | Order created, awaiting execution |
| `EXECUTING` | Order being processed |
| `COMPLETED` | Order successfully completed |
| `FAILED` | Order failed |
| `CANCELLED` | Order cancelled |
***
## Step 5: Check Order Status
**Endpoint:** `GET /api/v2.1/fintrans/{accountId}/orders/{orderId}`
**Headers:**
```http theme={null}
Authorization: Bearer {jwt-token}
```
**Status:** `200 OK`
```json theme={null}
{
"code": 200,
"message": "Order retrieved successfully",
"data": {
"orderId": "order-ff0e8400-e29b-41d4-a716-446655440081",
"operationType": "TRANSFER",
"status": "COMPLETED",
"amount": "100000",
"amountFormatted": "1000.00",
"currency": "EUR",
"fees": "150",
"feesFormatted": "1.50",
"beneficiaryName": "Jane Smith",
"beneficiaryIban": "GB82WEST12345698765432",
"reference": "FAM-2026-001",
"transactionReference": "TXN-20260114-001",
"createdAt": "2026-01-14T15:45:00.000Z",
"executedAt": "2026-01-14T15:45:30.000Z",
"completedAt": "2026-01-14T15:50:00.000Z"
}
}
```
***
## Transfer Types
| Type | Endpoint Suffix | Description |
| -------- | ------------------------- | ------------------- |
| Transfer | `/types/transfer/prepare` | Standard transfer |
| Topup | `/types/topup/prepare` | Add funds to wallet |
| Payment | `/types/payment/prepare` | Make a payment |
***
## Fee Structure
| Transaction Type | Fee |
| ----------------- | ------ |
| SEPA Transfer | €1.50 |
| SWIFT Transfer | €15.00 |
| Internal Transfer | Free |
***
## Complete Flow Summary
```
┌─────────────────────────────────────────────────────────────┐
│ INDIVIDUAL CUSTOMER COMPLETE LIFECYCLE │
└─────────────────────────────────────────────────────────────┘
Phase 1: Registration (5 min)
└─→ Customer + User + Wallet created
Phase 2: Session (instant)
└─→ JWT token for API calls
Phase 3: Verification (1-3 days)
└─→ KYC documents submitted and approved
Phase 4: Consents (5 min)
└─→ Terms, Privacy, Data Processing accepted
Phase 5: Activation (instant)
└─→ IBAN generated, wallet activated
Phase 6: Wallet Operations (ongoing)
└─→ Balance queries, limits check
Phase 7: Payment Operations (ongoing)
└─→ Beneficiaries, transfers, payments
```
***
## Related Resources
Common errors and troubleshooting
Implementation best practices