Create Single Card

This API allows the creation of one card at a time, supporting various scenarios such as creating debit cards on new or existing accounts, reissuing debit cards, and creating new or reissuing existing prepaid cards. If a pre-generated PAN is provided, the service will attempt to create the card using it; otherwise, a PAN will be automatically generated. Additionally, the endpoint supports creating anonymous cards.

📘

What is a PAN ?

The primary account number or payment card number is a card identifier. It is made of 16-19 numbers which are found on the card.

Create A Single Card

To create a card successfully make a POST Request to the create single card endpoint.

/card-management/api/v1/card/request

These are the parameters of the request:

Query Parameters

Parameter #Parameter NameData TypeRequiredDescription
1cardTypestringtrueThe value can be any of :
1. DEBIT_NEW_ACCOUNT: The user does not exist yet within your platform.
2. DEBIT_EXISTING_ACCOUNT: The user account is already present on your platform.
3. DEBIT_REISSUE: Choose this option when you must re-issue a customer card.
4. PREPAID_NEW: The user account is not yet registered on your platform.
5. PREPAID_REISSUE: Choose this option when you must re-issue a card to a customer.
2isActiveActivebooleanfalseTrue: Select this option when you want to create a backup for the card.
False: Select this option when you don't want a backup.
3isAnonymousbooleanfalsetrue - This value lets you create an anonymous card without any customer-specific details. Account ID, Account Type, First Name, Last Name, and Name On Card are not required.

false - This value lets you link a customer to the card.

Body Parameters

Field #Field nameData typeMax lengthRequiredDescription
1issuerNrint3trueIssuer Number e.g 2
2cardProgramstring1 to 20trueCard Program e.g VERVE
3userIdstring3 to 20trueUser ID or Name e.g Alex
4accountIdstring10 to 28false/trueRequired for All Debit Card Types
5accountTypestring2 to 2false/trueRequired for All Debit Card Types
6lastNamestring30false/trueRequired for New Debit and Prepaid Cards
7firstNamestring30false/trueRequired for New Debit and Prepaid Cards
8nameOnCardstring25false/trueRequired for New Debit and Prepaid Cards
9panstring16 to 19false/trueRequired for Reissue Debit and Prepaid Cards
10lostOrStolenbooleantrue or falsefalse/trueRequired for Reissue Debit and Prepaid Cards
11pinstring4falseThe default is 1234 when not provided
12branchCodestring10false
13customerIdstring25falseCustomer ID is autogenerated when not provided
14mobileNrstring50falseCustomer Mobile Number
15emailAddressstring70falseCustomer Email Address
16streetAddressstring100falseStreet Address
17streetAddressLine2string100falseStreet Address Line 2
18citystring40falseCity
19statestring20falseState
20postalCodestring20falsePostal Code
21countryCodestring3falseCountry Code.
22titlestring10falseCustomer Title e.g. Mr
23middleNamestring30falseCustomer Middle Name
24dateOfBirthstring8 to 8falseDate of Birth in the format YYYYMMDD e.g 19810130.
25ridstring1 to 11falseReceiving Institution Identifier obtained from the Interswitch operations team

This is what a typical request would look like for the different card types:

{
    "issuerNr" : "1",
    "cardProgram" : "Suntrust_Verve",
    "userId" : "Alex",
    "pin" : "1234",
    "branchCode" : "10010",
    "accountId" : "{{randomNumber}}",
    "accountType" : "20",
    "lastName" : "Test",
    "firstName" : "Test",
    "nameOnCard" : "Test"
}
{
   "issuerNr" : "72",
    "cardProgram" : "INFINITYPLUS",
    "userId" : "Ola",
    "pin" : "2210",
    "branchCode" : "10010",
   "customerId" : "800639",
    "accountId" : "0000800639",
    "accountType" : "20"
}


{
    "issuerNr" : "2",
    "cardProgram" : "VERVE",
    "userId" : "Alex",
    "pin" : "1234",
    "branchCode" : "10010",
    "customerId" : "1234567866",
    "accountId" : "1234567866",
    "accountType" : "20",
    "pan" : "5060990000000056086",
    "lostOrStolen" : "false"
}
{
    "issuerNr" : "72",
    "cardProgram" : " INFINITYPLUS",
    "userId" : "Alex",
    "lastName" : "Test",
    "firstName" : "Test",
    "nameOnCard" : "Test"
}
{
    "issuerNr" : "2",
    "cardProgram" : "VERVE",
    "userId" : "Alex",
    "pin" : "1234",
    "pan" : "5060990000000054222",
    "lostOrStolen" : "false"
}

📘

  1. DEBIT_NEW_ACCOUNT: The user does not exist yet within your platform.
  2. DEBIT_EXISTING_ACCOUNT: The user account is already present on your platform.
  3. DEBIT_REISSUE: Choose this option when you must re-issue a customer card.
  4. PREPAID_NEW: The user account is not yet registered on your platform.
  5. PREPAID_REISSUE: Choose this option when you must re-issue a card to a customer.

Response message  field description

Field #Field nameDescription
1codeInternal Response Code
2descriptionSuccessful or Error Message
3correlationIdRequest identifier
4cardCard details if the card request is successful
5successfulif true, the card has been generated and issued successfully or else card may have been generated but not issued successfully

This is what a typical successful or failed response would look like

{
    "code": "00",
    "description": "Successful",
    "correlationId": "2f6b1ebb444845a0b896fefab2fb254b",
    "card": {
        "pan": "5061800000000000389",
        "seqNr": "001",
        "expiryDate": "2508",
        "pinOffset": "7183",
        "cvv": "902",
        "cvv2": "840",
        "pinInfo": "3DD636885F8CBAA5",
        "track2": "5061800000000000389=2508101007183902",
        "customerId": "20220811144303279780389"
    },
    "successful": true
}
{
    "code": "10409",
    "description": "Account already exists.",
    "correlationId": "ff5c14d25d4e4c06aacadcb17f2beea1",
    "successful": false
}

Create An Anonymous Card

An anonymous card is a card without customer-specific details. Account ID, Account Type, First Name, Last Name, and Name On Card.

To create an anonymous card successfully make a POST Request to the create single card endpoint.

POST /card-management/api/v1/card/request?isAnonymous=true&isActiveActive=false&cardType=DEBIT_EXISTING_ACCOUNT

An anonymous card can be created and then later assigned to a customer. To create an anonymous card the isAnonymous query parameter must be set to true. This will enable the application to set the following fields to their corresponding default values if they have not been set in the request.

Field #Field nameData typeMax lengthDefaultDescription
1accountIdstring10 to 28666666666666666Required for All Debit Card Types
2accountTypestring2 to 220Required for All Debit Card Types
3lastNamestring30AnonymousRequired for New Debit and Prepaid Cards
4firstNamestring30AnonymousRequired for New Debit and Prepaid Cards
5nameOnCardstring25AnonymousRequired for New Debit and Prepaid Cards
6customerIdstring2520220524081136189680261Required for Reissue Debit and Prepaid Cards

The request should look like this :

{
    "issuerNr" : "1",
    "cardProgram" : "Suntrust_Verve",
    "userId" : "Alex",
    "pin" : "1234",
    "branchCode" : "10010",
    "accountId" : "1234567853",
    "accountType" : "20",
    "lastName" : "Test",
    "firstName" : "Test",
    "nameOnCard" : "Test"
}

Response Message  field description

Field #Field nameDescription
1codeInternal Response Code
2descriptionSuccessful or Error Message
3correlationIdRequest identifier
4cardCard details if the card request is successful
5successfulif true, the card has been generated and issued successfully.

else card may have been generated but not issued successfully

(card request on Postilion might have failed)
6errorsErrors array if any errors exist.

This is what a typical successful or failed response would look like.

{
    "code": "00",
    "description": "Successful",
    "correlationId": "2f6b1ebb444845a0b896fefab2fb254b",
    "card": {
        "pan": "5061800000000000389",
        "seqNr": "001",
        "expiryDate": "2508",
        "pinOffset": "7183",
        "cvv": "902",
        "cvv2": "840",
        "pinInfo": "3DD636885F8CBAA5",
        "track2": "5061800000000000389=2508101007183902",
        "customerId": "20220811144303279780389"
    },
    "successful": true
}
{
    "code": "10409",
    "description": "Account already exists.",
    "correlationId": "ff5c14d25d4e4c06aacadcb17f2beea1",
    "successful": false
}

Retry Single Card Creation

If a server-side error (having error code 500) is returned after initially sending a single card creation request, this API can be called to retry the request with the same parameters and request body.

POST /card-management/api/v1/card/retryCardRequest

These are the parameters of the request:

Body Parameters

Field #Field nameData typeMax lengthRequiredDescription
1cardReferencestring32trueRequest Correlation ID e.g 6beae9e078434c96b9fc16892d7f30ba

This is what a request would look like

{
  "cardReference": "6beae9e078434c96b9fc16892d7f30ba"
}

Response Message  field description

Field #Field nameDescription
1codeInternal Response Code
2descriptionSuccessful or Error Message
3correlationIdRequest identifier
4cardCard details if the card request is successful
5successfulif true, the card has been generated and issued successfully.

else card may have been generated but not issued successfully
6errorsErrors array if any errors exist.

This is what a typical successful or failed response would look like

{
    "code": "00",
    "description": "Successful",
    "correlationId": "2f6b1ebb444845a0b896fefab2fb254b",
    "card": {
        "pan": "5061800000000000389",
        "seqNr": "001",
        "expiryDate": "2508",
        "pinOffset": "7183",
        "cvv": "902",
        "cvv2": "840",
        "pinInfo": "3DD636885F8CBAA5",
        "track2": "5061800000000000389=2508101007183902",
        "customerId": "20220811144303279780389"
    },
    "successful": true
}
{
    "code": "10409",
    "description": "Account already exists.",
    "correlationId": "ff5c14d25d4e4c06aacadcb17f2beea1",
    "successful": false
}