Debit Cards

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 Wallet 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/baascards

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

3.0 HOW TO USE THE DEBIT CARD CREATE API

3.1 VIRTUAL DEBIT CARD

1. The developer calls the CREATE VIRTUAL CARD to initiate the card request.
2. The developer should then call the ACTIVATE DEBIT CARD API to initiate the card activation process.
3. The developer then calls the PIN CHANGE API to change the default pin returned in STEP 2. This completes the activation process.

4.0 DEBIT CARD LIFECYCLE

4.1 CREATE DEBIT CARD

This is the initial step in the process, where users can generate a new debit card linked to their sub-account. Follow the outlined steps to successfully create and activate your debit card.

4.1.1 CREATE VIRTUAL CARD

API Context: /cardrequest?action=virtual

Description: This endpoint is used to initiate a virtual card request.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

Query Parameters	Description	Required
action	This specifies the card creation type	Mandatory

SAMPLE REQUEST

{
    "accountNo": "1001555798",
    "primaryPhoneNo": "09023449092",
    "emailAddress": "afunbioluwa@gmail.com"
}

Field	Description	Status
accountNo	This is a sub account of the merchant	Mandatory
primaryPhoneNo	This is the creator's phone number	Mandatory
emailAddress	This is the creator's email address	Mandatory

SAMPLE SUCCESSFUL RESPONSE

{
    "status": "00",
    "message": "Successful",
    "data": {
        "maskedPan": "506124******6131",
        "track2": "5061240021356131=2612601001641398",
        "cvv": "123",
        "pinOffset": "1407",
        "expiryDate": "1204",
        "pan":"5061249421446131",
        "cardId":"11703"
    }
}

4.2 ACTIVATE DEBIT CARD

API Context: /cardaction/request

Description: This endpoint is used to initiate the card activation process.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{
    "action": "ACTIVATE",
    "accountNo": "1001555798",
    "cardId": "11703"
}

Field	Description	Status
action	This is the action to be carried out on the card	Mandatory
accountNo	The account number used to create the card	Mandatory
cardId	This is the id of the card created and it is returned upon card creation	Mandatory

SAMPLE RESPONSE

{
    "status": "00",
    "message": "Successful",
    "data": {
      "pin": "1234"
    }
} 

4.3 PIN CHANGE

API Context: /cardaction/request

Description: This endpoint is used to change card default pin.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{
    "action":"PIN-CHANGE",
    "cardId":"11703",
    "accountNo":"1001555798",
    "newCardPin":"1366",
    "cardPin":"1234"
}

Field	Description	Status
accountNo	The account number used to create the card	Mandatory
action	This is the action to be carried out on the card	Mandatory
cardId	This is the id of the card created and it is returned upon creation	Mandatory
newCardPin	The new pin to be used	Mandatory
cardPin	The default pin receive upon activation	Mandatory

SAMPLE RESPONSE

{
    "status": "00",
    "message": "Pin successfully changed"
}

4.4 BLOCK DEBIT CARD

API Context: /cardaction/request

Description: This endpoint is used to block a card.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{
    "action":"BLOCK",
    "cardId":"11703",
    "accountNo":"1001555798"
}

Field	Description	Status
action	This is the action to be carried out on the card	Mandatory
accountNo	The account number used to create the card	Mandatory
cardId	This is the id of the card created and it is returned upon creation	Mandatory

SAMPLE RESPONSE

{
    "status": "00",
    "message": "Successful"
}

4.5 UNBLOCK DEBIT CARD

API Context: /cardaction/request

Description: This endpoint is used to unblock a blocked card.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{
    "action":"UNBLOCK",
    "cardId":"11703",
    "accountNo":"1001555798"
}

Field	Description	Status
action	This is the action to be carried out on the card	Mandatory
accountNo	The account number used to create the card	Mandatory
cardId	This is the id of the card created and it is returned upon creation	Mandatory

SAMPLE SUCCESSFUL RESPONSE

{
    "status": "00",
    "message": "Successful"
}

SAMPLE FAILED RESPONSE

{
    "status": "01",
    "message": "Invalid Account Number and Card Id Combination"
} 

5.0 CARD TRANSACTIONS

5.1 TRANSACTION HISTORY

API Context: /account/transactions?accountNumber={accountNumber}&startDate={startDate}&endDate={endDate}&page=0&size=20

Description: This endpoint is designed to retrieve all card transactions associated with the specified merchant's sub-account number.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

QUERY PARAMS

Field	Description	Status
accountNumber	Customer's account number	Mandatory
startDate	start date e.g 2025-04-15	Mandatory
endDate	start date e.g 2025-04-17	Mandatory
page	Page number, starts from 0	Optional
size	Page size	Optional

SAMPLE RESPONSE

{
    "status": "00",
        "message": "Successful",
        "data": {
        "content": [
            {
                "transactionStatus": "success",
                "transactionType": "cashWithdrawal",
                "amount": "23.00",
                "sourceAccountno": "1001626656",
                "transmissionDate": "2025-03-14 10:20:18.0",
                "transactionFee": "0.00",
                "beneficiaryAccountno": null,
                "retrievalReferenceNumber": "847571200968",
                "card_acceptorTerminalid": "3IPG0001"
            },
            {
                "transactionStatus": "success",
                "transactionType": "debitGoodsAndServices",
                "amount": "21.00",
                "sourceAccountno": "1001626656",
                "transmissionDate": "2025-03-14 10:20:18.0",
                "transactionFee": "0.00",
                "beneficiaryAccountno": null,
                "retrievalReferenceNumber": "847571200967",
                "card_acceptorTerminalid": "3IPG0001"
            }
        ],
            "totalElements": 10,
            "totalPages": 2
    }
}

6.0 DEBIT CARD WEBHOOK SETUP

6.1 DEBIT TRANSACTION NOTIFICATION

This refers to a webhook notification you receive when funds are debited from the account.

Its http method should be POST and the payload it would receive would be in the format below:

{
  "availableBalance": "15004.00",
  "ledgerBalance": "15004.00",
  "accountNumber": "1001626656",
  "retrievalReferenceNumber": "847571200976",
  "cardAcceptorTerminalId": "3IPG0001",
  "transactionStatus": "withdrawal_performed",
  "amount": "210.0",
  "charge": "10.0"
}

Field	Description
availableBalance	For pool transactions, this reflects the account balance returned by the merchant, while for 1-1 transactions, it reflects the balance of the sub-account.
ledgerBalance	For pool transactions, this reflects the account balance returned by the merchant, while for 1-1 transactions, it reflects the balance of the sub-account.
accountNumber	This is the account number on the card used for the transaction.
retrievalReferenceNumber	This is the transaction reference.
cardAcceptorTerminalId	This is the channel ID through which the transaction was carried out.
transactionStatus	This is the status of the transaction.
amount	This is the initiator's amount.
charge	This is the transaction fee.

6.2 DEBIT AUTHORIZATION WEBHOOK

This webhook is required to validate the debit request initiated on the merchant's sub-account. It is specifically needed for merchants on POOL implementation.

Its http method should be POST and the payload it would receive would be in the format below:

{
  "accountNo":"1001626656", 
  "amount":"200"
}

Field	Description
accountNo	This is the account number of the card that was used to initiate the request.
amount	This is the request amount to be debited.

{
  "accountNo":"1001626656"
}

Field	Description
accountNo	This is the account number of the card that was used to initiate the request.

EXPECTED RESPONSE

{
  "status": "00",
  "message": "Successful",
  "data": {
    "accountBalance": "125000.50"
  }
}

Field	Description
accountBalance	This is account balance of the sub-account.

6.3 BALANCE CHECK WEBHOOK

This webhook is used to retrieve the current balance of a merchant's sub-account. It is specifically needed for merchants on POOL implementation.

Its http method should be POST and the payload it would receive would be in the format below:

{
  "accountNo":"1001626656"
}

Field	Description
accountNo	This is the account number of the card that was used to initiate the request.

EXPECTED RESPONSE

{
  "status": "00",
  "message": "Successful",
  "data": {
    "accountBalance": "125000.50"
  }
}

Field	Description
accountBalance	This is account balance of the sub-account.

note

When sharing a webhook with us, security measures such as Authentication or IP whitelisting are advised to be in place.

Also, your webhook url should respond with a 200 status code once notified successfully