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.
Endpoint: POST /api/v2.1/fintrans/{accountId}/beneficiariesHeaders:Authorization: Bearer {jwt-token}
Content-Type: application/json
{
"partyType": "INDIVIDUAL_CUSTOMER",
"firstName": "Jane",
"lastName": "Smith",
"iban": "GB82WEST12345698765432",
"currency": "EUR",
"country": "GB",
"email": "[email protected]",
"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
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
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
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
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
