FinHub
Open Developer Portal

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

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
Authorization: Bearer {jwt-token}
Content-Type: application/json

Request Body:

json
{
  "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
{
  "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 TypeDescription
INDIVIDUAL_CUSTOMERPersonal beneficiary
BUSINESS_CUSTOMERBusiness beneficiary

PEP Check Results

ResultDescription
VERIFIEDPEP check passed
PENDINGPEP check in progress
FLAGGEDRequires additional review

Step 2: List Beneficiaries

Endpoint: GET /api/v2.1/fintrans/{accountId}/beneficiaries

Headers:

http
Authorization: Bearer {jwt-token}

Status: 200 OK

json
{
  "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
{
  "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
{
  "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

FieldDescription
preparedOrderIdID for executing the order
amountTransfer amount
feesTransaction fees
totalAmountAmount + fees
validUntilOrder expiry time

Step 4: Execute Transfer Order

Endpoint: POST /api/v2.1/fintrans/{accountId}/types/transfer/execute

Request Body:

json
{
  "preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
  "consentConfirmation": {
    "confirmed": true,
    "confirmationMethod": "EXPLICIT",
    "confirmationTimestamp": "2026-01-14T15:45:00.000Z"
  }
}

Status: 200 OK

json
{
  "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

flowchart LR
    A[PREPARED] --> B[EXECUTING]
    B --> C{Outcome}
    C -->|Success| D[COMPLETED]
    C -->|Failure| E[FAILED]
    C -->|Cancelled| F[CANCELLED]

Order Statuses

StatusDescription
PREPAREDOrder created, awaiting execution
EXECUTINGOrder being processed
COMPLETEDOrder successfully completed
FAILEDOrder failed
CANCELLEDOrder cancelled

Step 5: Check Order Status

Endpoint: GET /api/v2.1/fintrans/{accountId}/orders/{orderId}

Headers:

http
Authorization: Bearer {jwt-token}

Status: 200 OK

json
{
  "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

TypeEndpoint SuffixDescription
Transfer/types/transfer/prepareStandard transfer
Topup/types/topup/prepareAdd funds to wallet
Payment/types/payment/prepareMake a payment

Fee Structure

Transaction TypeFee
SEPA Transfer€1.50
SWIFT Transfer€15.00
Internal TransferFree

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

Common errors and troubleshooting

Best Practices

Implementation best practices

Type to search…

↑↓ navigate ↵ open esc close