PayU South Africa
API Version
Minimum required API version: 1.1.0
The following features require an API version higher than the minimum:
- 3DS 2.0 External requires API version 1.3.0
Payment Methods
The tables below lists payment methods that are supported through a server-to-server integration and through the PayU payment page. When integrating a payment method, the Authorization, Capture and Charge request types are supported unless stated otherwise in the Only for Requests column.
Server-to-Server Integrations
The following table lists all supported payment methods through a server-to-server integration.
Payment Method | Payment Method Type | Only for Requests |
---|---|---|
American Express | Cards | |
Capitec Pay | Bank Transfer | |
DINERS | Cards | |
DISCOVERYMILES | Loyalty | |
EBUCKS | Loyalty | Charge |
EFT PRO | Bank Transfer | |
MASTERCARD | Cards | |
MASTERPASS | eWallet | Charge |
MOBICRED | eWallet | Charge |
VISA | Cards |
Payment Page
The following table lists all supported payment methods available on the PayU payment page. For each supported payment method, the API Value column list the value you need to pass in the payment_method.additional_details.supported_payment_methods
array of the Create Charge request.
Payment Method | API Value | Only for Requests |
---|---|---|
American Express | CREDITCARD | |
Capitec Pay | OPEN_BANKING | Charge |
DINERS | CREDITCARD | |
Discovery Miles | DISCOVERYMILES | |
eBucks | EBUCKS | |
EFT PRO | EFT_PRO | Charge |
FASTA | FASTA | Charge |
MASTERCARD | CREDITCARD | |
Mobicred | MOBICRED | |
Mobicred Virtual Credit | MOBICRED_VIRTUAL_CREDIT | |
MoreTyme | MORETYME | |
Payflex | PAYFLEX | |
PayPal | PAYPAL | |
RCS | RCS | |
RCS PLC | RCS_PLC | |
Samba | CREDITCARD | |
VISA | CREDITCARD |
Currencies
ZAR
Features
The following table provides an overview of all supported and non-supported features.
Feature | Supported |
---|---|
3DS 2.0 External | Yes |
3DS 2.0 PaymentsOS-handled | No |
3DS 2.0 Provider-handled | Yes |
3DS 2.0 Self-handled | No |
Installments | Yes |
Level 2 and 3 Data | No |
Multi-seller Payments | No |
Network Tokens | No |
Payment Facilitator | No |
PayU Risk | No |
Pre-authorization | No |
Retrieve Supported Payment Methods | No |
Retrieve Supported Plans | No |
Statement Soft Descriptor | Yes |
Stored Credentials Flag | Yes |
Transaction Processing without CVV | Yes |
Requests
The following table lists all supported requests for card-based transactions. Use the bodybuilder to create a sample request body for each request type.
Request | Partial/Multiple | Mode | Notes |
---|---|---|---|
Authorize | Partial and multiple are not supported | Asynchronous or Synchronous | The request can be synchronous or asynchronous, depending on whether you implemented a 3DS flow. |
Capture | Partial is supported | Synchronous | |
Charge | Not Applicable | Asynchronous or Synchronous | The request can be synchronous or asynchronous, depending on whether you implemented a 3DS flow. |
Refund | Both partial and multiple are supported | Synchronous | |
Void | Not Applicable | Synchronous |
Setup Procedures
Creating a Provider Configuration
When creating a new provider configuration in the PaymentsOS Control Center, select PayU South Africa as the provider.The following table lists the setup procedures that are specific to this provider.
Configuration | Required/Optional |
---|---|
In the PaymentsOS Control Center, configure the following credentials:
| Required |
In your PayU South Africa account, verify whether 3DS is configured to be optional or required and handle the 3DS flow accordingly. For more information, see Enabling 3DS below. Contact PayU South Africa support for assistance. | Required |
In your PayU South Africa account, disable the cvv check if you do not require customers to enter their cvv code when initiating a payment. Contact PayU South Africa support for assistance. | Optional |
In your PayU South Africa account, enable the payment methods you want to display in the payment page. For more information, see Implementing a Payment Page Flow below. Contact PayU South Africa support for assistance. | Optional |
In your PayU South Africa account, enable support for passing a custom mark_off reference number for reconciliation purposes (supported with card transactions only). Contact PayU South Africa support for assistance. | Optional |
If you want to allow payments in instalment when using the Payment Page, contact PayU South Africa to ensure this option is enabled in your account. | Optional |
Integration Procedures
The following sections list the integration procedures that are specific to this provider.
Enabling 3DS
Note
3DS must be implemented as part of a redirection flow. For an overview of how to implement a redirection flow, see Implementing a Redirection Flow.If you require 3DS, contact PayU South Africa support to configure the following IPN URLs in your PayU South Africa environment:
- For working with the PaymentsOS test environment: https://api.paymentsos.com/callbacks/magellan/test/redirection
- For working with the PaymentsOS live environment: https://api.paymentsos.com/callbacks/magellan/live/redirection
After configuring the IPN URLs, configure Webhooks in your PaymentsOS environment to receive updates when a change in a transaction status occurs.
Note that in your PayU South Africa account, you can configure 3DS to be either required (force 3DS) or optional. If you configured your account to enforce 3DS, then the user will always be required to complete a 3DS authentication step. If you configured 3DS to be optional and you want the user to complete a 3DS authentication step, then include a provider_specific_data
object with an is3ds
value of true
in your Create Authorization or Create Charge API requests.
"provider_specific_data": {
"magellan": {
"additional_details": {
"is3ds": "true"
}
}
Regardless of whether 3DS is set to required or optional, PayU South Africa will only direct a user to complete a 3DS authentication flow if a user’s card is enrolled for 3DSecure.
Bear in mind that a 3DS redirection flow requires that you pass a merchant_site_url
in the Create Authorization or Create Charge request. If you do not pass a merchant_site_url
, the user will not be able to complete the 3DS authentication flow. The response data of the Create Authorization or Create Charge request will indicate this in the additional_details.error
field:
{
"additional_details": {
"error": "The transaction requires 3DS authentication, but cannot be completed as the merchant_site_url was not provided"
}
...
}
Note
If the user could not complete the 3DS authentication flow, the transaction will remain in statusPending
. After 40 minutes, the transaction will transition to a status of Failed
.
Processing Payments without a CVV Check
If you disabled the cvv check in your account, you will need to pass a recurring
field with a value of true
in the provider_specific_data
object.
"provider_specific_data": {
"magellan": {
"additional_details": {
...
},
"recurring": true
}
Implementing a Payment Page Flow
If desired, you can implement a payment flow in which users are redirected to a payment page where they can then select their payment method of choice. This flow is identical to a redirection flow, in which the response of the Create Charge request returns a Redirection
object that includes the URL of the payment page to which you can redirect the user. Just make sure that your Create Charge request includes a payment_method.additional_details.supported_payment_methods
field with a comma separated list of the payment methods you want to show in the payment page:
{
"payment_method": {
"source_type": "payment_page",
"type": "untokenized",
"additional_details": {
"supported_payment_methods": "CREDITCARD,[SEE TABLE SUPPORTED PAYMENT METHODS]"
}
}
}
A few caveats:
-
In your PayU account, you must enable the payment methods you want to show in the payment page.
-
Authorize and Capture requests are not supported in a payment page flow.
-
When using the BodyBuilder to generate sample requests, make sure to choose the Payment Page payment type.
Testing
For testing, use the cards listed below. For any of the cards, use 02/2026 as expiry date and 123 as CVV.
VISA - Simulator Matrix for basic 3DS Scenarios
Card Type |
PAN |
Card Enrolled |
OTP Success |
ECI |
Description |
Risk Setting: Fully Authenticated = OFF |
---|---|---|---|---|---|---|
VISA 3DS test scenarios for 2 different 3DS authentication mode settings |
Transaction Result |
|||||
VISA |
4000015372250142 |
YES |
YES |
05 |
Cardholder Authentication Success + Bank response success |
Approved |
VISA |
4000019562093601 |
YES |
NO |
|
Cardholder Authentication Failure |
Transaction Failed |
VISA |
4000019542438801 |
NO |
N/A |
06 |
Issuer/Cardholder not participating |
Transaction Successful |
VISA |
4000029520272445 |
YES |
YES |
05 |
Cardholder Authentication Success + Bank response failure |
Transaction Failed |
MasterCard - Simulator Matrix for basic 3DS Scenarios
Card Type |
PAN |
Card Enrolled |
OTP Success |
ECI |
Description |
Risk Setting: Fully Authenticated = OFF |
---|---|---|---|---|---|---|
MasterCard 3DS test scenarios for 2 different 3DS authentication mode settings |
Transaction Result |
|||||
MasterCard |
5100018609086541 |
YES |
YES |
02 |
Cardholder Authentication Success |
Transaction Successful |
MasterCard |
5100013960913581 |
YES |
NO |
|
Cardholder Authentication Failure |
Transaction Failed |
MasterCard |
5100011063555010 |
NO |
N/A |
01 |
Issuer/Cardholder not participating |
Transaction Successful |
MasterCard |
5100022615342534 |
YES |
YES |
02 |
Cardholder Authentication Success + Bank response failure |
Transaction Failed |
For payment methods that require OTP or any form of user authentication (for example RCS or Discovery miles) when posting test transactions, ensure that the following key-value pair is set:
“demo_mode”
: “false”
Important Note
For other payment methods that do not require this level of connectivity, the key-value pair for test transactions is not required. However, when transactions are sent to production, this flag must always be set to “false”.This setting should be included in the provider-specific object details, as illustrated below:
"provider_specific_data": {
"payusouthafrica": {
"additional_details": {
"demo_mode": "false"
}
}
}
3D Secure
For testing 3D secure transactions, use the following accounts.
3DS redirect:
- Username: 800060
- Password: qDRLeKI9
- Safekey: {FBEF85FC-F395-4DE2-B17F-F53098D8F978}
3DS no-redirect:
- Username: 800059
- Password: 0aSlJ068
- Safekey: {38D2290B-712B-4D86-B514-E450A1788F91}