Card Payments (Local and International)

Collect payment through local (naira) cards.

API Reference

Initaite Card Payment

Path: /api/v1/card-payments
Method: POST
Response Body:
- Object will be returned with transaction status and possibly with instructions on what next to do (e.g. PIN or OTP maybe required. Also redirect URL to complete 3DS transaction)

Request Body Table

Field	Type	Required	Description
cardData	string	Yes	Encrypted Card data. Data will be encrypted in this format cardNo\|cvv\|expiryMonth\|expiryYear (4562543755474674\|123\|09\|30) using a public key that will be shared with the developer.
amount	number	Yes	Amount for the transaction
reference	string	Yes	Unique reference for the transaction
narration	string	No	Transaction narration
notificationUrl	string	No	Notification URL. Notification will be sent to the URL configured on the portal if not set
redirectUrl	string	No	Web page to redirect customer after completing transaction (for 3DS transaction)
businessId	string	Yes	Your business identifier
customer	object	Yes	Customer information
customer.name	string	Yes	Customer's full name
customer.email	string	Yes	Customer's email address
customer.phone	string	Yes	Customer's phone number
customer.address	object	Yes	Customer's address information
customer.address.line1	string	Yes	Address line 1
customer.address.line2	string	No	Address line 2
customer.address.city	string	No	City
customer.address.state	string	Yes	State
customer.address.postalCode	string	No	Postal code
customer.address.countryCode	string	Yes	Alpha-2 country code
currency	string	Yes	Currency
countryCode	string	Yes	Alpha-2 country code
requestCardAuthType	string	No	Card Request Type (THREE_DS, TWO_DS). Default is THREE_DS.

Sample Request (Local Card)

{
  "cardData": "D50S1yZKIeqiItKk751HfOQX3rlJWiCfPqPTiEphWVODQLxndDYbLXvr7l+0ZWdSz+8+SpAAhm20i3xdDLu1ig==",
  "customer": {
    "name": "John Doe",
    "email": "test-card@test.com",
    "address": {
      "postalCode": "112321",
      "countryCode": "NG",
      "city": "Lagos"
    },
    "phone": "+32322332323"
  },
  "amount": "750",
  "currency": "NGN",
  "businessId": "2131247a-6374-426e-a52e-fed7b0c7457e",
  "reference": "merchant-reference",
  "narration": "test",
  "notificationUrl": "https://webhook.site/ebdc5e7c-8b2a-4046-b4ef-23a55dd20cd5",
  "redirectUrl": "https://payonus.com"
}

Sample Request (Global Processing)

{
  "cardData": "D50S1yZKIeqiItKk751HfOQX3rlJWiCfPqPTiEphWVODQLxndDYbLXvr7l+0ZWdSz+8+SpAAhm20i3xdDLu1ig==",
  "customer": {
    "name": "John Doe",
    "email": "test-card@test.com",
    "address": {
      "postalCode": "112321",
      "countryCode": "NG",
      "city": "Lagos"
    },
    "phone": "+32322332323"
  },
  "amount": "750",
  "currency": "USD",
  "countryCode": "US",
  "businessId": "2131247a-6374-426e-a52e-fed7b0c7457e",
  "reference": "merchant-reference",
  "narration": "test",
  "notificationUrl": "https://webhook.site/ebdc5e7c-8b2a-4046-b4ef-23a55dd20cd5",
  "redirectUrl": "https://payonus.com"
}

Example Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "authTypeRequired": null,
    "paymentStatus": "FAILED",
    "onusReference": "ONUS-CARD-0767325242423-02082025-222812",
    "redirectUrl": null,
    "message": "Incorrect card PIN"
  }
}

{
  "status": 200,
  "message": "Success",
  "data": {
    "authTypeRequired": null,
    "paymentStatus": "SUCCESSFUL",
    "onusReference": "ONUS-CARD-2570434237835-03082025-103058",
    "redirectUrl": null,
    "message": "Card charged successfully"
  }
}

If further authorization is required, the authTypeRequired field will not be null. The possible values are:

OTP: This means an OTP has been sent to the customer and the customer needs to input the OTP and you will use the OTP to complete the transaction by calling the card completion endpoint.
PIN: This means customer needs to input their card PIN and you will use the PIN to complete the transaction by calling the card completion endpoint.
THREE_DS: This means payment requires 3DS authentication. The redirectUrl in the response body will not be null. You need to redirect the customer to this URL for them to complete the transaction. You will be notified via webhook on completion of the transaction.

Sample response when OTP is required

{
  "status": 200,
  "message": "Success",
  "data": {
    "authTypeRequired": "OTP",
    "paymentStatus": "PROCESSING",
    "onusReference": "ONUS-CARD-2570434237835-03082025-103058",
    "redirectUrl": null,
    "message": "Kindly enter the One-time PIN (OTP) sent to your phone number"
  }
}

Sample response when PIN is required

{
  "status": 200,
  "message": "Success",
  "data": {
    "authTypeRequired": "PIN",
    "paymentStatus": "PROCESSING",
    "onusReference": "ONUS-CARD-2570434237835-03082025-103058",
    "redirectUrl": null,
    "message": "Card PIN required"
  }
}

Sample when 3DS authorization is required

{
  "status": 200,
  "message": "Success",
  "data": {
    "authTypeRequired": "THREE_DS",
    "paymentStatus": "PROCESSING",
    "onusReference": "ONUS-CARD-1868414226924-03082025-104202",
    "redirectUrl": "https://test-checkout.com/charge-card/threeds-test/F60immE95K1MIwK",
    "message": "You would be redirected to a secure page to complete your authorization"
  }
}

Complete Card Payment

Path: /api/v1/card-payments/complete-payment
Method: POST
Response Body:
- Object will be returned with transaction status and possibly with instructions on what next to do (e.g. OTP maybe required. Also redirect URL to complete 3DS transaction)

Request Body Table

Field	Type	Required	Description
cardAuthType	string	Yes	This is the authen tication type required. e.g. OTP or PIN
authValue	string	Yes	The Otp received or card Pin
onusReference	string	Yes	The `onusReference` returned during initiation
businessId	string	Yes	Your business identifier. Must be same with the businessId passed during initiation

The response will follow the same format as the format explained above with further instructiions when necessary.

Card Data Encryption

Cardholder data (card number, CVV, expiry date, and optional PIN) is concatenated into a single string and then encrypted using RSA public key encryption:

If there's no PIN, the card data should be in this format: cardNo|cvv|expiryMonth|expiryYear
If there's a PIN, the card data should be in this format: cardNo|cvv|expiryMonth|expiryYear|pin

Encryption Method: Asymmetric cryptography (RSA).
- A public key is used to encrypt the data.
- Only the corresponding private key can decrypt it.
Encoding: The encrypted binary output is Base64-encoded for safe transmission and storage.

Public Keys

Summary:
The system secures sensitive cardholder information using RSA public key encryption. Data is encrypted with a public key and can only be decrypted with the matching private key. The encrypted output is Base64-encoded.

Test Cards (NGN)

You can use any of the following test cards in sandbox for your integration:

Please contact Support to enable International Card Testing for your business profile.

For Successful Payment (No Authentication) - Visa

Card Number: 4084127883172787
Expiry Date: 09/30
CVV: 123

For Successful Payment (with PIN) - Mastercard

Card Number: 5188513618552975
Expiry Date: 09/30
CVV: 123
PIN: 1234

For Successful Payment (with OTP) - Mastercard

Card Number: 5442056106072595
Expiry Date: 09/30
CVV: 123
PIN: 1234
OTP: 123456

For Successful Payment (with 3D Secure) - Visa

Card Number: 4562543755474674
Expiry Date: 09/30
CVV: 123
OTP: 1234

Successful (with Card Enroll) - Verve

Card Number: 5061460410120223210
Expiry Date: 09/30
CVV: 123
PIN: 1234
OTP: 123456

For Failed Payment (Insufficient Funds) - Verve

Card Number: 506066506066506067
Expiry Date: 09/30
CVV: 408

Test Cards (Global Cards - USD/US)

You can use any of the following test cards in sandbox for your integration:

For Successful Payment - MasterCard

Card Number: 5123450000000008
Expiry Date: 01/39
CVV: 100

For Failed Payment - MasterCard

Card Number: 5123450000000008
Expiry Date: 05/39
CVV: 100

For Successful Payment - Visa

Card Number: 4508750015741019
Expiry Date: 01/39
CVV: 100

For Failed Payment - Visa

Card Number: 4508750015741019
Expiry Date: 05/39
CVV: 100

Verification: - You can verify the status of a specific card payment using the Verify Single Payment endpoint with the onusReference returned during initiation or completion.