Card Payment

info

The Card Payment APIs allows developers to integrate card payment functionality into their applications or systems.

1.0 AUTHORIZATION

Authorization to the APIs below requires an access token. To get more info on how to generate this access token, click on Generating Access Token

2.0 BASE URL

All requests to the Card API in the test environment must be done using the web API URL below.

Test Environment: https://api-devapps.vfdbank.systems/vtech-cards/api/v2/baas-cards

LIVE Environment: https://api-apps.vfdbank.systems/vtech-cards/api/v2/baas-cards

3.0 NOTIFICATIONS

For notifications, a webhook must be configured by you on the baas portal so you can be notified of successful card transactions. The webhook is to be shared both in the testing and production environments. Its HTTP method should be POST and the payload it would receive would be in the format below:

Sample Request

    { 
      "status":"00",
      "message":"Success",  
      "data":{
       "reference":"rosapay-01919",
       "paymentReference":"202405020958548EOVV",
       "amountCollected":"990",
       "amountCredited":"985"
      }
}

Field	Description
reference	This is the unique reference you passed when making the card payment.
paymentReference	This is generated by us and identifies the card transaction.
amountCollected	This is the amount collected by us.
amountCredited	This is the amount credited to your collections account.

note

When sharing a webhook with us, security measures like IP whitelisting is advised to be in place.

3.1 CARD PAYMENT

You have an option for card payments:

1. NON-TOKENIZED CARD PAYMENT: This payment option involves the payer filling all his card details.

3.2 HOW TO MAKE NON-TOKENIZED CARD PAYMENTS

1. The developer configures a webhook on the baas portal to receive successful card payments notification. The webhook request is described HERE.
2. The developer then calls the INITIATE NON-TOKENIZED PAYMENT endpoint. Depending on the response from this call there're two options:
   
   1. Response from calling the INITIATE NON-TOKENIZED PAYMENT endpoint contains a redirectHtml: In this case, the developer should redirect the customer to this redirectHtml. The customer then needs to follow the instructions on the page displayed to complete payment.
   2. Response from calling INITIATE NON-TOKENIZED PAYMENT endpoint does not contain a redirectHtml: In this case, the customer would receive an otp, the developer is meant to create an otp page where the customer can enter this otp. The developer then needs to call the VALIDATE OTP endpoint to validate the entered otp. If the otp is valid, the payment is completed.
3. The developer can then call the PAYMENT STATUS endpoint to check the payment status.

3.2 INITIATE NON-TOKENIZED PAYMENT

Description: This type of payment involves the payer filling all his card details.

API Context: /initiate/payment

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

Sample Request

    {
      "amount": "1000",
      "reference": "rosapay-01919",
      "useExistingCard": false,
      "cardNumber": "5060990580000217499",
      "cardPin": "1111",
      "cvv2": "111",
      "expiryDate": "0350",
      "narration": "Payment for electronics",
      "customerId": "test@gmail.com"
    }

Field	Description	Status
amount	Amount to debit in naira. Minimum is ₦1000	Mandatory
reference	Unique reference for the transaction should be prefixed with your wallet name e.g rosapay-01919	Mandatory
useExistingCard	Should always be false	Mandatory
cardNumber	Card Number	Mandatory
cardPin	Card pin	Mandatory
cvv2	Card CVV2	Mandatory
expiryDate	Card expiry date, should be in this format MMYY e.g 0350	Mandatory
narration	This describes what the payment is for	Optional
customerId	A unique identifier for the customer e.g the customer's email	Mandatory

Sample Response With Redirect Html:

{
    "success": true,
    "data": {
        "code": "03",
        "serviceResponseCodes": "COMPLETED",
        "paymentProcessor": "MASTERCARD",
        "redirectHtml": "https://auth.gateway.zestpayment.com/?data=RiN1Fs9Npyv9uUrKVvVG9yHZR+5gkSIAfDLyhW0op7eHqtbK8SHY9/ecCUuPEyT6gsyYJGhhR53f4GVSJroudhUKk5XVLC+hOVQ2hr+GI402tmvCfMuFxcYtYu2gXPI4",
        "narration": "Proceed to authenticate payer",
        "hasSavedCards": false
    },
    "message": "Proceed to authenticate payer"
}

Sample Response Without Redirect Html:

 {
    "success": true,
    "data": {
        "code": "01",
        "serviceResponseCodes": "COMPLETED",
        "narration": "Customer needs to authenticate with otp",
        "hasSavedCards": false
    },
    "message": "Customer needs to authenticate with otp"
}

3.3 TEST CARD DETAILS

info

You can use the test card details below in the dev environment:

Verve
Card number: 5060990580000217499
Expiry date: 0350
CVV: 111
Pin: 1111
Otp: 123456

Visa
Card number: 4000000000002503
Expiry date: 0350
CVV: 111
Pin: 1111
Otp: 1234

Mastercard
Card number: 5123450000000008
Expiry date: 0139
CVV: 100
Pin: 1234

note

The card expiry date should be passed in this format MMYY e.g 0139, where 01 is the expiry month and 39 is the expiry year on the card.

3.4 VALIDATE OTP

API Context: /validate-otp

Description: This endpoint is used to validate the otp received by the customer. If the entered otp is valid, the payment is completed.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{   
    "otp": "123456",
    "reference": "rosapay-01919"
}

Field	Description	Status
otp	Otp received by the customer	Mandatory
reference	Should be the same reference you passed when calling the INITIATE NON-TOKENIZED PAYMENT endpoint	Mandatory

note

For the Verve test card above, you can use 123456 as the otp

SAMPLE RESPONSE:

{
    "status": "00",
    "message": "Success",
    "data": {
        "reference": "rosapay-01919"
    }
}

5.0 PAYMENT STATUS

API Context : /payment-details?reference={reference}

Description: This is used to confirm a payment status.

QUERY PARAMS

Field	Description	Status
reference	Unique reference you passed when making card payment	Mandatory

SAMPLE RESPONSE

   {
       "status": "00",
       "message": "Successful Transaction Retrieval",
       "data": {
           "transactionStatus": "00",
           "transactionMessage": "SUCCESS",
           "amount": "1000.00",
           "reference": "AdminTest-0995999980",
           "transactionDescription": "Request successfully treated"
       }
   }