Skip to content

Nedbank

Jump to bottom
RubenGeo edited this page Feb 5, 2025 · 9 revisions

Nedbank

This page contains information about configuring the Nedbank FSP integration in a 121 Platform Instance.

Configure Environment Variables

For the Nedbank FSP integration to work for any program, some settings need to be configured via environment variables:

Account Number

NEDBANK_ACCOUNT_NUMBER

The value is the account number used for the Nedbank integration.

Client ID

NEDBANK_CLIENT_ID

The value is the client secret provided by Nedbank.

API URL

NEDBANK_API_URL

The value is the base URL of Nedbank's API. The sandbox URL is https://b2b-api.nedbank.co.za/apimarket/b2b-sb/. In production and staging, a different URL is used.

Certificate Path

NEDBANK_CERTIFICATE_PATH

The value is the location of the TLS certificate needed for the connection to work. Nedbank provides this certificate.

Certificate Password

NEDBANK_CERTIFICATE_PASSWORD

The value is the password for the TLS certificate.

Payment flow

When a payment is made to a registration with a Nedbank FSP, 'Nedbank Vouchers' are created. These vouchers are represented by a code that is sent via text to the registrations, who can redeem the money at 'cash points'.

After a payment is made in the 121 platform, transactions are created with the status 'waiting' (indicating that the registration still needs to pick up the money). In a nightly cronjob, the latest status of the Nedbank Voucher is retrieved (see the mapping below) and the transaction status is updated accordingly. The updating of voucher status can also be manually triggered by calling: /api/financial-service-providers/nedbank.

Nedbank voucher statuses can be exported with the 'payment export'.

Nedbank Voucher Status to Transaction Status Mapping

This table maps the NedbankVoucherStatus to the corresponding TransactionStatusEnum in the system.

Nedbank Voucher Status Transaction Status
PENDING waiting
PROCESSING waiting
REDEEMABLE waiting
REDEEMED success
REFUNDED error
FAILED error

Nedbank API documentation

For more information about Nedbank's API used, see the Nedbank CashOut API documentation on Nedbank's website.

Payment Reference Prefix Configuration

For payments made through Nedbank, a paymentReferencePrefix must be configured via Program FSP Configurations. This prefix appears on bank statements and must meet Nedbank’s requirements.

Configure paymentReferencePrefix via Program FSP Configurations

The client must provide a paymentReferencePrefix, which needs to be configured for every program that uses the Nedbank FSP integration.

To configure the paymentReferencePrefix for a specific program, use the following API call:

POST api/programs/{programId}/financial-service-provider-configurations/{configuration-name}/properties

With the payload:

{
  "name": "paymentReferencePrefix",
  "value": "[paymentReferencePrefix]"
}

Replace [paymentReferencePrefix] with the value provided by the client.

Key Considerations:

  • The prefix must contain only letters, numbers, and hyphens (-); other characters are removed.
  • The final payment reference is a combination of the sanitized prefix (max 18 characters) and the recipient’s phone number.
Clone this wiki locally