Beneficiary Use Cases

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

POST /rest/v1/beneficiaries

Request body:

{
  "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 (201 Created):

{
  "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 [email protected] to enable specific providers.

Retrieve Beneficiaries for a Wallet

List all beneficiaries associated with a wallet.

GET /rest/v1/beneficiaries?walletId={walletId}&limit=50&offset=0
Authorization: Bearer {jwt}

Response:

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

GET /rest/v1/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.

PUT /rest/v1/beneficiaries/{beneficiaryId}

Request body:

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

DELETE /rest/v1/beneficiaries/{beneficiaryId}

Response: 204 No Content

Deletion is a soft delete — the beneficiary record is retained for audit purposes with status: "DELETED" and will not appear in future list queries.

Using a Beneficiary in a Withdrawal

Once a beneficiary is created, reference its beneficiaryId when creating a withdrawal:

POST /rest/v1/withdrawals

{
  "walletId": 1092847,
  "amount": 1200.00,
  "currency": "ZAR",
  "beneficiaryId": 4829104,
  "description": "Salary withdrawal",
  "externalUniqueId": "eft-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

See the 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 FAILED status with a descriptive error code in the response.