2. Home
  4. Virtual Card Management
  6. Virtual Card Management

Virtual Card Management


Create Virtual Prepaid Card Endpoint

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/create

Request Type is application/json

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
2pinNumeric4YesThis is a default pin configured on the client end for card creation.
3firstNameString100No
4lastNameString100No
5nameOnCardString100No
6mobileNrString25Yes
7emailAddressString50Yes
8streetAddressString255No
9streetAddressLine2String255No
10cityString255Yes
11stateString50No
12postalCodeString50No
13countryCodeString3Yes
14cardIdentifierString100YesThis is a name to identify each card attached to the same account

Plain Sample Request

{
      “pin”:”1234″,
      “firstName”:”Edson”,
      “lastName”:”Rock”,
      “nameOnCard”:”Adewoye Adeyelr”,
      “mobileNr”:”2348055186175″,
      “emailAddress”:”adewoyeadeyel@eexptest.com“,
      “streetAddress”:”12 vvv Road”,
      “streetAddressLine2″:”Off Adden Boulevard”,
      “city”:”Lagos”,
      “state”:”Lagos”,
      “postalCode”:”23401″,
      “countryCode”:”NGN”,
     “cardIdentifier” : “my-card”
}

Encrypted Sample Request

{
   “data”:”T4DZPBE42uzXl61X+3D47lTyB1uXkvgTY/Q2ATx5/A2Qm/8fAlkbJbMtmpGciOCIOimf44BRnntAsX7mn5UwFd6yE+fnVQvWLti+MYKud6ywK5fckw8b0ZrzR5+nvNLEaTA9jFptCBq0nNN1tCk7QzcgajBbad1/pbC8QUf7oYZ1rVqQ/Kghyi0aC5tIyL2h3ul/jiPyjEmb18I0xTSz3w==”
}

Response Message description

Field#Field nameData typeMax lengthRequiredDescription
1responseCodeString


2responseMessageString


3panString


4cvvString


5cvv2String


6pinInfoString


7pinOffsetString


8track2String


9seqNrnumeric


Sample Success Response

{
      “responseCode”:”00″,
      “responseMessage”:”Successful”,
      “data”:{​​​​​​​​
            “pan”:”5063210000000005255″,
            “seqNr”:”001″,
            “defaultAccountType”:”20″,
            “expiryDate”:”2407″,
            “pinOffset”:”7928″,
            “cvv”:”829″,
            “cvv2″:”801”,
            “pinInfo”:”AC47A9D62D435C76″,
            “track2″:”5063210000000005255=2407101007928829”,
            “customerId”:”PC5063215255-001″
       }​​​​​​​​

}

Sample Failed Response

{
      “responseCode”: “W104”,
      “responseMessage”: “A card already exists for this customer on this domain”,
      “errors”: []
}

Create Virtual Debit Card Endpoint

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/create/debit

Request Type is application/json

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
1accountTypeNumeric2YesTwo digit representation of the Account Type.20 – Current Account10 – Savings Account
2accountIdNumeric10Yes
3pinNumeric4YesThis is a default pin configured on the client end for card creation.
4firstNameString100No
5lastNameString100No
6nameOnCardString100No
7mobileNrString25Yes
8emailAddressString50Yes
9streetAddressString255No
10streetAddressLine2String255No
11cityString255Yes
12stateString50No
13postalCodeString50No
14countryCodeString3Yes
15cardIdentifierString100YesThis is a name to identify each card attached to the same account

Plain Sample Request

{

      “accountType”:”20″,

      “accountId”:”1234567890″,
      “pin”:”1234″,
      “firstName”:”Edson”,
      “lastName”:”Rock”,
      “nameOnCard”:”Adewoye Adeyelr”,
      “mobileNr”:”2348055186175″,
      “emailAddress”:”adewoyeadeyel@eexptest.com“,
      “streetAddress”:”12 vvv Road”,
      “streetAddressLine2″:”Off Adden Boulevard”,
      “city”:”Lagos”,
      “state”:”Lagos”,
      “postalCode”:”23401″,
      “countryCode”:”NGN”,
      “cardIdentifier” : “my-card”
}

Encrypted Sample Request

{
   “data”:”T4DZPBE42uzXl61X+3D47lTyB1uXkvgTY/Q2ATx5/A2Qm/8fAlkbJbMtmpGciOCIOimf44BRnntAsX7mn5UwFd6yE+fnVQvWLti+MYKud6ywK5fckw8b0ZrzR5+nvNLEaTA9jFptCBq0nNN1tCk7QzcgajBbad1/pbC8QUf7oYZ1rVqQ/Kghyi0aC5tIyL2h3ul/jiPyjEmb18I0xTSz3w==”
}

Response Message description

Field#Field nameData typeMax lengthRequiredDescription
1responseCodeString


2responseMessageString


3panString


4cvvString


5cvv2String


6pinInfoString


7pinOffsetString


8track2String


9seqNrnumeric


Sample Success Response

{
      “responseCode”:”00″,
      “responseMessage”:”Successful”,
      “data”:{​​​​​​​​
            “pan”:”5063210000000005255″,
            “seqNr”:”001″,
            “defaultAccountType”:”20″,
            “expiryDate”:”2407″,
            “pinOffset”:”7928″,
            “cvv”:”829″,
            “cvv2″:”801”,
            “pinInfo”:”AC47A9D62D435C76″,
            “track2″:”5063210000000005255=2407101007928829”,
            “customerId”:”PC5063215255-001″
       }​​​​​​​​

}

Sample Failed Response

{
      “responseCode”: “W104”,
      “responseMessage”: “A card already exists for this customer on this domain”,
      “errors”: []
}

Block Virtual Card Endpoint

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/block

Request Type is application/json

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
1mobileNumberString25Yes
2pinNumeric4Yes
3cardIdentifierString100YesThis is a name to identify each card attached to the same account

Plain Sample Request

{
       “pin”:”1234″,
       “mobileNumber”:”2348055186175″,
       “cardIdentifier” : “my-card”
}

Encrypted Sample Request

{
   “data”:”T4DZPBE42uzXl61X+3D47lTyB1uXkvgTY/Q2ATx5/A2Qm/8fAlkbJbMtmpGciO”
}

Sample Success Response

{
      “responseCode”: “00”,
      “responseMessage”: “Successful”,
      “data”: {
            “maskedPan”: “506321*********5396”
      }
}

Sample Failed Response

{
      “responseCode”: “W102”,
      “responseMessage”: “Failed to complete request”,
      “errors”: [
            {
                  “fieldName”: null,
                  “code”: “E39”,
                  “message”: “No Card acceptor ID has been defined for this client.”
             }
       ]
}

Unblock Virtual Card Endpoint

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/unblock

Request Type is application/json

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
1mobileNumberString25Yes
2pinNumeric4Yes
3cardIdentifierString100YesThis is a name to identify each card attached to the same account

Plain Sample Request

{
       “pin”:”1234″,
       “mobileNumber”:”2348055186175″,
        “cardIdentifier” : “my-card”
}

Encrypted Sample Request

{
   “data”:”T4DZPBE42uzXl61X+3D47lTyB1uXkvgTY/Q2ATx5/A2Qm/8fAlkbJbMtmpGciOCIO”
}

Sample Success Response

{
      “responseCode”: “00”,
      “responseMessage”: “Successful”,
      “data”: {
            “maskedPan”: “506321*********5396”
      }
}

Sample Failed Response

{
      “responseCode”: “W102”,
      “responseMessage”: “Failed to complete request”,
      “errors”: [
            {
                  “fieldName”: null,
                  “code”: “E39”,
                  “message”: “No Card acceptor ID has been defined for this client.”
             }
       ]
}

Change Card Pin Endpoint – This endpoint must be called after successful card creation to activate the card.

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/change-pin

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
1mobileNumberString25Yes
2oldPinNumeric4YesThis is a default pin configured on the client end that was used to create the card. After the successful activation, subsequent call to this endpoint, the user old pin will then be passed.
3newPinNumeric4YesThis is the user’s preferred pin. 
4cardIdentifierString100YesThis is a name to identify each card attached to the same account

Plain Sample Request

{
      “newPin”:”1234″,
      “oldPin”:”1234″,
      “mobileNumber”:”2348055186175″,
      “cardIdentifier” : “my-card”
}

Encrypted Sample Request

{
   “data”:”T4DZPBE42uzXl61X+3D47lTyB1uXkvgTY/Q2ATx5/A2Qm/8fAlkbJbzcgajBbad1/pbC8QUf7oYZ1rVqQ/Kghyi0aC5tIyL2h3ul/jiPyjEmb18I0xTSz3w==”
}

Sample Success Response

{
      “responseCode”: “00”,
      “responseMessage”: “Successful”,
      “data”: {
            “maskedPan”: “506321*********5396”
      }
}

Sample Failed Response

{
      “responseCode”: “W102”,
      “responseMessage”: “Failed to complete request”,
      “errors”: [
            {
                  “fieldName”: null,
                  “code”: “E39”,
                  “message”: “No Card acceptor ID has been defined for this client.”
             }
       ]
}

Get Card balance  Endpoint

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/card-balance

Request Type is application/json

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
1mobileNumberString25Yes
2cardIdentifierString100YesThis is a name to identify each card attached to the same account

Sample Request

{
    “mobileNumber” : “2348065186175”,
     “cardIdentifier” : “my-card”
}

Sample Success Response

{
      “responseCode”: “00”,
      “responseMessage”: “Successful”,

      “data”:{

            “ledgerBalance”:”00″,

            “availableBalance”:”0.00″,

            “cashLimit”:”0.00″,

            “cashNrTransLimit”:”0.00″,

            “paymentLimit”:”0.00″,

            “paymentNrTransLimit”:”0.00″,

            “depositCreditLimit”:”0.00″

      }

}

Sample Failed Response

{
    “responseCode”: “W102”,
    “responseMessage”: “Failed to complete request”,
    “errors”: [
        {
            “fieldName”: null,
            “code”: “10400”,
            “message”: “Bad request Error 1: pan-> not a valid card number”
        }
    ]
}

Get Account Statement Endpoint

POST {scheme}://{host}:{port}/virtual-card/api/v1/cards/account-statement

Request Type is application/json

Authorization: {passport generated bearer token}

Request Message description

Field#Field nameData typeMax lengthRequiredDescription
1fromDateString
Yes
2toDateString
Yes
3transCountInteger
Yes
4referenceInteger
Yes
5forwardInteger
Yes
6orderingInteger
Yes
7mobileNumberString
Yes
8cardIdentifierString100YesThis is a name to identify each card attached to the same account

Sample Request

{
    “fromDate” : “03/05/2018”,
    “toDate” : “03/05/2018”,
    “transCount” : 10,
    “reference” : 1,
    “forward” : 1,
    “ordering” : 1,
    “mobileNumber” : “2348065186175”,
     “cardIdentifier” : “my-card”
}

Sample Success Response

{
  “responseCode”: “00”,
  “responseMessage”: “Successful”,
  “data”: {
    “statementRecords”: [
      {
        “tranType”: “50”,
        “tranAmount”: “-23250”,
        “tranLocalDatetime”: “1406497152000”,
        “tranPostedDatetime”: “1406497152230”,
        “cardAcceptorNameLocation”: “QTBPWCGMO/ayo/999923430 LANG”
      },
      {
        “tranType”: “50”,
        “tranAmount”: “-20000”,
        “tranLocalDatetime”: “1406497152005”,
        “tranPostedDatetime”: “1406497152210”,
        “cardAcceptorNameLocation”: “QTBPWCGMO/ayo/999923430 LANG”
      }
    ]
  }
}

Sample Failed Response

{
    “responseCode”: “W102”,
    “responseMessage”: “Failed to complete request”,
    “errors”: [
        {
            “fieldName”: null,
            “code”: “10400”,
            “message”: “Bad request Error 1: pan-> not a valid card number”
        }
    ]
}

Get Customer Details Endpoint

GET {scheme}://{host}:{port}/virtual-card/api/v1/cards/customer-details

Request Type is application/json

Authorization: {passport generated bearer token}

Header Message description

Field#Field nameData typeMax lengthRequiredDescription
1mobileNumberString
Yes

Sample Response

{
      “responseCode”: “00”,
      “responseMessage”: “Successful”,
      “data”: {
            “customer”:{

                “id”: 1,
                 “createdAt”: “2021-07-22 13:59:19”,
                 “updatedAt”: null,
                 “firstName”:”John”,
                 “lastName”:”Doe”,
                 “nameOnCard”:”John Doe”,
                 “mobileNumber”:”234807564996655″,
                 “gender”:”Male”,
                 “email”:”john.doe@interswitchgroup.com”,
                 “streetAddress”:”7 Ako Awo Street”,
                 “streetAddressLine2″:”7 Ako Awo Street”

            },

            “domain”:{

                 “id”: 1,
                 “createdAt”: “2021-07-22 13:59:19”,
                 “updatedAt”: null,
                 “domainCode”:”FBN”,
                 “clientId”:”virtual-card”,
                 “domainName”:”First bank”,
                 “issuerNr”:”2″,
                 “currencyCode”:”NGN”,
                 “cardProgram”:”UAT wallet”,
                 “channel”:”quicktellermobile”,
                 “merchantId”:”QTMOBILE1IZTTIS”,
                 “enabled”:true

            },

           “cardDetails”: [
                   {
                         “cardIdentifier”: “default”,
                        “maskedPan”: “506321*********0545”,
                         “status”: “unblocked”
                  },
                 {
                        “cardIdentifier”: “my-card”,
                       “maskedPan”: “506321*********1733”,
                         “status”: “unblocked”
                  }
              ]


      }
}

Get Card Details Endpoint

GET {scheme}://{host}:{port}/virtual-card/api/v1/cards/card-details

Request Type is application/json

Authorization: {passport generated bearer token}

Header Message description

Field#Field nameData typeMax lengthRequiredDescription
1mobileNumberString
Yes
2cardIdentifierString100YesThis is a name to identify each card attached to the same account

Sample Response

{
      “responseCode”: “00”,
      “responseMessage”: “Successful”,
      “data”: {
            “safeTokenStatus”: “SUCCESSFUL”,

            “payPhoneStatus”: “SUCCESSFUL”,

            “maskedPan”: “506321*********5396”,

            “currencyCode”: “NGN”,

            “seqNr”: “001”,

            “pan”: “5063210987654345396”,

            “cvv”: “333”,

            “cvv2”: “233”,

            “expiry”: “2501”,     

            “status”: “unblocked”

      }
}

Was this article helpful to you? Yes 1 No 1

How can we help?