{"openapi":"3.0.3","info":{"title":"Beneficiary","version":"1.0","description":"Beneficiary service"},"paths":{"/recipients":{"get":{"operationId":"get_client_recipients","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:read","Admin:Beneficiaries:read","Client:At Verto Rate:read","Client:Make Payment To Account:read","Client:Add Funds:read","Client:Make Payment To Another Business:read"],"summary":"Fetch user beneficiaries","description":"Retrieve a paginated list of beneficiaries for the authenticated user with filtering and search capabilities","tags":["Client"],"parameters":[{"$ref":"#/components/parameters/limitParam"},{"$ref":"#/components/parameters/skipParam"},{"name":"searchQuery","in":"query","description":"Search by name, account number, bank name, or reference.","schema":{"type":"string"},"example":"Acme"},{"name":"currencyId","in":"query","description":"Return only beneficiaries for this currency id. See the guide on [Currency Codes Mapping](/docs/currency-codes) for valid values.","schema":{"type":"string"},"example":"4"},{"name":"accountId","in":"query","description":"Return the beneficiary with this id.","schema":{"type":"string"},"example":"12345"},{"name":"accountNumbers","in":"query","description":"Comma-separated account numbers to match (up to 100).","allowReserved":true,"schema":{"type":"string"},"example":"98846622175,1122334455"},{"name":"stablecoin","in":"query","description":"`true` — stablecoin beneficiaries only.\n`false` or omit — non-stablecoin beneficiaries.\n","schema":{"anyOf":[{"type":"boolean"},{"type":"string"}]},"example":false},{"name":"isSelfAccount","in":"query","description":"`true` — your own company accounts only.\n`false` — third-party recipients only.\n","schema":{"type":"string"},"example":"false"},{"name":"reference","in":"query","description":"Filter by beneficiary reference (or comma-separated list).","allowReserved":true,"schema":{"type":"string"},"example":"RP-27022024-010"},{"name":"isAccountActive","in":"query","description":"Filter by active (`true`) or inactive (`false`) beneficiaries.","schema":{"type":"boolean"},"example":true},{"name":"needsUpdate","in":"query","description":"When `true`, omit beneficiaries that require a forced update\n(`isUpdateRequired` on the response).\n","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"Successfully retrieved user beneficiaries","content":{"application/json":{"schema":{"type":"object","properties":{"totalCount":{"type":"integer","format":"int32","description":"Total matches before pagination.","example":1},"items":{"type":"array","items":{"$ref":"#/components/schemas/beneficiaryClient"}}}},"examples":{"approvedBankBeneficiaries":{"summary":"One approved LOCAL company beneficiary","value":{"totalCount":1,"items":[{"id":12345,"country":null,"currencyId":25,"partyType":"Third_Party","isSelfAccount":false,"beneficiaryType":"company","companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"accountNumber":"98846622175","accountLabel":null,"cryptoCurrency":null,"blockchain":null,"cryptoCurrencyWalletAddress":null,"cryptoCurrencyWalletHostedOption":null,"cryptoCurrencyWalletHostedOn":null,"cryptoCurrencyWalletHostedOnOtherOption":null,"bankCode":"112233","altNationalId":null,"bankName":"HDFC Bank","reference":"RP-09082026-001","paymentMode":"LOCAL","paymentCapabilities":null,"isUpdateRequired":false,"updateReason":null,"verificationState":"approved","companyId":1001,"bankAddress":{"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","address":"123 MG Road"},"beneficiaryAddress":{"companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","addressLine1":"456 Business Park","addressLine2":null,"mobileNumber":null,"email":null},"createdAt":"2026-08-09T10:15:30.000Z","isAccountActive":true,"isArchived":false,"customReferenceLabel":"Vendor Payment - Acme","forceUpdateComments":null,"nestedType":null,"copVerification":null,"adminVerified":"approved","representativeName":"Rohan Mehta","bulkBeneficiaryId":null,"userRecordId":null,"ccValidationId":null}]}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}}}},"post":{"operationId":"create_client_recipient","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:write","Admin:Beneficiaries:write","Client:Add Account:write"],"summary":"Create new beneficiary","description":"Create a new beneficiary account with banking details, address information, and payment preferences","tags":["Client"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/addBeneficiaryClient"},"examples":{"localCompany":{"summary":"Bank beneficiary (non-international) - LOCAL company (INR)","value":{"currencyId":25,"beneficiaryType":"company","paymentMode":"LOCAL","companyName":"Acme Trading Ltd","accountNumber":"98846622175","bankCode":"112233","bankName":"HDFC Bank","bankAddress":{"countryCode":"IN"}}},"localIndividualGbp":{"summary":"Bank beneficiary (non-international) - LOCAL individual (GBP)","value":{"currencyId":4,"beneficiaryType":"individual","paymentMode":"LOCAL","firstName":"Jane","lastName":"Doe","accountNumber":"12345678","bankCode":"200000","bankName":"Barclays Bank UK PLC","bankAddress":{"countryCode":"GB"}}},"localMyOrganisation":{"summary":"Bank beneficiary (non-international) - LOCAL myOrganisation (INR)","value":{"currencyId":25,"beneficiaryType":"myOrganisation","paymentMode":"LOCAL","isSelfAccount":true,"accountNumber":"9988776655","bankCode":"112233","bankName":"HDFC Bank","bankAddress":{"countryCode":"IN"}}},"internationalCompany":{"summary":"Bank beneficiary (international) - company (EUR)","value":{"currencyId":5,"beneficiaryType":"company","paymentMode":"INTERNATIONAL","companyName":"Acme Exports Ltd","accountNumber":"DE89370400440532013000","bankCode":"DEUTDEFF","bankName":"Deutsche Bank","bankAddress":{"countryCode":"DE"},"beneficiaryAddress":{"addressLine1":"12 Hauptstrasse","city":"Berlin","countryCode":"DE","postCode":"10115","stateOrProvience":"Berlin"}}},"mobileMoneyIndividual":{"summary":"Bank beneficiary (non-international) - MOBILE_MONEY (KES M-PESA)","value":{"currencyId":28,"beneficiaryType":"individual","paymentMode":"MOBILE_MONEY","firstName":"Amina","lastName":"Otieno","accountNumber":"+254-712345678","bankCode":"M-PESA","bankName":"M-PESA","bankAddress":{"countryCode":"KE"}}},"hkBankCompany":{"summary":"Bank beneficiary (non-international) - HK_BANK (CNY to HK bank)","value":{"currencyId":22,"beneficiaryType":"company","paymentMode":"HK_BANK","companyName":"Harbour Trading HK","accountNumber":"123456789012","bankCode":"004","bankName":"HSBC Hong Kong","bankAddress":{"countryCode":"HK"},"beneficiaryAddress":{"addressLine1":"1 Queens Road Central","city":"Hong Kong","countryCode":"HK","postCode":"000000","stateOrProvience":"Hong Kong"}}},"stablecoinCompany":{"summary":"Stablecoin beneficiary - wallet nickname (accountLabel)","value":{"currencyId":1,"beneficiaryType":"company","paymentMode":"STABLECOIN","companyName":"Crypto Desk Ltd","accountLabel":"Treasury USDC","cryptoCurrency":"USDC","blockchain":"ethereum_erc20","cryptoCurrencyWalletAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","cryptoCurrencyWalletHostedOption":"exchange","cryptoCurrencyWalletHostedOn":"exchange_binance_us"}},"stablecoinIndividual":{"summary":"Stablecoin beneficiary - named beneficiary (with address)","value":{"currencyId":1,"beneficiaryType":"individual","paymentMode":"STABLECOIN","firstName":"Jane","lastName":"Doe","cryptoCurrency":"USDC","blockchain":"ethereum_erc20","cryptoCurrencyWalletAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","cryptoCurrencyWalletHostedOption":"self_hosted_wallet","cryptoCurrencyWalletHostedOn":"self_hosted_metamask","beneficiaryAddress":{"addressLine1":"10 Example Street","city":"London","countryCode":"GB","postCode":"SW1A 1AA","stateOrProvience":"London"}}}}}}},"responses":{"200":{"description":"Successfully created new beneficiary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/addBeneficiaryClientResponse"},"examples":{"createdLocalCompany":{"summary":"Created LOCAL company beneficiary","value":{"success":true,"accounts":{"id":12345,"country":null,"currencyId":25,"partyType":"Third_Party","isSelfAccount":false,"beneficiaryType":"company","companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"accountNumber":"98846622175","accountLabel":null,"cryptoCurrency":null,"blockchain":null,"cryptoCurrencyWalletAddress":null,"cryptoCurrencyWalletHostedOption":null,"cryptoCurrencyWalletHostedOn":null,"cryptoCurrencyWalletHostedOnOtherOption":null,"bankCode":"112233","altNationalId":null,"bankName":"HDFC Bank","reference":"RP-09082026-001","paymentMode":"LOCAL","paymentCapabilities":null,"isUpdateRequired":false,"updateReason":null,"verificationState":"approved","companyId":1001,"bankAddress":{"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","address":"123 MG Road"},"beneficiaryAddress":{"companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","addressLine1":"456 Business Park","addressLine2":null,"mobileNumber":null,"email":null},"createdAt":"2026-08-09T10:15:30.000Z","isAccountActive":true,"isArchived":false,"customReferenceLabel":"Vendor Payment - Acme","forceUpdateComments":null,"nestedType":null,"copVerification":null,"adminVerified":"approved","representativeName":"Rohan Mehta","bulkBeneficiaryId":null,"userRecordId":null,"ccValidationId":null}}},"createdStablecoinCompany":{"summary":"Created STABLECOIN company beneficiary","value":{"success":true,"accounts":{"id":12346,"country":null,"currencyId":1,"partyType":"Third_Party","isSelfAccount":false,"beneficiaryType":"company","companyName":"Crypto Desk Ltd","firstName":null,"lastName":null,"accountNumber":null,"accountLabel":"Treasury USDC","cryptoCurrency":"USDC","blockchain":"ethereum_erc20","cryptoCurrencyWalletAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","cryptoCurrencyWalletHostedOption":"exchange","cryptoCurrencyWalletHostedOn":"exchange_binance_us","cryptoCurrencyWalletHostedOnOtherOption":null,"bankCode":null,"altNationalId":null,"bankName":null,"reference":"RP-09082026-002","paymentMode":"STABLECOIN","paymentCapabilities":null,"isUpdateRequired":false,"updateReason":null,"verificationState":"approved","companyId":1001,"bankAddress":{"countryCode":null,"stateOrProvience":null,"city":null,"postCode":null,"address":null},"beneficiaryAddress":{"companyName":null,"firstName":null,"lastName":null,"countryCode":null,"stateOrProvience":null,"city":null,"postCode":null,"addressLine1":null,"addressLine2":null,"mobileNumber":null,"email":null},"createdAt":"2026-08-09T11:02:10.000Z","isAccountActive":true,"isArchived":false,"customReferenceLabel":"Crypto Treasury Transfer","forceUpdateComments":null,"nestedType":null,"copVerification":null,"adminVerified":"approved","representativeName":"Wei Zhang","bulkBeneficiaryId":null,"userRecordId":null,"ccValidationId":null}}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingAccountNumber":{"summary":"Missing required bank field","value":{"message":"Account number is required","code":400}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}},"404":{"description":"Related configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recipients/{recipientId}":{"get":{"operationId":"get_client_recipient_by_id","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:read","Admin:Beneficiaries:read","Client:At Verto Rate:read","Client:Make Payment To Account:read","Client:Add Funds:read","Client:Make Payment To Another Business:read"],"summary":"Fetch user beneficiary by ID","description":"Retrieve detailed information for a specific beneficiary account by its unique identifier","tags":["Client"],"parameters":[{"name":"recipientId","in":"path","description":"id of the account","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Fetch beneficiary details by ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/addBeneficiaryClientResponse"},"examples":{"localCompanyById":{"summary":"LOCAL company beneficiary","value":{"success":true,"accounts":{"id":12345,"country":null,"currencyId":25,"partyType":"Third_Party","isSelfAccount":false,"beneficiaryType":"company","companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"accountNumber":"98846622175","accountLabel":null,"cryptoCurrency":null,"blockchain":null,"cryptoCurrencyWalletAddress":null,"cryptoCurrencyWalletHostedOption":null,"cryptoCurrencyWalletHostedOn":null,"cryptoCurrencyWalletHostedOnOtherOption":null,"bankCode":"112233","altNationalId":null,"bankName":"HDFC Bank","reference":"RP-09082026-001","paymentMode":"LOCAL","paymentCapabilities":null,"isUpdateRequired":false,"updateReason":null,"verificationState":"approved","companyId":1001,"bankAddress":{"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","address":"123 MG Road"},"beneficiaryAddress":{"companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","addressLine1":"456 Business Park","addressLine2":null,"mobileNumber":null,"email":null},"createdAt":"2026-08-09T10:15:30.000Z","isAccountActive":true,"isArchived":false,"customReferenceLabel":"Vendor Payment - Acme","forceUpdateComments":null,"nestedType":null,"copVerification":null,"adminVerified":"approved","representativeName":"Rohan Mehta","bulkBeneficiaryId":null,"userRecordId":null,"ccValidationId":null}}},"stablecoinById":{"summary":"STABLECOIN company beneficiary","value":{"success":true,"accounts":{"id":12346,"country":null,"currencyId":1,"partyType":"Third_Party","isSelfAccount":false,"beneficiaryType":"company","companyName":"Crypto Desk Ltd","firstName":null,"lastName":null,"accountNumber":null,"accountLabel":"Treasury USDC","cryptoCurrency":"USDC","blockchain":"ethereum_erc20","cryptoCurrencyWalletAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","cryptoCurrencyWalletHostedOption":"exchange","cryptoCurrencyWalletHostedOn":"exchange_binance_us","cryptoCurrencyWalletHostedOnOtherOption":null,"bankCode":null,"altNationalId":null,"bankName":null,"reference":"RP-09082026-002","paymentMode":"STABLECOIN","paymentCapabilities":null,"isUpdateRequired":false,"updateReason":null,"verificationState":"approved","companyId":1001,"bankAddress":{"countryCode":null,"stateOrProvience":null,"city":null,"postCode":null,"address":null},"beneficiaryAddress":{"companyName":null,"firstName":null,"lastName":null,"countryCode":null,"stateOrProvience":null,"city":null,"postCode":null,"addressLine1":null,"addressLine2":null,"mobileNumber":null,"email":null},"createdAt":"2026-08-09T11:02:10.000Z","isAccountActive":true,"isArchived":false,"customReferenceLabel":"Crypto Treasury Transfer","forceUpdateComments":null,"nestedType":null,"copVerification":null,"adminVerified":"approved","representativeName":"Wei Zhang","bulkBeneficiaryId":null,"userRecordId":null,"ccValidationId":null}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}},"404":{"description":"Beneficiary not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFound":{"summary":"Unknown recipientId","value":{"message":"Beneficiary not found","code":404}}}}}}}},"put":{"operationId":"update_client_recipient","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:write","Admin:Beneficiaries:write","Client:Update Account:write"],"summary":"Update an existing beneficiary","description":"Update an existing beneficiary account. Fields are merged with the existing record; `currencyId`, `paymentMode` and `beneficiaryType` must always be supplied so downstream validation can resolve the correct currency/payment-mode configuration.","tags":["Client"],"parameters":[{"name":"recipientId","in":"path","description":"id of the account","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateBeneficiaryClient"},"examples":{"updateLocalCompany":{"summary":"Update LOCAL company bank details","value":{"currencyId":25,"beneficiaryType":"company","paymentMode":"LOCAL","companyName":"Acme Trading Ltd","accountNumber":"98846622175","bankCode":"112233","bankName":"HDFC Bank","bankAddress":{"countryCode":"IN"}}},"updateStablecoinCompany":{"summary":"Update STABLECOIN wallet (accountLabel path)","value":{"currencyId":1,"beneficiaryType":"company","paymentMode":"STABLECOIN","companyName":"Crypto Desk Ltd","accountLabel":"Treasury USDC","cryptoCurrency":"USDC","blockchain":"ethereum_erc20","cryptoCurrencyWalletAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","cryptoCurrencyWalletHostedOption":"exchange","cryptoCurrencyWalletHostedOn":"exchange_binance_us"}},"updateGbpIndividual":{"summary":"Update LOCAL GBP individual","value":{"currencyId":4,"beneficiaryType":"individual","paymentMode":"LOCAL","firstName":"Jane","lastName":"Doe","accountNumber":"12345678","bankCode":"200000","bankName":"Barclays Bank UK PLC","bankAddress":{"countryCode":"GB"}}}}}}},"responses":{"200":{"description":"Successfully updated beneficiary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateBeneficiaryResponse"},"examples":{"updatedLocalCompany":{"summary":"Updated LOCAL company beneficiary","value":{"success":true,"accounts":{"id":12345,"country":null,"currencyId":25,"partyType":"Third_Party","isSelfAccount":false,"beneficiaryType":"company","companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"accountNumber":"98846622175","accountLabel":null,"cryptoCurrency":null,"blockchain":null,"cryptoCurrencyWalletAddress":null,"cryptoCurrencyWalletHostedOption":null,"cryptoCurrencyWalletHostedOn":null,"cryptoCurrencyWalletHostedOnOtherOption":null,"bankCode":"112233","altNationalId":null,"bankName":"HDFC Bank","reference":"RP-09082026-001","paymentMode":"LOCAL","paymentCapabilities":null,"isUpdateRequired":false,"updateReason":null,"verificationState":"approved","companyId":1001,"bankAddress":{"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","address":"123 MG Road"},"beneficiaryAddress":{"companyName":"Acme Trading Ltd","firstName":null,"lastName":null,"countryCode":"IN","stateOrProvience":"Maharashtra","city":"Mumbai","postCode":"400001","addressLine1":"456 Business Park","addressLine2":null,"mobileNumber":null,"email":null},"createdAt":"2026-08-09T10:15:30.000Z","isAccountActive":true,"isArchived":false,"customReferenceLabel":"Vendor Payment - Acme","forceUpdateComments":null,"nestedType":null,"copVerification":null,"adminVerified":"approved","representativeName":"Rohan Mehta","bulkBeneficiaryId":null,"userRecordId":null,"ccValidationId":null}}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingRequired":{"summary":"Missing required update fields","value":{"message":"currencyId, paymentMode and beneficiaryType are required","code":400}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}},"404":{"description":"Beneficiary not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFound":{"summary":"Unknown recipientId","value":{"message":"Beneficiary not found","code":404}}}}}}}},"delete":{"operationId":"delete_client_recipient","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:write","Admin:Beneficiaries:write","Client:Delete Account:write"],"summary":"Delete beneficiary","description":"Remove an existing beneficiary account","tags":["Client"],"parameters":[{"name":"recipientId","in":"path","description":"id of the account","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully deleted beneficiary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/deleteResponse"},"examples":{"deleted":{"summary":"Beneficiary deleted","value":{"success":true}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}},"404":{"description":"Beneficiary not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFound":{"summary":"Unknown recipientId","value":{"message":"Beneficiary not found","code":404}}}}}}}}},"/uploadDocuments":{"post":{"operationId":"upload_beneficiary_documents","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:read","Admin:Beneficiaries:read"],"summary":"Get signed URLs to upload beneficiary documents","description":"This endpoint does **not** accept file bytes. It returns short-lived\npre-signed S3 upload URLs so you can attach supporting documents to a\nbeneficiary (when Verto compliance requires them).\n\n---\n\n### How to use (3 steps)\n\n1. **Request upload URLs** — `POST /uploadDocuments` with a JSON **array**\n   of `{ fileName, fileType }` objects.\n   Allowed `fileName` extensions: `jpeg`, `jpg`, `pdf`, `png`, `svg`.\n2. **Upload each file** — HTTP `PUT` the file bytes to the matching\n   `items[].link` from the response.\n   - Use the file's content type (for example `application/pdf`).\n   - Each `link` expires in **15 minutes**.\n   - Do **not** PUT to `items[].url` — that is not the upload target.\n3. **Attach on create/update** — when calling `POST /recipients` or\n   `PUT /recipients/{recipientId}`, send:\n\n   ```json\n   \"documentDetails\": [\n     { \"key\": \"<items[].key from step 1>\", \"name\": \"<original fileName>\" }\n   ]\n   ```\n\nMost integrations can skip this entire flow and omit `documentDetails`\nunless Verto asks for supporting documents.\n","tags":["Document Upload"],"parameters":[{"name":"companyId","in":"query","required":false,"description":"Optional. Prefer omitting this — uploads use the company from your\naccess token. If you send `companyId`, it must match that company.\n","schema":{"type":"string"},"example":"12345"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadDocumentRequest"},"examples":{"singlePdf":{"summary":"One PDF document","value":[{"fileName":"passport.pdf","fileType":"application/pdf"}]},"multipleFiles":{"summary":"Multiple documents","value":[{"fileName":"passport.pdf","fileType":"application/pdf"},{"fileName":"address-proof.jpg","fileType":"image/jpeg"}]}}}}},"responses":{"200":{"description":"Signed upload URLs generated. Next: PUT each file to `items[].link`,\nthen pass `items[].key` in `documentDetails` on create/update.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadDocumentResponse"},"examples":{"success":{"summary":"Signed URL for one PDF","value":{"totalCount":1,"items":[{"success":true,"link":"https://upload.example/signed-put-url","url":"https://files.example/documents/example-file.pdf","key":"documents/example-file.pdf"}]}}}}}},"400":{"description":"Invalid request (body not an array, empty fileName, or disallowed extension)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"badExtension":{"summary":"Disallowed file extension","value":{"message":"Only these file extensions are allowed: jpeg, jpg, pdf, png, svg.","code":400}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}},"403":{"description":"companyId query does not match the authenticated company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"A server side error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/confirm-payee":{"post":{"operationId":"confirm_payee_verification","x-atlas-api":true,"x-permission-config":["Client:Beneficiaries:read"],"summary":"Retrieve ConfirmPayee verification details","description":"Retrieve verification details for payee confirmation in the UK payment system","tags":["Payee Verification Data"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/confirmPayee"},"examples":{"ukPersonal":{"summary":"UK Confirmation of Payee (personal)","value":{"type":"PERSONAL","name":"Jane Doe","accountType":"PERSONAL","sortCode":"200000","accountNumber":"12345678"}},"nigeriaNameEnquiry":{"summary":"Nigeria name enquiry","value":{"bankCountry":"NG","bankCode":"000014","accountNumber":"0123456789"}}}}}},"responses":{"200":{"description":"Successfully retrieved ConfirmPayee verification details","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/confirmPayeeVerificationResponse"},{"$ref":"#/components/schemas/confirmPayeeVerificationResponseNG"}]},"examples":{"ukMatch":{"summary":"UK CoP name match","value":{"actualPayeeName":"Jane Doe","status":{"identifier":"CONFIRMED","detailedStatusIdentifier":"MATCH_PERSONAL","reason":"Name is a match to the account name."}}},"nigeriaMatch":{"summary":"Nigeria account name returned","value":{"bankCountry":"NG","bankCode":"000014","accountNumber":"0123456789","accountName":"ACME TRADING LTD"}}}}}},"400":{"description":"unacceptable request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401Unauthorized"}}}},"404":{"description":"risk factor entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"A server side error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token returned by the Login endpoint. Send it as:\n> Authorization: Bearer <token>\n"}},"parameters":{"limitParam":{"name":"limit","in":"query","description":"max records to return","schema":{"type":"integer","format":"int32","maximum":100}},"skipParam":{"name":"skip","in":"query","description":"number of items to skip","schema":{"type":"integer","format":"int32"}}},"schemas":{"beneficiaryClient":{"type":"object","description":"Beneficiary returned by list / create / get-by-id.","properties":{"id":{"type":"integer","description":"Beneficiary id (`{recipientId}` for get/update/delete).","example":12345},"country":{"type":"string","description":"Legacy country text. Prefer `bankAddress.countryCode` / `beneficiaryAddress.countryCode`.","example":"India"},"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":4},"partyType":{"type":"string","description":"`First_Party` if `isSelfAccount` is true, otherwise `Third_Party`.\nDistinct from `beneficiaryType`.\n","enum":["First_Party","Third_Party"],"example":"Third_Party"},"isSelfAccount":{"type":"boolean","description":"Whether this beneficiary is an account your company owns (`First_Party`) rather than a third party (`Third_Party`).","example":false},"beneficiaryType":{"type":"string","description":"`company`, `individual`, or `myOrganisation`.","enum":["company","individual","myOrganisation"],"example":"company"},"companyName":{"type":"string","nullable":true,"description":"Company name, when `beneficiaryType` is `company`.","example":"Acme Trading Ltd"},"firstName":{"type":"string","nullable":true,"description":"First name, when `beneficiaryType` is `individual`."},"lastName":{"type":"string","nullable":true,"description":"Last name, when `beneficiaryType` is `individual`."},"accountNumber":{"type":"string","nullable":true,"description":"Account number / IBAN (bank modes).","example":"98846622175"},"accountLabel":{"type":"string","description":"Wallet nickname (stablecoin).","maxLength":50},"cryptoCurrency":{"type":"string","description":"Stablecoin ticker (`STABLECOIN` only).","enum":["USDC","USDT"]},"blockchain":{"type":"string","description":"Blockchain network (`STABLECOIN` only).","enum":["ethereum_erc20"]},"cryptoCurrencyWalletAddress":{"type":"string","description":"Wallet address (`STABLECOIN` only).","maxLength":42},"cryptoCurrencyWalletHostedOption":{"type":"string","description":"Wallet hosting type (`STABLECOIN` only).","enum":["dedicated_wallet_via_custodian","exchange","self_hosted_wallet","not_known"]},"cryptoCurrencyWalletHostedOn":{"$ref":"#/components/schemas/CryptoCurrencyWalletHostedOn"},"cryptoCurrencyWalletHostedOnOtherOption":{"type":"string","nullable":true,"maxLength":30},"bankCode":{"type":"string","description":"Bank code / sort code / SWIFT.","example":"112233"},"altNationalId":{"type":"string","nullable":true,"description":"Secondary identifier for the beneficiary account (e.g. a mobile money provider or alternate national/bank identifier), if one was set."},"bankName":{"type":"string","description":"Bank name.","example":"HDFC Bank"},"reference":{"type":"string","description":"Beneficiary reference (use when creating payments).","example":"RP-09082026-001"},"paymentMode":{"type":"string","nullable":true,"description":"Payment method.","enum":["LOCAL","INTERNATIONAL","MOBILE_MONEY","STABLECOIN","HK_BANK"],"example":"LOCAL"},"paymentCapabilities":{"type":"object","nullable":true,"additionalProperties":true,"description":"Bank capability details filled in by Verto after bank lookup. Shape varies by bank/vendor."},"isUpdateRequired":{"type":"boolean","description":"`true` if this beneficiary needs a forced update before use.","example":false},"updateReason":{"type":"string","nullable":true,"description":"Why a forced update is required, when `isUpdateRequired` is true."},"verificationState":{"type":"string","description":"Compliance status — same as `adminVerified`.","enum":["approved","pending","rejected"],"example":"approved"},"companyId":{"type":"integer","description":"Your company id.","example":1001},"bankAddress":{"type":"object","description":"Bank address. `countryCode` is the bank country.","properties":{"countryCode":{"type":"string","description":"Bank country (ISO-2).","example":"IN"},"stateOrProvience":{"type":"string","description":"State or province.","nullable":true},"city":{"type":"string"},"postCode":{"type":"string","nullable":true},"address":{"type":"string"}}},"beneficiaryAddress":{"type":"object","description":"Beneficiary person/company address (not the bank).","properties":{"companyName":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"countryCode":{"type":"string","description":"Beneficiary country (ISO-2)."},"stateOrProvience":{"type":"string","description":"State or province.","nullable":true},"city":{"type":"string"},"postCode":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string","nullable":true},"mobileNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time","description":"Created at (ISO-8601)."},"isAccountActive":{"type":"boolean","description":"Whether the beneficiary is active.","example":true},"isArchived":{"type":"boolean","description":"Whether the beneficiary is archived.","example":false},"customReferenceLabel":{"type":"string","nullable":true,"description":"Your optional reconciliation label.","example":"Vendor Payment - Acme"},"forceUpdateComments":{"type":"string","description":"Comments when a forced update was requested."},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"copVerification":{"type":"string","nullable":true,"description":"Stored Confirmation of Payee (CoP) / name-check outcome, if one was\nsubmitted when the beneficiary was created or updated.\n","example":"MATCH_PERSONAL"},"adminVerified":{"type":"string","nullable":true,"description":"Compliance status (`approved` / `pending` / `rejected`). Same as `verificationState`.","example":"approved"},"representativeName":{"type":"string","nullable":true,"description":"Representative name, if stored.","example":"Rohan Mehta"},"bulkBeneficiaryId":{"type":"string","nullable":true,"description":"Set only for bulk-uploaded beneficiaries; otherwise null."},"userRecordId":{"type":"string","nullable":true,"description":"Linked user-record id, if present."},"ccValidationId":{"type":"string","nullable":true,"description":"Confirmation of Payee validation id, if present."}}},"ClientNestedType":{"type":"string","nullable":true,"description":"Relationship of this beneficiary to your company, when your company\nhas been approved as a nested/downstream client (company category\n**financial services** or **crypto**).\n\nRequired on every beneficiary you create for as long as your\ncompany is approved for downstream/nested use — not just for some\nbeneficiaries. Send one of:\n\n- `OPEX` — Your own operational / operating-expense account\n- `NESTED_CUSTOMER` — An end-customer of yours\n- `NESTED_PAYEE` — A payee of your nested customer\n\nNot applicable (omit, or send `null`) if your company has not been\napproved as a nested/downstream client.\n","enum":["OPEX","NESTED_CUSTOMER","NESTED_PAYEE"],"example":"NESTED_CUSTOMER"},"ClientDocumentDetail":{"type":"object","description":"One supporting document already uploaded for this beneficiary.\n\nComplete the flow on [Upload beneficiary documents](/reference/upload_beneficiary_documents)\nfirst (`POST /uploadDocuments` → PUT file to `link` → use `key` here).\n\nMost integrations can omit `documentDetails` or send an empty array.\n","required":["key","name"],"properties":{"key":{"type":"string","description":"S3 object key from `POST /uploadDocuments` response (`items[].key`).\nExample: `documents/example-file.pdf`.\n","example":"documents/example-file.pdf"},"name":{"type":"string","description":"Original filename (usually the same `fileName` you sent to upload).","example":"passport.pdf"}}},"ClientBankAddress":{"type":"object","description":"Bank location. Send `countryCode` (bank country, ISO-2). Other sub-fields are optional.","required":["countryCode"],"properties":{"countryCode":{"type":"string","description":"Bank country (ISO-2).","example":"IN","pattern":"^(?=[A-Za-z]{2}$)[A-Za-z]*|$"},"stateOrProvience":{"type":"string","description":"State or province.","example":"State","nullable":true},"city":{"type":"string","example":"Delhi","nullable":true},"postCode":{"type":"string","example":"789456","nullable":true},"address":{"type":"string","example":"MG Road","nullable":true}}},"ClientBeneficiaryAddress":{"type":"object","description":"Beneficiary person/company address (not the bank).\nWhen present, each text field must be up to 35 characters; only alphanumeric\ncharacters, spaces, and commas are allowed.\n","properties":{"countryCode":{"type":"string","description":"Beneficiary country (ISO-2).","example":"IN","pattern":"^(?=[A-Za-z]{2}$)[A-Za-z]*|$","nullable":true},"stateOrProvience":{"type":"string","description":"State or province. Up to 35 characters; alphanumeric, spaces, and commas only.","maxLength":35,"pattern":"^(|[0-9a-zA-Z, ]{0,35})$","example":"Delhi","nullable":true},"city":{"type":"string","description":"Up to 35 characters; alphanumeric, spaces, and commas only.","maxLength":35,"pattern":"^(|[0-9a-zA-Z, ]{0,35})$","example":"Delhi","nullable":true},"postCode":{"type":"string","description":"Up to 35 characters; alphanumeric, spaces, and commas only.","maxLength":35,"pattern":"^(|[0-9a-zA-Z, ]{0,35})$","example":"110001","nullable":true},"addressLine1":{"type":"string","description":"Up to 35 characters; alphanumeric, spaces, and commas only.","maxLength":35,"pattern":"^(|[0-9a-zA-Z, ]{0,35})$","example":"12 Main Street","nullable":true},"addressLine2":{"type":"string","description":"Up to 35 characters; alphanumeric, spaces, and commas only.","maxLength":35,"pattern":"^(|[0-9a-zA-Z, ]{0,35})$","example":"Suite 4","nullable":true},"mobileNumber":{"type":"string","description":"Recipient mobile, when required for the currency.","example":"9875642318","nullable":true},"email":{"type":"string","description":"Recipient email, when required for the currency.","example":"beneficiary@example.com","nullable":true}}},"CreateStablecoinBeneficiary":{"type":"object","title":"Stablecoin beneficiary","description":"Crypto wallet beneficiary (`paymentMode: STABLECOIN`).\nDo not send bank fields (`accountNumber`, `bankCode`, `bankName`, `bankAddress`).\n\nTwo ways to identify the beneficiary:\n\n1. **With `accountLabel` (wallet nickname)** — also send `companyName`.\n   Full `beneficiaryAddress` is not required.\n2. **Without `accountLabel`** — send either `companyName`, or both `firstName`\n   and `lastName`, plus full `beneficiaryAddress` (`addressLine1`, `city`,\n   `countryCode`, `postCode`, `stateOrProvience`).\n","example":{"currencyId":1,"beneficiaryType":"company","paymentMode":"STABLECOIN","companyName":"Crypto Desk Ltd","accountLabel":"Treasury USDC","cryptoCurrency":"USDC","blockchain":"ethereum_erc20","cryptoCurrencyWalletAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","cryptoCurrencyWalletHostedOption":"exchange","cryptoCurrencyWalletHostedOn":"exchange_binance_us"},"required":["currencyId","beneficiaryType","paymentMode","cryptoCurrencyWalletAddress","blockchain","cryptoCurrency","cryptoCurrencyWalletHostedOption"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":1},"beneficiaryType":{"type":"string","description":"Who you are paying (`company`, `individual`, or `myOrganisation`).","enum":["company","individual","myOrganisation"],"example":"company"},"paymentMode":{"type":"string","description":"Payment method (`STABLECOIN`).","enum":["STABLECOIN"],"example":"STABLECOIN"},"accountLabel":{"type":"string","description":"Wallet nickname. When provided, `companyName` is also required and\nfull `beneficiaryAddress` is not required.\nAllowed characters: alphanumeric, spaces, and .,'&@#$^*/!().\nMaximum length: 50.\n","maxLength":50,"nullable":true,"example":"Treasury USDC"},"companyName":{"type":"string","description":"Required when `accountLabel` is provided, or when `firstName`/`lastName`\nare not supplied.\nAllowed characters: alphanumeric and spaces; some currencies also allow `.` and `-`.\n","example":"Crypto Desk Ltd","nullable":true},"firstName":{"type":"string","description":"Use with `lastName` when `accountLabel` and `companyName` are not supplied.\nOnly alphanumeric characters and spaces are allowed.\n","example":"Jane","nullable":true},"lastName":{"type":"string","description":"Use with `firstName` when `accountLabel` and `companyName` are not supplied.\nOnly alphanumeric characters and spaces are allowed.\n","example":"Doe","nullable":true},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"},{"type":"object","description":"Required when `accountLabel` is not provided: send `addressLine1`,\n`city`, `countryCode`, `postCode`, and `stateOrProvience`.\nEach text field (when present) must be up to 35 characters; only\nalphanumeric characters, spaces, and commas are allowed.\n"}]},"cryptoCurrency":{"type":"string","description":"Stablecoin ticker.","enum":["USDC","USDT"],"example":"USDC"},"blockchain":{"type":"string","description":"Blockchain network.","enum":["ethereum_erc20"],"example":"ethereum_erc20"},"cryptoCurrencyWalletAddress":{"type":"string","description":"Wallet address. Must be a valid `0x`-prefixed 40-character hex address.","maxLength":42,"example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"},"cryptoCurrencyWalletHostedOption":{"type":"string","description":"How the wallet is hosted.","enum":["dedicated_wallet_via_custodian","exchange","self_hosted_wallet","not_known"],"example":"exchange"},"cryptoCurrencyWalletHostedOn":{"$ref":"#/components/schemas/CryptoCurrencyWalletHostedOn"},"cryptoCurrencyWalletHostedOnOtherOption":{"type":"string","description":"Provider name to use when `cryptoCurrencyWalletHostedOn` is `other`\n(custodian, exchange, or wallet provider).\nMaximum length: 30.\n","nullable":true,"maxLength":30},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is a wallet you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's wallets; leave `false`/omit for third-party payees.","example":false,"nullable":true},"customReferenceLabel":{"type":"string","description":"Optional label for your own reconciliation.","example":"Vendor-42","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]}}},"CreateBankBeneficiaryCompany":{"type":"object","title":"Bank beneficiary (non-international) - company","description":"Bank beneficiary (non-international). Requires bank details and `companyName`.\nDo not send stablecoin/crypto fields.\n\nSet `paymentMode` to the payout rail:\n`LOCAL` (domestic bank), `MOBILE_MONEY` (KES/TZS wallets), or\n`HK_BANK` (CNY paid to a Hong Kong bank).\n`beneficiaryAddress` is required for some currencies (e.g. `USD` on `LOCAL`) but not others (e.g. `GBP` on `LOCAL`).\n","example":{"currencyId":25,"beneficiaryType":"company","paymentMode":"LOCAL","companyName":"Acme Trading Ltd","accountNumber":"98846622175","bankCode":"112233","bankName":"HDFC Bank","bankAddress":{"countryCode":"IN"}},"required":["currencyId","beneficiaryType","paymentMode","accountNumber","bankCode","bankName","bankAddress","companyName"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":25},"beneficiaryType":{"type":"string","enum":["company"],"example":"company"},"paymentMode":{"type":"string","description":"How the payout is delivered (non-international). Choose based on the rail:\n\n- `LOCAL` — Domestic bank transfer in the beneficiary's market.\n  Use a normal bank account number plus the local bank identifier\n  (sort code, local bank code, or SWIFT/BIC as required for the currency).\n  Example: GBP Faster Payments (`bankCode` = sort code, `accountNumber` = 8-digit account).\n\n- `MOBILE_MONEY` — Mobile-wallet payout (not a bank account).\n  Available for **KES** and **TZS** only.\n  Put the phone number in `accountNumber` (e.g. `+254-712345678`) and the\n  wallet provider in `bankCode` / `bankName` (e.g. `M-PESA`).\n\n- `HK_BANK` — Pay **CNY** into a Hong Kong bank account\n  (`bankAddress.countryCode: HK`, 3-digit Hong Kong `bankCode`).\n  For **HKD** domestic payouts use `LOCAL`, not `HK_BANK`.\n\nWhich values a currency accepts is enforced at runtime — see named examples.\n","enum":["LOCAL","MOBILE_MONEY","HK_BANK"],"example":"LOCAL"},"companyName":{"type":"string","description":"Company / business name.","example":"Acme Trading Ltd"},"accountNumber":{"type":"string","description":"Required for non-stablecoin payment modes.\nAllowed characters at schema level: alphanumeric and `-+./'\"`.\nExact per-currency / payment-mode format is enforced at runtime\n(e.g. TZS/KES `MOBILE_MONEY` accept `+`/`-`; SWIFT_STANDARD allows `/`).\n","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","example":"98846622175"},"bankCode":{"type":"string","description":"Bank / rail identifier for the chosen `paymentMode`:\n- `LOCAL` — sort code, local bank code, or SWIFT/BIC (see bank-code notes)\n- `MOBILE_MONEY` — wallet provider code (e.g. `M-PESA`)\n- `HK_BANK` — 3-digit Hong Kong bank code (e.g. `004`)\n","example":"112233"},"bankName":{"type":"string","description":"Bank or wallet-provider name matching `bankCode`\n(e.g. bank name for `LOCAL` / `HK_BANK`, or `M-PESA` for mobile money).\n","example":"HDFC Bank","pattern":"^.+$"},"bankAddress":{"$ref":"#/components/schemas/ClientBankAddress"},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"}],"description":"Optional for most currencies on `LOCAL`, `MOBILE_MONEY`, and\n`HK_BANK` payment modes, but required for some (e.g. `USD` on\n`LOCAL` requires it; `GBP` on `LOCAL` does not). Beneficiary\nperson/company address, not the bank's.\n"},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":false,"nullable":true},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.","example":"123456789","nullable":true},"customReferenceLabel":{"type":"string","description":"Optional. Label for your own reconciliation.","example":"Vendor-42","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — create does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"}}},"CreateBankBeneficiaryIndividual":{"type":"object","title":"Bank beneficiary (non-international) - individual","description":"Bank beneficiary (non-international). Requires bank details plus `firstName` and `lastName`.\nDo not send stablecoin fields.\n\nSet `paymentMode` to the payout rail:\n`LOCAL` (domestic bank), `MOBILE_MONEY` (KES/TZS wallets), or\n`HK_BANK` (CNY paid to a Hong Kong bank).\n","required":["currencyId","beneficiaryType","paymentMode","accountNumber","bankCode","bankName","bankAddress","firstName","lastName"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":2},"beneficiaryType":{"type":"string","enum":["individual"],"example":"individual"},"paymentMode":{"type":"string","description":"How the payout is delivered (non-international). Choose based on the rail:\n\n- `LOCAL` — Domestic bank transfer in the beneficiary's market.\n  Use a normal bank account number plus the local bank identifier\n  (sort code, local bank code, or SWIFT/BIC as required for the currency).\n  Example: GBP Faster Payments (`bankCode` = sort code, `accountNumber` = 8-digit account).\n\n- `MOBILE_MONEY` — Mobile-wallet payout (not a bank account).\n  Available for **KES** and **TZS** only.\n  Put the phone number in `accountNumber` (e.g. `+254-712345678`) and the\n  wallet provider in `bankCode` / `bankName` (e.g. `M-PESA`).\n\n- `HK_BANK` — Pay **CNY** into a Hong Kong bank account\n  (`bankAddress.countryCode: HK`, 3-digit Hong Kong `bankCode`).\n  For **HKD** domestic payouts use `LOCAL`, not `HK_BANK`.\n\nWhich values a currency accepts is enforced at runtime — see named examples.\n","enum":["LOCAL","MOBILE_MONEY","HK_BANK"],"example":"LOCAL"},"firstName":{"type":"string","example":"Jane"},"lastName":{"type":"string","example":"Doe"},"accountNumber":{"type":"string","description":"Required for non-stablecoin payment modes.\nAllowed characters at schema level: alphanumeric and `-+./'\"`.\nExact per-currency / payment-mode format is enforced at runtime\n(e.g. TZS/KES `MOBILE_MONEY` accept `+`/`-`; SWIFT_STANDARD allows `/`).\n","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","example":"12345678"},"bankCode":{"type":"string","example":"200000"},"bankName":{"type":"string","example":"Barclays Bank UK PLC","pattern":"^.+$"},"bankAddress":{"$ref":"#/components/schemas/ClientBankAddress"},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"}],"description":"Optional for most currencies on `LOCAL`, `MOBILE_MONEY`, and\n`HK_BANK` payment modes, but required for some (e.g. `USD` on\n`LOCAL` requires it; `GBP` on `LOCAL` does not). Beneficiary\nperson/company address, not the bank's.\n"},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":false,"nullable":true},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.","nullable":true},"customReferenceLabel":{"type":"string","description":"Optional. Label for your own reconciliation.","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — create does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"}}},"CreateBankBeneficiaryMyOrganisation":{"type":"object","title":"Bank beneficiary (non-international) - myOrganisation","description":"Bank beneficiary for your own organisation (non-international).\nNo name fields required. Set `isSelfAccount: true`. Do not send stablecoin fields.\n\nSet `paymentMode` to the payout rail:\n`LOCAL` (domestic bank), `MOBILE_MONEY` (KES/TZS wallets), or\n`HK_BANK` (CNY paid to a Hong Kong bank).\n","required":["currencyId","beneficiaryType","paymentMode","accountNumber","bankCode","bankName","bankAddress"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":4},"beneficiaryType":{"type":"string","enum":["myOrganisation"],"example":"myOrganisation"},"paymentMode":{"type":"string","description":"How the payout is delivered (non-international). Choose based on the rail:\n\n- `LOCAL` — Domestic bank transfer in the beneficiary's market.\n  Use a normal bank account number plus the local bank identifier\n  (sort code, local bank code, or SWIFT/BIC as required for the currency).\n  Example: GBP Faster Payments (`bankCode` = sort code, `accountNumber` = 8-digit account).\n\n- `MOBILE_MONEY` — Mobile-wallet payout (not a bank account).\n  Available for **KES** and **TZS** only.\n  Put the phone number in `accountNumber` (e.g. `+254-712345678`) and the\n  wallet provider in `bankCode` / `bankName` (e.g. `M-PESA`).\n\n- `HK_BANK` — Pay **CNY** into a Hong Kong bank account\n  (`bankAddress.countryCode: HK`, 3-digit Hong Kong `bankCode`).\n  For **HKD** domestic payouts use `LOCAL`, not `HK_BANK`.\n\nWhich values a currency accepts is enforced at runtime — see named examples.\n","enum":["LOCAL","MOBILE_MONEY","HK_BANK"],"example":"LOCAL"},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":true,"nullable":true},"accountNumber":{"type":"string","description":"Required for non-stablecoin payment modes.\nAllowed characters at schema level: alphanumeric and `-+./'\"`.\nExact per-currency / payment-mode format is enforced at runtime\n(e.g. TZS/KES `MOBILE_MONEY` accept `+`/`-`; SWIFT_STANDARD allows `/`).\n","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","example":"9988776655"},"bankCode":{"type":"string","example":"112233"},"bankName":{"type":"string","example":"HDFC Bank","pattern":"^.+$"},"bankAddress":{"$ref":"#/components/schemas/ClientBankAddress"},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"}],"description":"Optional for most currencies on `LOCAL`, `MOBILE_MONEY`, and\n`HK_BANK` payment modes, but required for some (e.g. `USD` on\n`LOCAL` requires it; `GBP` on `LOCAL` does not). Beneficiary\nperson/company address, not the bank's.\n"},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.","nullable":true},"customReferenceLabel":{"type":"string","description":"Optional. Label for your own reconciliation.","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — create does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"}}},"CreateInternationalCompany":{"type":"object","title":"Bank beneficiary (international) - company","description":"Cross-border bank payout. `paymentMode` is `INTERNATIONAL`.\nRequires bank details, `companyName`, and beneficiary address. Do not send stablecoin fields.\n","required":["currencyId","beneficiaryType","paymentMode","accountNumber","bankCode","bankName","bankAddress","companyName","beneficiaryAddress"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":1},"beneficiaryType":{"type":"string","enum":["company"],"example":"company"},"paymentMode":{"type":"string","description":"Cross-border bank transfer via SWIFT rails.","enum":["INTERNATIONAL"],"example":"INTERNATIONAL"},"companyName":{"type":"string","example":"Acme Exports Ltd"},"accountNumber":{"type":"string","description":"Required. Trimmed before validation, then uppercased for IBAN.\nAllowed characters at schema level: alphanumeric and `-+./'\"`.\nExact per-currency format is enforced at runtime.\n","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","example":"DE89370400440532013000"},"bankCode":{"type":"string","description":"SWIFT/BIC code.","example":"DEUTDEFF"},"bankName":{"type":"string","example":"Deutsche Bank","pattern":"^.+$"},"bankAddress":{"$ref":"#/components/schemas/ClientBankAddress"},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"},{"type":"object","description":"Required. Send at least `addressLine1` and `countryCode`.","required":["addressLine1","countryCode"]}]},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":false,"nullable":true},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.","nullable":true},"customReferenceLabel":{"type":"string","description":"Optional. Label for your own reconciliation.","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — create does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"}}},"CreateInternationalIndividual":{"type":"object","title":"Bank beneficiary (international) - individual","description":"Cross-border bank payout. `paymentMode` is `INTERNATIONAL`.\nRequires bank details, name fields, and beneficiary address. Do not send stablecoin fields.\n","required":["currencyId","beneficiaryType","paymentMode","accountNumber","bankCode","bankName","bankAddress","firstName","lastName","beneficiaryAddress"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":1},"beneficiaryType":{"type":"string","enum":["individual"],"example":"individual"},"paymentMode":{"type":"string","description":"Cross-border bank transfer via SWIFT rails.","enum":["INTERNATIONAL"],"example":"INTERNATIONAL"},"firstName":{"type":"string","example":"Jane"},"lastName":{"type":"string","example":"Doe"},"accountNumber":{"type":"string","description":"Required. Trimmed before validation, then uppercased for IBAN.\nAllowed characters at schema level: alphanumeric and `-+./'\"`.\nExact per-currency format is enforced at runtime.\n","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","example":"DE89370400440532013000"},"bankCode":{"type":"string","example":"DEUTDEFF"},"bankName":{"type":"string","example":"Deutsche Bank","pattern":"^.+$"},"bankAddress":{"$ref":"#/components/schemas/ClientBankAddress"},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"},{"type":"object","description":"Required. Send at least `addressLine1` and `countryCode`.","required":["addressLine1","countryCode"]}]},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":false,"nullable":true},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.","nullable":true},"customReferenceLabel":{"type":"string","description":"Optional. Label for your own reconciliation.","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — create does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"}}},"CreateInternationalMyOrganisation":{"type":"object","title":"Bank beneficiary (international) - myOrganisation","description":"Cross-border bank payout for your own organisation.\n`paymentMode` is `INTERNATIONAL`. No name fields required. Do not send stablecoin fields.\n","required":["currencyId","beneficiaryType","paymentMode","accountNumber","bankCode","bankName","bankAddress","beneficiaryAddress"],"properties":{"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":1},"beneficiaryType":{"type":"string","enum":["myOrganisation"],"example":"myOrganisation"},"paymentMode":{"type":"string","description":"Cross-border bank transfer via SWIFT rails.","enum":["INTERNATIONAL"],"example":"INTERNATIONAL"},"accountNumber":{"type":"string","description":"Required. Trimmed before validation, then uppercased for IBAN.\nAllowed characters at schema level: alphanumeric and `-+./'\"`.\nExact per-currency format is enforced at runtime.\n","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","example":"DE89370400440532013000"},"bankCode":{"type":"string","example":"DEUTDEFF"},"bankName":{"type":"string","example":"Deutsche Bank","pattern":"^.+$"},"bankAddress":{"$ref":"#/components/schemas/ClientBankAddress"},"beneficiaryAddress":{"allOf":[{"$ref":"#/components/schemas/ClientBeneficiaryAddress"},{"type":"object","description":"Required. Send at least `addressLine1` and `countryCode`.","required":["addressLine1","countryCode"]}]},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":true,"nullable":true},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.","nullable":true},"customReferenceLabel":{"type":"string","description":"Optional. Label for your own reconciliation.","nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — create does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"}}},"addBeneficiaryClient":{"description":"Create a beneficiary. Select a body shape below — only the fields for that\nshape are shown.\n- **Bank beneficiary (non-international)** — `LOCAL`, `MOBILE_MONEY`, or `HK_BANK` - **Bank beneficiary (international)** — `paymentMode: INTERNATIONAL` - **Stablecoin beneficiary** — crypto wallet (`paymentMode: STABLECOIN`)\n","oneOf":[{"$ref":"#/components/schemas/CreateBankBeneficiaryCompany"},{"$ref":"#/components/schemas/CreateBankBeneficiaryMyOrganisation"},{"$ref":"#/components/schemas/CreateBankBeneficiaryIndividual"},{"$ref":"#/components/schemas/CreateInternationalCompany"},{"$ref":"#/components/schemas/CreateInternationalMyOrganisation"},{"$ref":"#/components/schemas/CreateInternationalIndividual"},{"$ref":"#/components/schemas/CreateStablecoinBeneficiary"}]},"addBeneficiaryClientResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"accounts":{"$ref":"#/components/schemas/beneficiaryClient"}}},"Error":{"required":["message","code"],"type":"object","properties":{"message":{"description":"The error message indicating what the issue is","type":"string"},"code":{"description":"The error code","maximum":1000,"minimum":1,"type":"integer"}},"example":{"code":400,"message":"wrong input"}},"401Unauthorized":{"required":["message","success"],"type":"object","properties":{"message":{"description":"The error message indicating what the issue is","type":"string"},"success":{"description":"Success status of api","type":"boolean"}},"example":{"success":false,"message":"Unauthorized"}},"updateBeneficiaryClient":{"type":"object","description":"Update payload for an existing beneficiary. The update is merged with the existing record,\nso most body fields are optional. When a field is supplied, the same format/pattern/enum\nconstraints as `addBeneficiaryClient` apply.\n\n`currencyId`, `paymentMode` and `beneficiaryType` must always be supplied so downstream\nvalidation can resolve the correct currency/payment-mode configuration.\n\nRuntime conditional rules (enforced by the service, not by the JSON schema):\n  - Non-stablecoin paymentModes (`LOCAL`, `INTERNATIONAL`, `MOBILE_MONEY`, `HK_BANK`):\n    `accountNumber`, `bankCode`, `bankName` and `bankAddress.countryCode` are required.\n  - `INTERNATIONAL` paymentMode additionally requires `beneficiaryAddress.addressLine1`\n    and `beneficiaryAddress.countryCode`.\n  - When `beneficiaryType` is `company`, `companyName` is required (non-stablecoin). When\n    `individual`, `firstName` and `lastName` are required. `myOrganisation` has no name\n    field requirement.\n  - Stablecoin paymentMode (`STABLECOIN`): `cryptoCurrencyWalletAddress`, `blockchain`,\n    `cryptoCurrency` and `cryptoCurrencyWalletHostedOption` are required. When\n    `accountLabel` (wallet nickname) is supplied, `companyName` is required; otherwise\n    either `companyName` or both `firstName`+`lastName` must be provided, together with a\n    full `beneficiaryAddress` (`addressLine1`, `city`, `countryCode`, `postCode`,\n    `stateOrProvience`).\n  - SWIFT bank codes whose country (chars 5-6) is in the sanctioned (OORA) list are rejected.\n  - When the client's company category is `financial services` or `crypto`, `nestedType`\n    is required.\n","example":{"currencyId":25,"beneficiaryType":"company","paymentMode":"LOCAL","companyName":"Acme Trading Ltd","accountNumber":"98846622175","bankCode":"112233","bankName":"HDFC Bank","bankAddress":{"countryCode":"IN"}},"required":["currencyId","paymentMode","beneficiaryType"],"properties":{"accountNumber":{"type":"string","description":"Trimmed before validation, then uppercased for IBAN. Required for non-stablecoin payment modes. Allowed characters at schema level: alphanumeric and `-+./'\"`. Exact per-currency/payment-mode format (e.g. TZS/KES MOBILE_MONEY expect `+<country>-XXXXXXXXX`) is enforced by the runtime validator.","pattern":"^[0-9a-zA-Z\\s\\-+./'\"]*$","nullable":true,"example":"98846622175"},"accountLabel":{"type":"string","description":"Wallet nickname (primarily for stablecoin). Allowed characters: alphanumeric, spaces, and .,'&@#$^*/!()","maxLength":50,"nullable":true},"cryptoCurrency":{"type":"string","description":"Required when paymentMode is stablecoin.","enum":["USDC","USDT"],"nullable":true},"blockchain":{"type":"string","description":"Required when paymentMode is stablecoin.","enum":["ethereum_erc20"],"nullable":true},"cryptoCurrencyWalletAddress":{"type":"string","description":"Required when paymentMode is stablecoin. Must be a valid 0x-prefixed 40-character hex address.","maxLength":42,"nullable":true},"cryptoCurrencyWalletHostedOption":{"type":"string","description":"Required when paymentMode is stablecoin.","enum":["dedicated_wallet_via_custodian","exchange","self_hosted_wallet","not_known"],"nullable":true},"cryptoCurrencyWalletHostedOn":{"$ref":"#/components/schemas/CryptoCurrencyWalletHostedOn"},"cryptoCurrencyWalletHostedOnOtherOption":{"type":"string","nullable":true,"maxLength":30},"country":{"type":"string","example":"India","nullable":true},"bankAddress":{"type":"object","description":"When supplied, countryCode must reference an active supported 2-letter country code.","required":["countryCode"],"properties":{"countryCode":{"type":"string","pattern":"^(?=[A-Za-z]{2}$)[A-Za-z]*|$","example":"IN"},"stateOrProvience":{"type":"string","description":"State or province.","example":"State","nullable":true},"city":{"type":"string","example":"Pune","nullable":true},"postCode":{"type":"string","example":"789789","nullable":true},"address":{"type":"string","example":"abc address","nullable":true}}},"bankCode":{"type":"string","description":"Trimmed before validation. Required for non-stablecoin payment modes. SWIFT codes belonging to sanctioned (OORA) countries are rejected.","example":"0000000000","nullable":true},"altNationalId":{"type":"string","description":"Optional. A secondary identifier for the beneficiary account where `accountNumber`/`bankCode` alone isn't enough — for example a mobile money provider (`M-PESA`) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency. Trimmed before validation.","example":"M-PESA","nullable":true},"bankName":{"type":"string","description":"Required for non-stablecoin payment modes.","example":"000000","pattern":"^.+$","nullable":true},"companyName":{"type":"string","description":"Required when beneficiaryType is 'company' (non-stablecoin). Base validation allows alphanumerics and spaces; some currencies (e.g. AUD/CAD/CNY/HKD/IDR/JPY and other Asian locales) additionally permit `.` and `-` in company names — enforced by the runtime validator.","example":"DevikaTestCOmpany","nullable":true},"firstName":{"type":"string","description":"Required when beneficiaryType is 'individual' (non-stablecoin). Only alphanumeric characters and spaces are allowed.","example":"Jai","nullable":true},"lastName":{"type":"string","description":"Required when beneficiaryType is 'individual' (non-stablecoin). Only alphanumeric characters and spaces are allowed.","example":"MataDI","nullable":true},"beneficiaryAddress":{"type":"object","description":"Required for international payment mode and for currencies/payment modes where the configured rules mark beneficiary address as required. All individual fields (when present) must be up to 35 characters; only alphanumeric characters, spaces, and commas are allowed.","properties":{"countryCode":{"type":"string","description":"Required for international payment mode and when beneficiary address is required. Must be an active supported 2-letter country code.","pattern":"^(?=[A-Za-z]{2}$)[A-Za-z]*|$","nullable":true},"stateOrProvience":{"type":"string","description":"State or province. Required when beneficiary address is required.","example":"State","nullable":true},"city":{"type":"string","description":"Required when beneficiary address is required.","example":"Pune","nullable":true},"postCode":{"type":"string","description":"Required when beneficiary address is required.","example":"789456","nullable":true},"addressLine1":{"type":"string","description":"Required for `INTERNATIONAL` payment mode and when beneficiary address is required.","example":"somePlace far","nullable":true},"addressLine2":{"type":"string","example":"someplace","nullable":true},"mobileNumber":{"type":"string","description":"Required when currency-level configuration requires a recipient mobile number.","example":"999999999","nullable":true},"email":{"type":"string","description":"Required when currency-level configuration requires a recipient email. Must be a valid email address.","example":"test@gmail.com","nullable":true}}},"beneficiaryType":{"type":"string","description":"Type of beneficiary.","enum":["company","individual","myOrganisation"]},"companyEstablishmentDate":{"type":"string","example":"YYYY-MM-DD","nullable":true},"companyCountryOfTax":{"type":"string","example":"India","nullable":true},"companyIncorporationNumber":{"type":"string","example":"1234567890","nullable":true},"currencyId":{"type":"integer","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":4},"paymentMode":{"type":"string","description":"How the payout is delivered. Choose based on the rail:\n\n- `LOCAL` — Domestic bank transfer in the beneficiary's market.\n  Use a normal bank account number plus the local bank identifier\n  (sort code, local bank code, or SWIFT/BIC as required for the currency).\n  Example: GBP Faster Payments (`bankCode` = sort code, `accountNumber` = 8-digit account).\n\n- `INTERNATIONAL` — Cross-border bank transfer via SWIFT rails.\n  Requires `beneficiaryAddress.addressLine1` and `beneficiaryAddress.countryCode`.\n\n- `MOBILE_MONEY` — Mobile-wallet payout (not a bank account).\n  Available for **KES** and **TZS** only.\n  Put the phone number in `accountNumber` (e.g. `+254-712345678`) and the\n  wallet provider in `bankCode` / `bankName` (e.g. `M-PESA`).\n\n- `HK_BANK` — Pay **CNY** into a Hong Kong bank account\n  (`bankAddress.countryCode: HK`, 3-digit Hong Kong `bankCode`).\n  For **HKD** domestic payouts use `LOCAL`, not `HK_BANK`.\n\n- `STABLECOIN` — Crypto wallet payout. Do not send bank fields; send\n  `cryptoCurrencyWalletAddress`, `blockchain`, `cryptoCurrency`, and\n  `cryptoCurrencyWalletHostedOption` instead.\n","enum":["LOCAL","INTERNATIONAL","MOBILE_MONEY","STABLECOIN","HK_BANK"],"example":"LOCAL"},"customReferenceLabel":{"type":"string","example":"","nullable":true},"isSelfAccount":{"type":"boolean","description":"Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets `partyType` to `First_Party` when `true`, `Third_Party` otherwise. Set `true` for your own company's accounts (e.g. treasury/OPEX transfers); leave `false`/omit for third-party payees.","example":true,"nullable":true},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"documentDetails":{"type":"array","nullable":true,"description":"Optional. Supporting documents for this beneficiary.\n\nUse only after the 3-step upload flow on\n[Upload beneficiary documents](/reference/upload_beneficiary_documents):\n\n1. `POST /uploadDocuments` → receive `items[].link` and `items[].key`\n2. `PUT` file bytes to `items[].link` (expires in 15 minutes)\n3. Send `{ \"key\": \"<items[].key>\", \"name\": \"<fileName>\" }` here\n\nOmit this field, or send `[]`, unless Verto asks for supporting documents.\n","items":{"$ref":"#/components/schemas/ClientDocumentDetail"},"example":[{"key":"documents/example-file.pdf","name":"passport.pdf"}]},"copVerification":{"type":"string","description":"Optional. Confirmation of Payee (CoP) / name-check outcome.\n\nPass this only if you have already called `POST /confirm-payee`\nfor this account (mainly UK GBP local payouts) and want that\nresult stored on the beneficiary. Use the value from the CoP\nresponse (`status.detailedStatusIdentifier`), for example\n`MATCH_PERSONAL`, `CLOSE_MATCH`, or `NO_ACCOUNT`.\n\nOmit if you have not run CoP — update does not require this\nfield.\n","nullable":true,"example":"MATCH_PERSONAL"},"nativeCompanyName":{"type":"string","example":"test","nullable":true},"branchCode":{"type":"string","example":"000000","nullable":true},"companyRegistrationNumber":{"type":"string","example":"1234567890","nullable":true},"accountType":{"type":"string","example":"futsuu","nullable":true}}},"updateBeneficiaryResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"accounts":{"$ref":"#/components/schemas/beneficiarySSI"}}},"deleteResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"UploadDocumentRequest":{"type":"array","description":"JSON array of files to prepare for upload. Send the array as the raw\nrequest body (not wrapped in an object).\n","minItems":1,"example":[{"fileName":"passport.pdf","fileType":"application/pdf"}],"items":{"type":"object","required":["fileName"],"properties":{"fileName":{"type":"string","description":"Original file name including extension. Extension must be one of:\n`jpeg`, `jpg`, `pdf`, `png`, `svg`.\n","example":"passport.pdf"},"fileType":{"type":"string","description":"MIME type of the file (for example `application/pdf` or `image/jpeg`).\nAccepted for compatibility with clients; extension on `fileName` is\nwhat the service validates today.\n","example":"application/pdf"}}}},"UploadDocumentResponse":{"type":"object","description":"Signed upload targets for each requested file (same order as the request array).","properties":{"totalCount":{"type":"integer","description":"Number of signed upload items returned.","example":1},"items":{"type":"array","items":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` when a signed upload URL was generated for this file.","example":true},"link":{"type":"string","description":"Pre-signed S3 **PUT** URL. Upload the file bytes here within\n**15 minutes**. Do not use `url` for the upload.\n","example":"https://upload.example/signed-put-url"},"url":{"type":"string","description":"Object location for reference only. Not the upload target —\nalways PUT to `link`.\n","example":"https://files.example/documents/example-file.pdf"},"key":{"type":"string","description":"Store this value in `documentDetails[].key` on create/update\nafter you successfully PUT the file to `link`.\n","example":"documents/example-file.pdf"}}}}}},"confirmPayee":{"type":"object","example":{"type":"PERSONAL","name":"Jane Doe","accountType":"PERSONAL","sortCode":"200000","accountNumber":"12345678"},"oneOf":[{"required":["type","name","accountType","sortCode","accountNumber"]},{"required":["bankCountry","bankCode","accountNumber"]}],"properties":{"type":{"type":"string"},"countryCode":{"type":"string"},"bankCode":{"type":"string"},"name":{"type":"string","example":"devika","minLength":1,"maxLength":140},"accountType":{"enum":["PERSONAL","BUSINESS"]},"sortCode":{"type":"string","example":123456,"minLength":6,"maxLength":6},"accountNumber":{"type":"string","example":12345678}}},"confirmPayeeVerificationResponse":{"type":"object","properties":{"actualPayeeName":{"type":"string","example":"devika"},"status":{"type":"object","properties":{"identifier":{"type":"string","enum":["REJECTED","FAILED","CONFIRMED"],"description":"The main status identifier"},"detailedStatusIdentifier":{"type":"string","description":"Optional. Provides more specific detail about the status.","example":"MATCH_PERSONAL","nullable":true},"reason":{"type":"string","description":"Optional. Reason for the status.","example":"Name is a match to the account name. The type of account is 'Personal' when 'Business' was provided in the request.","nullable":true}}}}},"confirmPayeeVerificationResponseNG":{"type":"object","properties":{"bankCountry":{"type":"string","example":"NG"},"bankCode":{"type":"string","example":123456},"accountNumber":{"type":"string","example":12345678},"accountName":{"type":"string","example":"John Doe"}}},"CryptoCurrencyWalletHostedOn":{"type":"string","nullable":true,"description":"This field is based on the selected cryptoCurrencyWalletHostedOption, i.e. store custodian/exchange/self-hosted wallet details. This is null if cryptoCurrencyWalletHostedOption is not_known","maxLength":45,"enum":[null,"custodian_amber","custodian_anchorage_digital","custodian_bake","custodian_balance","custodian_bge","custodian_binance_us","custodian_bit_flyer","custodian_bitget","custodian_bit_go","custodian_bit_mex","custodian_bitpoint_japan","custodian_bitstamp","custodian_bloc_pal","custodian_bullish","custodian_bybit","custodian_cex_io","custodian_circle","custodian_coinbase","custodian_coincheck","custodian_coinhako","custodian_coinjar","custodian_coinpass","custodian_coin_smart","custodian_coinsquare","custodian_copper","custodian_crypto_com","custodian_curv","custodian_custodia","custodian_dtc","custodian_escrowffy","custodian_exmo","custodian_fdas","custodian_forum_pay","custodian_gemini","custodian_goobit","custodian_iconomi","custodian_kraken","custodian_lite_bit","custodian_luno","custodian_metallicus","custodian_netcoins","custodian_nexo","custodian_ok_coin","custodian_paxos","custodian_paypal","custodian_paysafe","custodian_phemex","custodian_prometheum_capital","custodian_revolut","custodian_ripio","custodian_robinhood","custodian_safello","custodian_standard_custody_and_trust","custodian_sfox","custodian_shakepay","custodian_skrill","custodian_standard_chartered","custodian_swiss_borg","custodian_taurus","custodian_trans_ficc","custodian_trijo","custodian_triple_a","custodian_virgo_cx","custodian_wealthsimple","custodian_zenus_bank","custodian_zero_hash","custodian_zodia_custody","exchange_amber","exchange_anchorage_digital","exchange_bake","exchange_balance","exchange_bge","exchange_binance_us","exchange_bit_flyer","exchange_bitget","exchange_bit_go","exchange_bit_mex","exchange_bitpoint_japan","exchange_bitstamp","exchange_bloc_pal","exchange_bullish","exchange_bybit","exchange_cex_io","exchange_circle","exchange_coinbase","exchange_coincheck","exchange_coinhako","exchange_coinjar","exchange_coinpass","exchange_coin_smart","exchange_coinsquare","exchange_copper","exchange_crypto_com","exchange_curv","exchange_custodia","exchange_dtc","exchange_escrowffy","exchange_exmo","exchange_fdas","exchange_forum_pay","exchange_gemini","exchange_goobit","exchange_iconomi","exchange_kraken","exchange_lite_bit","exchange_luno","exchange_metallicus","exchange_netcoins","exchange_nexo","exchange_ok_coin","exchange_paxos","exchange_paypal","exchange_paysafe","exchange_phemex","exchange_prometheum_capital","exchange_revolut","exchange_ripio","exchange_robinhood","exchange_safello","exchange_standard_custody_and_trust","exchange_sfox","exchange_shakepay","exchange_skrill","exchange_standard_chartered","exchange_swiss_borg","exchange_taurus","exchange_trans_ficc","exchange_trijo","exchange_triple_a","exchange_virgo_cx","exchange_wealthsimple","exchange_zenus_bank","exchange_zero_hash","exchange_zodia_custody","self_hosted_metamask","self_hosted_trust_wallet","self_hosted_exodus","self_hosted_atomic_wallet","self_hosted_ledger","self_hosted_trezor","self_hosted_electrum","self_hosted_wasabi_wallet","self_hosted_my_ether_wallet_mew","other"]},"beneficiarySSI":{"type":"object","properties":{"accountNumber":{"type":"string","example":1234567890},"fundType":{"enum":["exchange","wallets"],"example":"exchange"},"bankAddress":{"type":"object","properties":{"countryCode":{"type":"string","example":"IN"},"stateOrProvience":{"type":"string","description":"State or province.","example":"STOCKHOLM"},"city":{"type":"string","example":"Delhi"},"postCode":{"type":"string","example":110048},"address":{"type":"string","example":"204 Adam street"}}},"bankCode":{"type":"string","example":"CPANAU21"},"altNationalId":{"type":"string","description":"Secondary identifier for the beneficiary account (e.g. a mobile money provider or alternate national/bank identifier), if one was set.","example":"M-PESA","nullable":true},"bankName":{"type":"string","example":"HDFC"},"companyName":{"type":"string","example":"Verto international"},"companyRegistrationNumber":{"type":"string","example":"1234567890"},"clientCompanyName":{"type":"string","example":"Verto international"},"userRecordId":{"type":"number","example":1},"firstName":{"type":"string","example":"Adam"},"lastName":{"type":"string","example":"San"},"currencyId":{"type":"number","description":"Currency id for this beneficiary. Obtain currencyId from the guide on [Currency Codes Mapping](/docs/currency-codes).","example":1},"customLabel":{"type":"string","example":"Labled"},"partyType":{"enum":["First_Party","Third_Party"],"example":"First_Party"},"beneficiaryType":{"type":"string","example":"company"},"reference":{"type":"string","example":"RP-10082023-002"},"paymentMode":{"type":"string","example":"test"},"paymentCapabilities":{"type":"string","example":""},"isUpdateRequired":{"type":"boolean","example":true},"updateReason":{"type":"string","example":"test reason"},"verificationState":{"type":"string","example":"pending"},"id":{"type":"number","example":1},"companyId":{"type":"string","example":1},"smartWalletEnabled":{"type":"boolean","example":true},"isAccountActive":{"type":"boolean","example":true},"incoming_capability":{"type":"string","example":"all"},"priority":{"type":"number","example":1},"customReferenceLabel":{"type":"string","example":""},"industryRestriction":{"type":"array","items":{"type":"string","example":""}},"countryRestriction":{"type":"array","items":{"type":"string","example":""}},"beneficiaryAddress":{"type":"object","properties":{"companyName":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"countryCode":{"type":"string"},"stateOrProvience":{"type":"string","description":"State or province.","nullable":true},"city":{"type":"string"},"postCode":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string","nullable":true},"mobileNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"nestedType":{"$ref":"#/components/schemas/ClientNestedType"},"bankAccountId":{"type":"string","example":"69ca312cb32e4c78fdb1357d","nullable":true}}}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://api-beneficiary-sandbox.vertofx.com"}]}