Phase 6: Beneficiary Management Business beneficiaries require additional information compared to individual beneficiaries, including business relationship details and enhanced due diligence data.
Prerequisites Requirement Status Organization Status ACTIVEWallet Status ACTIVEValid Session JWT token with appropriate role
Add Business Beneficiary Endpoint: POST /api/v2.1/fintrans/{accountId}/beneficiariesHeaders: Authorization : Bearer {jwt-token} Content-Type : application/json
Request Body: { "partyType" : "BUSINESS_CUSTOMER" , "companyName" : "Supplier Corporation Ltd" , "registrationNumber" : "REG-SUPP-001" , "taxId" : "TAX-SUPP-001" , "iban" : "GB82WEST12345698765432" , "currency" : "EUR" , "country" : "GB" , "email" : "[email protected] " , "phoneNumber" : "+442071234567" , "shortName" : "Supplier Corp" , "bicSwiftCode" : "WESTGB21" , "networkName" : "SEPA" , "bankName" : "Westminster Bank" , "bankAddress" : "London, UK" , "correspondentBankBic" : null , "correspondentBankName" : null , "purposeCode" : "INVOICE_PAYMENT" , "businessRelationship" : { "relationshipType" : "SUPPLIER" , "contractReference" : "CNT-2024-001" , "monthlyVolume" : "50000" , "averageTransactionSize" : "5000" }, "additionalData" : { "taxId" : "GB123456789" , "vatNumber" : "GB987654321" , "industryCode" : "6201" , "dueDiligenceCompleted" : true , "sanctionsCheckDate" : "2026-01-10" } }
Status: 201 Created{ "code" : 201 , "message" : "Beneficiary created successfully" , "data" : { "beneficiaryId" : "benef-2233e8400-e29b-41d4-a716-446655440190" , "accountId" : "wallet-aa0e8400-e29b-41d4-a716-446655440120" , "partyType" : "BUSINESS_CUSTOMER" , "beneficiaryName" : "Supplier Corporation Ltd" , "iban" : "GB82WEST12345698765432" , "bic" : "WESTGB21" , "bicType" : "external" , "currency" : "EUR" , "country" : "GB" , "networkName" : "SEPA" , "bankName" : "Westminster Bank" , "purposeCode" : "INVOICE_PAYMENT" , "pepCheckResult" : "VERIFIED" , "sanctionsCheckResult" : "CLEAR" , "status" : "active" , "createdAt" : "2026-01-15T15:00:00.000Z" , "verifiedAt" : "2026-01-15T15:00:00.000Z" } }
Business Relationship Types Relationship Type Description SUPPLIERGoods or services supplier VENDORVendor relationship PARTNERBusiness partner SUBSIDIARYSubsidiary company AFFILIATEAffiliated company CONTRACTORContract service provider
Purpose Codes Code Description INVOICE_PAYMENTPayment for invoices SALARY_PAYMENTEmployee salary payments TAX_PAYMENTTax payments to authorities LOAN_REPAYMENTLoan repayment DIVIDEND_PAYMENTDividend distribution INVESTMENTInvestment transfers
Enhanced Due Diligence Fields Field Description taxIdBeneficiary’s tax identification vatNumberVAT registration number industryCodeIndustry classification code dueDiligenceCompletedDue diligence status sanctionsCheckDateDate of last sanctions check
List Beneficiaries Endpoint: GET /api/v2.1/fintrans/{accountId}/beneficiariesQuery Parameters:
status: Filter by status (active, inactive)partyType: Filter by party typenetwork: Filter by network (SEPA, SWIFT) Status: 200 OK{ "code" : 200 , "message" : "Beneficiaries retrieved successfully" , "data" : [ { "beneficiaryId" : "benef-2233e8400-e29b-41d4-a716-446655440190" , "beneficiaryName" : "Supplier Corporation Ltd" , "iban" : "GB82WEST12345698765432" , "network" : "SEPA" , "status" : "active" , "lastUsed" : "2026-01-15T16:00:00.000Z" } ] }
Beneficiary Verification All beneficiaries undergo automatic verification:
Check Description Result PEP Check Politically Exposed Person screening VERIFIED / FLAGGED Sanctions Check Global sanctions list screening CLEAR / FLAGGED IBAN Validation IBAN format and checksum VALID / INVALID
Beneficiaries with FLAGGED status cannot be used for transactions until manually reviewed and approved.
Next Step After adding beneficiaries, proceed to Phase 7: Payment Consent Setup .
Phase 7: Payment Consent Setup Create payment consents with restrictions
