ZAR Bank Collections

ZAR bank EFT transactions are supported on the DusuPay API. The customer is redirected to the payment URL and there, they're allowed to log into their online banking and complete the transaction.

Overview

Before starting, your merchant account needs to have been enabled to do funds collections from South African banks. We equally recommend that you go through the Getting Started section to have a high-level understanding of the funds collection process.

When the initial API request is successful, the customer will be redirected to a payment URL where they'll be guided to complete the transaction. During the process, the customer chooses their bank and they're guided to access their online banking portal and while there, they authorize the payment for the requested amount.

Step 1: Obtain the required data for the payment request

The table below describes the request parameters that are used for the collection/charge request. Most/all will be collected from the paying customer.

Parameter	Type	Required	Description
merchant_reference	String	true	The unique reference for this request. It must be at least 8 characters long. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API
transaction_method	String	true	The transaction method to be used. This will be BANK for this request
currency	String	true	The 3-character ISO currency code for the request currency
amount	Number	true	The amount being requested
provider_code	String	true	The provider code as obtained from the payment options list
customer_name	String	false	The name of the customer
customer_email	String	false	The email of the customer
description	String	true	The description/narration for the transaction. Between 10-30 characters
charge_customer	Boolean	false	Whether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge
allow_final_status_change	Boolean	false	Whether or not the final transaction status can be altered as described here. By default, this is true to mean DusuPay will alter the final transaction status under the circumstances described.
redirect_url	String	true	The HTTPs redirect URL to which the API will redirect when the payment is successful/failed

After collecting the necessary bank payment information from your customer, prepare your request payload as demonstrated below.

{
	"merchant_reference": "auto",
	"transaction_method": "BANK",
	"currency": "ZAR",
	"amount": 50,
	"provider_code": "bank_za",
	"customer_email": "[e-mail]",
	"customer_name": "JOHN DOE",
	"description": "Test Collection",
	"charge_customer": false,
	"allow_final_status_change": true,
	"redirect_url": "https://your-redirect-url"
}

POST https://sandboxapi.dusupay.com/collections/initialize

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

curl -X POST "https://sandboxapi.dusupay.com/collections/initialize" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "transaction_method": "BANK",
        "currency": "ZAR",
        "amount": 50,
        "provider_code": "bank_za",
        "customer_email": "[e-mail]",
        "customer_name": "JOHN DOE",
        "description": "Test Collection",
        "charge_customer": false,
        "allow_final_status_change": true,
        "redirect_url": "https://your-redirect-url"
    }'

202: Accepted - Request acknowledged for processing

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "DUSUPAYZAERK2SBE6WJAG",
        "merchant_reference": "MCTREFQSSBHMHU3RCTLA",
        "payment_url": "https://devpay.dusupay.com/pay/collection/DUSUPAYZAERK2SBE6WJAG"
    }
}

400: Bad Request - Request is not formed as expected

{
    "code": 400,
    "status": "error",
    "message": "Invalid provider code (bank_ug)",
    "data": {}
}

Step 2: Redirect to Payment URL

Notice the payment_url parameter in the callback body. The URL should be loaded in the browser so that the customer can proceed with the transaction. When the page loads, the customer will be guided through the payment process and on success/failure, the customer will be redirected to the redirect_url sent by the merchant in the request. Additionally, a callback/webhook will be sent to the configured collection callback URL.

Step 3: Handle the redirect and/or callback

Redirect

On success/failure of the transaction, the customer will be redirected to the URL that was passed in the redirect_url request parameter. The sample requests below demonstrated the success and failure scenarios. You can copy the URL and paste it on this online resource in order to view the query parameters therein.

Redirect on success

https://webhook.site/cc0393dc-fe49-401b-ba56-da9e099a3648?id=33911&event=transaction.completed&merchant_reference=MCTREFZQTUDRC38TLYUV&internal_reference=DUSUPAYHYJQ3ZUJMPGFG5&transaction_type=COLLECTION&transaction_status=COMPLETED&status_message=Transaction%20Completed%20Successfully&rsa_signature=Y23aNOaOs6NfOnrhpZrWGAOI4bMR5kNobFnrOBlqF%2FY7f03aBpHZx2rcmU3q2P9zS2w61xs3FsT%2FipRI9F21dNJ0UxDQci7yQ%2B7CZbk6kJQbfX9Ht7OIhH2%2F7cv%2FNUXDmXzZQYST3Qwe9QIhea1SIImWRzR8HKAeEeoVRPLDqxohLX4A0S91hjrZVO%2BjohZJLazIeXFrOaJyIu3xPQ7bzJi%2BfVhw6ry3R7NknIj5y752WpW0CqvxXKr3wPUIXy99tnN%2FCWLG65AmVL9GkBZj0j12%2B8ztBpknPBuGKWxndJB7zkkPTCmA%2BA1m21f3RENYTNH7nHet5zp5Iyq%2BkmtVVUmEcfvfAwAxs0sP0fYTFU8iSX6wvB6UEvk3AWgrprlb1XGd3sRgFgCb3HjzA7%2B8RBi%2Fw59qIXqK4LlbOtZw2tPc7MjLeXq%2BmqzrO8SRxyuvu6lX0HPhaHSXAGq%2BvljA1Kk4ZNLdSWxYCC2IgI7%2BPomrfWW1I6pNIF%2BudPTIYTPN6EEdMUwFBltyAoh%2ByHl6K%2F%2Fcz4FfE6OgZwJkbQ8661sHqiB2ND%2FhSQh%2B0Qre1tQTLx7BGQTSGdD34CLn%2FQICIlqNCvKbMF4ZO208xYaBct01T6Xa23zykkrmlTviEMJgSIo3zj2KpN%2BTF1X5jZOXLszBL20o1SeQlY9%2BhRzshzY%3D&hmac_signature=t%3D1721639784089%2Cs%3D1ec4e0f7749397faea80958bca9ab2c6d8e7448c3ee02f958881a392ce299128

Redirect on failure/cancellation

https://mysite.com?id=34639&event=transaction.failed&merchant_reference=MCTREF8DQRHYTNCQTACH&internal_reference=DUSUPAY8A54ZUJFGSMENE&transaction_type=COLLECTION&transaction_status=FAILED&status_message=Balance%20Insufficient%20for%20the%20transaction&rsa_signature=yvODC%2BViCiZmlEEEbQX1B%2FfQ0kNzrYqRN0c3Y8MjzZ%2FiMNVzf%2BUS36Ec8P1a0rOKgyc0l7KVbzEJwMZu0nasAHFuCeSOebs5NOHvSNJkAbQE2nZXgxvo1uQtJOMnbYZZKIvswemRTRGEyAKl7bRGc2AXzYRzJBVOYBVDOM0o36FUpfNNFrucVjvrmJJD8YtRtIXk3RjBzXkhV%2B3KAjWx0KU8bh424OyZUwsRTaN0MeuQMFY%2FkeuFvNKPzxKtN%2BaJqcx4aDZes6thevgfCljgne0ibC9Zy1eDCYP8A1T%2BNTS%2FHUZBuy1Y%2BzAmQ%2BMjnoiI%2FVk2I%2BuoRkHU01%2BMV%2Bo4CFGAoheoQ9N%2B7KFN0f4oAdT3G%2BJZtcwitZ0Q3Jo%2FW3aYNyvrPQHt88hjOtVHKhSNEwUJ8QNfy42WiZJOix4p5I5oyePdYGW5ia09MuaY6BkV8o9mdotcWGpn6O1PsxnxfduI6gbGLWtcxjrat75LeMhGjPLYcJA9CQECK7NvBFHOBUA%2F9rR5gReBVEkdVf5N8q551DvJfR4nENxZukaVMzjhq2IIndOHzRXTyXIxVKGhWAAcGXrVKcXvUvh8Np%2FlJg2bz4xWarvbk%2FFSrXYJj5IwNrOB02N5IzoVCGSyE%2BGWjofyUhgrq%2Ftlralnyp0GpXong2Sl8xB0%2Foucm4xtC60%3D&hmac_signature=t%3D1721967214552%2Cs%3D0a3505923c0541166952726c9c32c9dfdec41d51e4b1016093a6f53f0b9a76e9

Callback/Webhook

Every merchant account is expected to have configured a callback/webhook URL for collections. For all collections that transition to the final state (COMPLETED, FAILED or CANCELLED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

Successful Bank Transfer

{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "DUSUPAYRMGRXNNYBWATKJ",
        "transaction_type": "COLLECTION",
        "request_currency": "ZAR",
        "transaction_amount": 50,
        "transaction_currency": "ZAR",
        "transaction_charge": 1,
        "transaction_account": "2121562123",
        "charge_customer": false,
        "total_credit": 49,
        "provider_code": "bank_ng",
        "request_amount": 50,
        "customer_name": "JOHN DOE",
        "institution_name": "FNB",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Failed Request

{
      "event": "transaction.failed",
      "payload": {
        "id": 26609,
        "merchant_reference": "MCTREFNRFRTQA6SCWT5X",
        "internal_reference": "DUSUPAYWYUF8CR3ZRCGYU",
        "transaction_type": "COLLECTION",
        "request_currency": "NGN",
        "transaction_amount": 40000,
        "transaction_currency": "NGN",
        "transaction_charge": 0,
        "transaction_account": "2121562456",
        "charge_customer": false,
        "total_credit": 0,
        "provider_code": "mtn_ug",
        "request_amount": 40000,
        "customer_name": "JOHN DOE",
        "transaction_status": "FAILED",
        "status_message": "Request timed out without a transfer"
      }
    }

Either of the two (redirect/callback) can be used to confirm the final status of the transaction. We recommend that in either situation, the redirect/callback request is verified (by verifying the signatures)