Selling

Payment methods

Hlawula accepts eight payment methods. Wallets and cards work for buyers anywhere; Capitec Pay, Absa Pay, Nedbank Direct EFT and Pay by bank are for buyers in South Africa. PayFast or Peach processes all of them, and your customer only sees Hlawula.

Method	id	Who can use it	How the buyer approves
Apple Pay	`apple_pay`	Everyone	Face ID or Touch ID
Google Pay	`google_pay`	Everyone	Device unlock
Samsung Pay	`samsung_pay`	Everyone	Fingerprint or PIN
Card	`card`	Everyone	Card details, 3-D Secure
Capitec Pay	`capitec_pay`	South Africa	In the Capitec app
Absa Pay	`absa_pay`	South Africa	In the Absa Banking App
Nedbank Direct EFT	`nedbank_direct_eft`	South Africa	Signs in to Nedbank Money
Pay by bank	`pay_by_bank`	South Africa	Signs in to their own bank

Apple Pay first

On the hosted checkout, Apple Pay is the first button. It's the fastest way to pay: no typing, one glance, done. Google Pay and Samsung Pay sit right under it. Everyone else picks card or their bank below.

Wallets return an encrypted payment token from the device. You send that token to the pay endpoint and the aggregator decrypts it; card details never touch your servers or ours.

Request body

{ "method": "apple_pay", "walletToken": "<token from ApplePaySession>" }

Before going live with Apple Pay

Apple requires the paying domain to be verified and served over HTTPS, and only shows the button in Safari and on Apple devices. The demo checkout uses a stand-in payment sheet and a placeholder token, so it works in any browser. Use Apple's official button and sheet in production.

Cards

Request body

{
  "method": "card",
  "cardNumber": "4242 4242 4242 4242",
  "expiry": "12/30",
  "cvc": "123",
  "name": "Thandi Mokoena"
}

We check the number passes the Luhn check, the expiry hasn't passed and the security code is 3 or 4 digits. In the demo, card details reach the API directly; in production they go straight to the aggregator's hosted fields.

South African bank payments

Capitec Pay and Absa Pay

The buyer enters the cellphone number linked to their banking app. The bank sends an approval request to the app, and the payment completes when they approve it.

Request body

{ "method": "capitec_pay", "mobile": "082 123 4567" }

Numbers can be written as 082 123 4567, 0821234567 or +27 82 123 4567.

Nedbank Direct EFT and Pay by bank

The buyer signs in to their bank, checks the amount and approves an EFT. Pay by bank works with Absa, Capitec, Discovery Bank, FNB, Investec, Nedbank, Standard Bank and TymeBank.

Request body

{ "method": "pay_by_bank", "bank": "FNB" }

Which methods a buyer can use

Ask for the list with the buyer's country. Each method comes back with available set for that country.

bash

curl "$HLAWULA_URL/api/payment-methods?country=GB"

Paying with a South Africa only method for a buyer elsewhere returns 400 method_unavailable.

Errors

Code	When
`method_unknown`	The method id isn’t one of the eight above.
`method_unavailable`	The method isn’t offered in the buyer’s country.
`wallet_token_missing`	A wallet payment arrived without a token.
`card_invalid`	The card number fails validation.
`expiry_invalid`	The expiry date is malformed or in the past.
`cvc_invalid`	The security code isn’t 3 or 4 digits.
`mobile_invalid`	The cellphone number isn’t a South African mobile number.
`bank_invalid`	Pay by bank was used without one of the supported banks.