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 Name	Data Type	Required	Description
1	cardType	string	true	The 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.
2	isActiveActive	boolean	false	True: Select this option when you want to create a backup for the card. False: Select this option when you don't want a backup.
3	isAnonymous	boolean	false	true - 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 name	Data type	Max length	Required	Description
1	issuerNr	int	3	true	Issuer Number e.g 2
2	cardProgram	string	1 to 20	true	Card Program e.g VERVE
3	userId	string	3 to 20	true	User ID or Name e.g Alex
4	accountId	string	10 to 28	false/true	Required for All Debit Card Types
5	accountType	string	2 to 2	false/true	Required for All Debit Card Types
6	lastName	string	30	false/true	Required for New Debit and Prepaid Cards
7	firstName	string	30	false/true	Required for New Debit and Prepaid Cards
8	nameOnCard	string	25	false/true	Required for New Debit and Prepaid Cards
9	pan	string	16 to 19	false/true	Required for Reissue Debit and Prepaid Cards
10	lostOrStolen	boolean	true or false	false/true	Required for Reissue Debit and Prepaid Cards
11	pin	string	4	false	The default is 1234 when not provided
12	branchCode	string	10	false
13	customerId	string	25	false	Customer ID is autogenerated when not provided
14	mobileNr	string	50	false	Customer Mobile Number
15	emailAddress	string	70	false	Customer Email Address
16	streetAddress	string	100	false	Street Address
17	streetAddressLine2	string	100	false	Street Address Line 2
18	city	string	40	false	City
19	state	string	20	false	State
20	postalCode	string	20	false	Postal Code
21	countryCode	string	3	false	Country Code.
22	title	string	10	false	Customer Title e.g. Mr
23	middleName	string	30	false	Customer Middle Name
24	dateOfBirth	string	8 to 8	false	Date of Birth in the format YYYYMMDD e.g 19810130.

This is what a typical request would look like :

{
    "issuerNr": "2",
    "cardProgram": "VERVE",
    "userId": "Alex",
    "pin": "2493",
    "customerId": "347561",
    "accountId": "0000347563",
    "accountType": "20",
    "lastName": "Uko",
    "firstName": "Francess",
    "nameOnCard": "Francess Uko",
    "dateOfBirth": "19980609",
    "emailAddress": "[email protected]",
    "currencyCode": "566",
    "mobileNr": "080321627942",
    "streetAddress": "12 eiuoi",
    "streetAddressLine2": "Delaware",
    "city": "Lagos",
    "state": "Lagos",
    "postalCode": "23401",
    "countryCode": "NGN",
    "lostOrStolen": false
}

Response message field description

Field #	Field name	Description
1	code	Internal Response Code
2	description	Successful or Error Message
3	correlationId	Request identifier
4	card	Card details if the card request is successful
5	successful	if 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": "fd372f57378b40e9b201bd1267f8aa9e",
    "card": {
        "pan": "5060990000001048132",
        "seqNr": "001",
        "expiryDate": "5004",
        "pinOffset": "4713",
        "cvv": "700",
        "cvv2": "352",
        "pinInfo": "57968BF9D1C35F7F",
        "track2": "5060990000001048132=5004101004713700",
        "customerId": "20220524081136189680261"
    },
    "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 name	Data type	Max length	Default	Description
1	accountId	string	10 to 28	666666666666666	Required for All Debit Card Types
2	accountType	string	2 to 2	20	Required for All Debit Card Types
3	lastName	string	30	Anonymous	Required for New Debit and Prepaid Cards
4	firstName	string	30	Anonymous	Required for New Debit and Prepaid Cards
5	nameOnCard	string	25	Anonymous	Required for New Debit and Prepaid Cards
6	customerId	string	25	20220524081136189680261	Required for Reissue Debit and Prepaid Cards

The request should look like this :

{
    "issuerNr" : "2",
    "cardProgram" : "VERVE",
    "userId" : "Alex",
    "pin" : "1234",
    "branchCode" : "10010",
    "accountId": "3322978901"
}

Response Message field description

Field #	Field name	Description
1	code	Internal Response Code
2	description	Successful or Error Message
3	correlationId	Request identifier
4	card	Card details if the card request is successful
5	successful	if 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)
6	errors	Errors 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 name	Data type	Max length	Required	Description
1	cardReference	string	32	true	Request Correlation ID e.g 6beae9e078434c96b9fc16892d7f30ba

This is what a request would look like

{
  "cardReference": "6beae9e078434c96b9fc16892d7f30ba"
}

Response Message field description

Field #	Field name	Description
1	code	Internal Response Code
2	description	Successful or Error Message
3	correlationId	Request identifier
4	card	Card details if the card request is successful
5	successful	if true, the card has been generated and issued successfully. else card may have been generated but not issued successfully
6	errors	Errors 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
}

📘What is a PAN ?

Create A Single Card

Create An Anonymous Card

Retry Single Card Creation

📘
What is a PAN ?