Phase 7: Payment Operations

The final phase covers payment operations: adding beneficiaries, preparing orders, and executing transfers.

Payment Flow

Step 1: Add Beneficiary

Beneficiaries must be pre-registered before making transfers.

Request
Response

Endpoint: POST /api/v2.1/fintrans/{accountId}/beneficiariesHeaders:

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

Request Body:

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

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

Request
Response

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

Authorization: Bearer {jwt-token}

Status: 200 OK

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

Request
Response

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

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

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

Request
Response

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

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

Status: 200 OK

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

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

Request
Response

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

Authorization: Bearer {jwt-token}

Status: 200 OK

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

Error Handling

Common errors and troubleshooting

Best Practices

Implementation best practices

​Phase 7: Payment Operations

​Payment Flow

​Step 1: Add Beneficiary

​Beneficiary Party Types

​PEP Check Results

​Step 2: List Beneficiaries

​Step 3: Prepare Transfer Order

​Prepared Order Fields

​Step 4: Execute Transfer Order

​Order Status Flow

​Order Statuses

​Step 5: Check Order Status

​Transfer Types

​Fee Structure

​Complete Flow Summary

​Related Resources

Error Handling

Best Practices

Phase 7: Payment Operations

Payment Flow

Step 1: Add Beneficiary

Beneficiary Party Types

PEP Check Results

Step 2: List Beneficiaries

Step 3: Prepare Transfer Order

Prepared Order Fields

Step 4: Execute Transfer Order

Order Status Flow

Order Statuses

Step 5: Check Order Status

Transfer Types

Fee Structure

Complete Flow Summary

Related Resources