Introduction

Local Payments Africa is a leading payment method provider for Africa, offering a comprehensive range of payment solutions, including Cash, Vouchers, Mobile, and eWallets.

Supported Countries

• Benin (Payout)
• Burkina Faso (Deposit)
• Cameroon (Deposit)
• Central African Republic (Payout)
• Chad (Payout)
• Egypt (Deposit)
• Gabon (Payout and Deposit)
• Ghana (Payout)
• Ivory Coast (Payout and Deposit)
• Nigeria(Payout)
• Rwanda (Deposit)
• Senegal (Payout and Deposit)
• South Africa (Payout and Deposit)
• Tanzania (Payout and Deposit)
• Uganda (Payout and Deposit)
• Zambia(Payout)

Supported Currencies

• EGP (Deposit)
• GHS (Payout and Deposit)
• NGN (Payout and Deposit)
• RWF (Deposit)
• TZS (Payout and Deposit)
• UGX (Deposit)
• USD (Payout)
• XAF (Payout and Deposit)
• ZAR (Payout and Deposit)
• ZM (Payout and Deposit)

Payment (Deposit) Flow

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Local_payments_Africa“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, country, email, phone
• userDetails class containing: firstName, lastName, country, email, phone

Example /payment Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"100",
  "currency":"EGP",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_Local_payments_Africa"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"EG",
    "email":"[email protected]",
    "phone": "201162552644"
  },
  "userDetails":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"EG",
    "email":"[email protected]",
    "phone": "201162552644"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response

{
  "internalRequestId": 1192167198,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "979047831696752006",
  "merchantSiteId": "217268",
  "version": "1.0",
  "clientRequestId": "20240801143414",
  "sessionToken": "bd847f27-cb4d-4756-b2f1-85d8c3ea952a",
  "clientUniqueId": "20180327175242",
  "orderId": "475814288",
  "userTokenId": "TestToken",
  "paymentOption": {
    "redirectUrl": "https://gw-apm-globalpayapi.nuvei.com/Home?PaymentToken=8DCDBC1EEBF71920A098E35778CCDB1B.29114979",
    "userPaymentOptionId": "122922378",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Payout (Withdrawal) Flow

Follow these steps to perform a payout:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.

Example /createUser Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"<2-letter ISO country code>",
  "firstName":"John",
  "lastName":"Smith",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

The request registers the userTokenId (userId) in the Nuvei system, which is needed to generate a UPO in the next step.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request and include:

• userTokenId – The unique user identifier in your system.
• paymentMethodName: “apmgw_Local_payments_Africa“
• billingAddress class containing: countryCode and email

Example /addUPOAPM Request

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "paymentMethodName": "apmgw_Local_payments_Africa",
  "billingAddress": {
    "countryCode": "EG",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

Example /addUPOAPM Response

{
  "userPaymentOptionId":83458468,
  "internalRequestId":553078068,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221109154215"
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

User Experience

Payment with Fawry

1. The user selects the payment option they want to use from the available options, such as Card and Fawry, and others based on country and provider settings.
2. It generates a reference number for making the payment.
3. The custome uses this reference number to complete the payment with their Fawry app or at a Fawry outlet.

Payment with Card

1. The user is redirected to the card payment page, where they fill in the card details and press Pay.

Payment with QR Code

1. The user selects QR payment; this option is automatically available for all transactions in NGN.
2. The user scans the QR code using their bank’s mobile app and confirms the payment.
   
3. Once the payment is confirmed, the user is redirected to the merchant’s page.

Withdrawal

1. The user selects one of the three payout options available for their country.
   
2. The user enters the required information on the cashier according to the selected payout channels. All user details are prefilled if provided.
   1. Mobile money: First name, Last name, Email, Phone, Mobile provider (dropdown list)
   2. Bank Transfer: First name, Last name, City, Street, Email, Phone, Bank name (dropdown list), Account number.
   3. Barter: First name, Last name, Email, Phone
3. The user enters the withdrawal amount.
4. After the customer presses the withdrawal button, they receive a confirmation message that the payout has been successfully sent.

Testing

Access Bank

Account number: 0690000031
OTP: 12345

Access Bank 2

Account number: 0690000032
OTP: 12345

Access Bank 3

Account number: 0690000033
OTP: 12345

Access Bank 4

Account number: 0690000034
OTP: 12345

Test Mastercard PIN Authentication

Card number: 5531 8866 5214 2950
cvv: 564
Expiry: 09/32
Pin: 3310
OTP: 12345

Test Visa Card 3DS authentication (VBVSECURECODE)

Card number: 4187 4274 1556 4246
cvv: 828
Expiry: 09/32
Pin: 3310
OTP: 12345

Address Verification (AVS) Card

Card number: 4556052704172643
cvv: 899
Expiry: 09/32
Pin: 3310
OTP: 12345

Test Mastercard 3DS Authentication (VBVSECURECODE)

Card number: 5438 8980 1456 0229

cvv: 564

Expiry: 10/31

Pin: 3310

OTP: 12345

Test Mastercard PIN 2

Card number: 5399 8383 8383 8381

cvv: 470

Expiry: 10/31

Pin: 3310

OTP: 12345

Test VBVSECURECODE Card

Card number: 4751 7632 3669 9647

Expiry: 09/35

Test Visa Card 3DS Authentication

Card number: 4242 4242 4242 4242

cvv: 812

Expiry: 01/31

Pin: 3310

OTP: 12345

Test Verve Card (PIN)

Card number: 5061 4604 1012 0223 210

cvv: 780

Expiry Month: 12

Expiry Year: 31

Pin: 3310

OTP: 12345

Test Card Declined (Address Verification)

Card number: 5143 0105 2233 9965

cvv: 276

Expiry: 08/32

Pin: 3310

Test Card Fraudulent

Card number: 5590 1317 4329 4314

cvv: 887

Expiry: 11/32

Pin: 3310

OTP: 12345

Test Card Insufficient Funds

Card number: 5258 5859 2266 6506

cvv: 883

Expiry: 09/31

Pin: 3310

OTP: 12345

Pre-authorization Test Card

Card number: 5377 2836 4507 7450

cvv: 789

Expiry: 09/31

Pin: 3310

Test Card – Do Not Honour

Card number: 5143010522339965

cvv: 276

Expiry: 08/31

Pin: 3310

Test Card – Insufficient Funds

Card number: 5258585922666506

cvv: 883

Expiry: 09/31

Pin: 3310

OTP: 12345

Test Card – Invalid Transaction

Card number: 5551658157653822

cvv: 276

Expiry: 08/31

Test Card – Restricted Card, Retain Card

Card number: 5551651630381384

cvv: 276

Expiry: 08/31

Test Card – Function Not Permitted to Cardholder

Card number: 5258582054729020

cvv: 887

Expiry: 11/30

Test Card – Function Not Permitted to Terminal

Card number: 5258588264565682

cvv: 887

Expiry: 11/30

Test Card – Transaction Error

Card number: 5258589130149016

cvv: 887

Expiry: 11/30

Test Card – Incorrect PIN

Card number: 5399834697894723

cvv: 883

Expiry: 09/31

Pin: 3310

OTP: 12345

Test Verve Card – Card Enrollment

Card number: 5531882884804517

cvv: 564

Expiry: 10/32

Pin: 3310