PayU Nigeria

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications in this section to integrate with PayU Nigeria.

API Version

Minimum required API version: 1.1.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 MethodPayment Method TypeOnly for Requests
EFT BANK TRANSFERBank TransferCharge
MASTERCARDCards
VerveCardsCharge
VISACards

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 MethodAPI ValueOnly for Requests
EFT BANK TRANSFEREFT_BANK_TRANSFERCharge
Instant Account TransferPAY_BY_REFCharge
MASTERCARDCREDITCARDCharge
Pay by USSDUSSDCharge
Scan to PaySCAN_TO_PAYCharge
VerveCREDITCARDCharge
VISACREDITCARDCharge

Currencies

NGN, USD

Features

The following table provides an overview of all supported and non-supported features.

FeatureSupported
3DS 2.0 ExternalNo
3DS 2.0 PaymentsOS-handledNo
3DS 2.0 Provider-handledYes
3DS 2.0 Self-handledNo
InstallmentsNo
Level 2 and 3 DataNo
Multi-seller PaymentsNo
Network TokensNo
Payment FacilitatorNo
PayU RiskNo
Pre-authorizationNo
Retrieve Supported Payment MethodsNo
Retrieve Supported PlansNo
Statement Soft DescriptorNo
Stored Credentials FlagNo
Transaction Processing without CVVYes

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.

Supported requests for card transactions.
RequestPartial/MultipleModeNotes
AuthorizePartial and multiple are not supportedAsynchronous or Synchronous
  • The request can be synchronous or asynchronous, depending on whether you implemented a 3DS flow.
  • Authorize is only supported for the local currency, USD is not supported.
Capture Partial is supportedSynchronous
Charge Not ApplicableAsynchronous or SynchronousThe request can be synchronous or asynchronous, depending on whether you implemented a 3DS flow.
Refund Both partial and multiple are supportedSynchronous
Void Not ApplicableSynchronous

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

ConfigurationRequired/Optional
In the PaymentsOS Control Center, configure the following credentials:
  • Username: Web service username provided by PayU Nigeria.
  • Password: Web service password provided by PayU Nigeria.
  • Safekey: PayU Merchant Identifier provided by PayU Nigeria.
To obtain test credentials, click here. To obtain live credentials, login to the merchant portal.
Required
In your PayU Nigeria 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 Nigeria support for assistance.Required
In your PayU Nigeria account, disable the cvv check if you do not require customers to enter their cvv code when initiating a payment. Contact PayU Nigeria support for assistance.Optional
In your PayU Nigeria 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 Nigeria support for assistance.Optional
If you want to use our End-to-End Encryption Service, configure the public key generated with PayU Nigeria in the PublicJWK field in your PaymentsOS account. Optional

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Enabling 3DS

If you require 3DS, contact PayU Nigeria support to configure the following IPN URLs in your PayU Nigeria environment:

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 Nigeria 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.

Copy
"provider_specific_data": {
    "magellan": {
      "additional_details": {
        "is3ds": "true"
      }
    }
  }

Regardless of whether 3DS is set to required or optional, PayU Nigeria 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:

Copy
{
  "additional_details": {
    "error": "The transaction requires 3DS authentication, but cannot be completed as the merchant_site_url was not provided"
  }
  ...
}

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.

Copy
"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:

Copy
{
  "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.

Implementing Verve in a Checkout Page

Verve is a pan-African chip + PIN payment card that offers issuers, cardholders and organizations comprehensive payment card products and solutions in Nigeria. If desired, you can allow customers to pay using Verve by offering them Verve as a payment method directly in your own checkout page.

Passing the Card’s PIN Number

When customers use Verve as their payment method, you will need to prompt them for their card’s pin number (just make sure to first verify that they are using a ‘Verve card’) and then pass the number in the payment_method.pin field of the Create Charge request.

Copy
{
  "payment_method": {
    "credit_card_cvv": "123",
    "pin": "1234", // pass the pin number here
    "token": "f78cbf5b-0e23-44e0-be11-2081791d9501",
    "type": "tokenized"
  },
  ...
}  

Passing the Mobile Phone Number

If the card is not yet enrolled in Verve, the response of the Create Charge request will return a provider_data.additional_information.transaction_status field with a value of mobile_number_pending, as well as a provider_data.additional_information.callback_url field with the URL to which to pass the user’s phone number:

Copy
{
"provider_data.additional_information": {
    "transaction_status": "mobile_number_pending",
    "callback_url": "https://api.paymentsos.com/payments/2a24dc43-5185-428d-8d89-bc5cb4348872/charges/8bd0f312-e5c5-4247-bc86-306c4b4f263b/callbacks",
    "vendor": "verve"
  }
}        

Now POST the mobile number to the callback URL. Include the phone number in the request body, like so:

Copy
{
    "vendor": "verve",
    "type": "enrollment",
    "mobile_number": "1234567890"
}

After you send the phone number, your customer will receive a One-time Password (OTP) on their phone. You must then pass the OTP, as explained in Passing a One-time Password below.

Passing a One-time Password

When choosing to pay with Verve, customers may receive a One-time Password (OTP) in order to authorize the transaction.

If a customer needs to pass an OTP, they will receive the OTP on their mobile phone after you invoke the Create Charge request (the code is sent to the phone number they provided when enrolling their card in Verve). The response of the Create Charge request will then include a provider_data.additional_information.transaction_status field with a value of otp_pending, indicating that an OTP is required. The response will also include a provider_data.additional_information.callback_url field, with the URL to which you must send the OTP that the customer received.

Here’s a sample response:

Copy
{
"provider_data.additional_information": {
    "transaction_status": "otp_pending",
    "callback_url": "https://api.paymentsos.com/payments/2a24dc43-5185-428d-8d89-bc5cb4348872/charges/8bd0f312-e5c5-4247-bc86-306c4b4f263b/callbacks",
    "vendor": "verve"
  }
}    

Now POST the OTP to the callback URL, like so:

Copy
{
    "vendor": "verve",
    "type": "otp",
    "otp": "1234" // Minimum length is 4 digits; maximum length is 6 digits.
}

Routing Verve Transactions to PayU Nigeria

Transactions using the Verve payment method must be processed by PayU South Nigeria. To ensure your transactions using Verve are indeed routed to PayU South Nigeria, pass an additional_details object in the Create Charge request with a key-value pair that indicates that the transaction was done with a Verve card. In the example below, we pass a key of verve_card with a value of true:

Copy
{
  "payment_method": {
    ...
  },
  ...
  "additional_details": {
      "verve_card": "true"
  }
}

You can then configure a route rule based on the custom information you passed. For more information, see Creating Policy Rules based on Custom Data.

Testing

You can use the test cards from the PayU Nigeria Test Credentials site.

Testing with Verve

To test with Verve, use any of the following card numbers:

  • 5061030000000000084

  • 6280511000000095

  • 5061030000000000027

  • 5061030000000000035

  • 5061040000000000231

For the expiry date, cvv and pin number pass the following:

  • Expiry date: any date in future

  • cvv: any 3 digit number

  • pin: any 4 digit number

Last modified March 2, 2023