--- updatedAt: 2026-05-20T05:45:37.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Beneficiary Use Cases Managing payment beneficiaries — bank accounts and mobile money destinations for withdrawals. A **beneficiary** is a saved payment destination linked to a wallet. Beneficiaries represent the bank accounts, mobile money wallets, or other payment destinations that a customer wants to pay to. They are used when initiating withdrawals via payment rails such as RTC, EFT, or mobile money. *** ## Create a Beneficiary Before a customer can withdraw funds to an external bank account, a beneficiary record must exist for that wallet. **Prerequisites:** A valid bearer token; a wallet ID ```http POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/beneficiaries ``` **Request body:** ```json { "walletId": 1092847, "accountHolderName": "Sipho Dlamini", "firstName": "Sipho", "lastName": "Dlamini", "bankName": "STANDARD_BANK", "branchCode": "051001", "bankAccountNumber": "123456789", "accountType": "CURRENT", "reference": "Salary withdrawal May 2026", "provider": "RTC" } ``` | Field | Required | Description | | -------------------- | -------- | -------------------------------------------------------------------------------------- | | `walletId` | Yes | The wallet this beneficiary belongs to | | `accountHolderName` | Yes | The beneficiary's full name as it appears on their bank account | | `firstName` | No | First name of the beneficiary | | `lastName` | No | Last name of the beneficiary | | `bankName` | Yes | The receiving bank (see supported banks below) | | `branchCode` | Yes | The bank's branch code | | `bankAccountNumber` | Yes | The beneficiary's bank account number | | `accountType` | No | `CURRENT`, `SAVINGS`, or `TRANSMISSION` | | `reference` | No | Payment reference shown on the beneficiary's statement | | `provider` | Yes | The payment rail to use (see supported providers below) | | `mobileNumber` | No | Mobile number for mobile money beneficiaries | | `mobileMoneyNetwork` | No | Mobile money network for mobile money beneficiaries | | `country` | No | ISO country code | | `alias` | No | Friendly alias for the beneficiary (e.g. `MyAccount` — used for scheduled withdrawals) | | `onlyCheck` | No | If `true`, validates account details via AVS without creating the record | | `saveOnPass` | No | If `true`, only creates the record if AVS validation passes | **Response (200 OK):** ```json { "beneficiaryId": 4829104, "walletId": 1092847, "accountHolderName": "Sipho Dlamini", "firstName": "Sipho", "lastName": "Dlamini", "bankName": "STANDARD_BANK", "branchCode": "051001", "bankAccountNumber": "123456789", "accountType": "CURRENT", "reference": "Salary withdrawal May 2026", "provider": "RTC", "status": "ACTIVE", "created": "2026-05-19T10:00:00.000Z" } ``` ### Supported Banks Common bank values for South African accounts: | Value | Bank | | ---------------- | ------------------- | | `ABSA` | ABSA Bank | | `STANDARD_BANK` | Standard Bank | | `FNB` | First National Bank | | `NEDBANK` | Nedbank | | `CAPITEC` | Capitec Bank | | `AFRICAN_BANK` | African Bank | | `INVESTEC` | Investec | | `TYME_BANK` | TymeBank | | `DISCOVERY_BANK` | Discovery Bank | > 📘 Note > > Contact your EFT Corporation account manager for the full list of supported banks and the correct bank identifiers for your region and payment provider. ### Supported Providers | Provider | Description | Settlement Time | | -------- | --------------------------------- | ------------------- | | `RTC` | Real-Time Clearing (South Africa) | Near-instant (24/7) | | `EFT` | Electronic Funds Transfer | 1–2 business days | | `DTB` | Same-day batch clearing | Same business day | | `MTN` | MTN Mobile Money | Near-instant | | `TANDA` | Tanda mobile money | Near-instant | Provider availability depends on your tenant's configuration. Contact to enable specific providers. *** ## Retrieve Beneficiaries for a Wallet List all beneficiaries associated with a wallet. ```http GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/beneficiaries?walletId={walletId}&limit=50&offset=0 Authorization: Bearer {jwt} ``` **Response:** ```json [ { "beneficiaryId": 4829104, "walletId": 1092847, "accountHolderName": "Sipho Dlamini", "bankName": "STANDARD_BANK", "branchCode": "051001", "bankAccountNumber": "123456789", "accountType": "CURRENT", "reference": "Salary withdrawal May 2026", "provider": "RTC", "status": "ACTIVE", "created": "2026-05-19T10:00:00.000Z" }, { "beneficiaryId": 7391048, "walletId": 1092847, "accountHolderName": "Nomsa Khumalo", "bankName": "ABSA", "branchCode": "632005", "bankAccountNumber": "987654321", "accountType": "SAVINGS", "reference": "Loan repayment", "provider": "RTC", "status": "ACTIVE", "created": "2026-04-10T08:30:00.000Z" } ] ``` ### Query Parameters | Parameter | Description | | ------------------- | ------------------------------------------- | | `walletId` | Filter by wallet ID | | `customerId` | Filter by customer (user) ID | | `organisationId` | Filter by organisation ID | | `bankAccountNumber` | Filter by bank account number | | `mobileNumber` | Filter by mobile number | | `limit` | Number of results to return (default: 1000) | | `offset` | Pagination offset (default: 0) | *** ## Get a Specific Beneficiary ```http GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/beneficiaries/{beneficiaryId} ``` **Response:** Same structure as the list response, for a single beneficiary. *** ## Update a Beneficiary Update the reference or other mutable fields on an existing beneficiary. ```http PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/beneficiaries/{beneficiaryId} ``` **Request body:** ```json { "reference": "Updated reference — June 2026", "accountHolderName": "Sipho T. Dlamini" } ``` > ⚠️ Warning > > Bank account details (account number, bank, branch code) are immutable after creation for audit and fraud prevention purposes. To change these, delete the existing beneficiary and create a new one. *** ## Delete a Beneficiary ```http DELETE /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/beneficiaries/{beneficiaryId} ``` **Response:** `204 No Content` Deletion permanently removes the beneficiary record. *** ## Using a Beneficiary in a Withdrawal Once a beneficiary is created, initiate a withdrawal using the standard withdrawal endpoint. Supply the destination bank account details (`accountNumber`, `bank`, `branchCode`, `accountName`) directly in the withdrawal request — there is no `beneficiaryId` field in the withdrawal request body. ```http POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals ``` ```json { "amount": 1200.00, "type": "ZA_SB_EFT", "accountNumber": "123456789", "bank": "Standard Bank of South Africa", "branchCode": "051001", "accountName": "Sipho Dlamini", "description": "Salary withdrawal", "externalUniqueId": "eft-a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` See the [Withdrawal Use Cases](https://developer.eftcorp.com/docs/withdrawal-use-cases) for the complete withdrawal flow. *** ## Beneficiary Validation Eclipse validates beneficiary details at the point of withdrawal initiation. Depending on the payment provider: * **RTC**: Account number, branch code, and bank code are validated against the South African NPCI clearing system. * **EFT**: Details are validated at file generation time. Failures are reported via the withdrawal status callback. * **Mobile money**: Phone number format is validated against the provider's E.164 requirements. If a beneficiary fails validation, the withdrawal will move to `ERROR` status with a descriptive error code in the response.