REST API Requests

Register

This request registers a card to a wallet based on the MSISDN of the wallet.

METHOD: POST

Parameter	Type	Description
msisdn	String	MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format.
accountNumber	String	The account number that ties into the PAN that will be loaded to the wallet Consists of: Bank Card Number/PAN OR 6 Digits (BIN) 9 Digits (Account Number) 1 Digit (Check Digit) Minimum 14 and Maximum 19 characters.
account	String	The account type that the accountNumber/PAN will be linked with. [This is an optional parameter unless the accountNumber BIN (first 6 digits) requires it] Accepts the following: 10 [Savings] 20 [Current] 30 [Credit]
expiryDate	String	Expiry date of the accountNumber/PAN in format MMYY [This is an optional parameter].
imageId	Long	A wallet identifier to differentiate different wallet types [This is an optional parameter].
cardholderName	String	The name of the card holder/account holder [This is an optional parameter] Minimum 3 characters and Maximum 26 characters.
dateOfBirth	String	The date of birth of the cardholder/account holder in the format CCYYMMDD [This is an optional parameter]..
node	String	This determines which wallet the accountNumber/PAN will be associated with [This is an optional parameter] Contact the Scan to Pay service provider if you are unsure what the node should be for this request.
state	String	This is the state that the accountNumber/PAN will be in once it has been linked to the MSISDN. [This is an optional parameter – Defaults to LINKED if state parameter is not used] Accepts the following: LINKED [hard links the accountNumber/PAN to the MSISDN, no other MSISDN will be able to use the accountNumber/PAN] COSMETIC [cosmetically links the accountNumber/PAN to the MSISDN, the state will change to LINKED automatically once the customer has successfully performed a transaction. Another MSISDN will be able to use this accountNumber/PAN unless it is in a LINKED state.
validationMethod	String	This determines which type of validation the customer will experience when the accountNumber/PAN has been linked to their msisdn [This is an optional parameter if validation is required; if no validation is needed this parameter should not be sent] Accepts the following: SIMPLE [The customer will be prompted to accept the accountNumber/PAN linked to their MSISDN with a simple Yes or No. If Yes is selected the card will link to the MSISDN. If No is chosen the accountNumber/PAN will be delinked and any other MSISDN will be able to use it] DOB [If DOB is selected the customer will be prompted to enter the date of birth of the accountNumber/cardholder. If this matches to the DOB provided on this request then the validation will be successful, if this does not match the accountNumber/PAN will be delinked and any other MSISDN will be able to use it].

Returns - HTTP 200

Parameter	Type	Description
Results	String	Result of the API request. Expected results: SUCCESS FAIL ALREADY LINKED CARD LINKED TO PROFILE MAX CARDS LINKED CARD BLACKLISTED CARD NOT SUPPORTED CARD CHECK DIGITS FAIL CARD EXPIRED EXPIRY INVALID IMAGE ID INVALID CARDHOLDER NAME INVALID CARD DELINKED MISSING ACCOUNT INVALID CARD STATE

Sample Request

{
"msisdn": "27832006283",
"accountNumber": "5221008264807699",
“account”: ”30”, "cardholderName": "J Smith", "expiryDate": "1218",
"state": "LINKED",
"node": "SBSA",
"validationMethod": "SIMPLE", "dateOfBirth":  "19830711"
}

Delink

This request delinks a card from a wallet based on the MSISDN of the wallet.

METHOD: POST

Parameter

Type

Description

msisdn

String

MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format

accountNumber

String

The account number that ties into the PAN that will be loaded to the wallet
Consists of:

Bank Card Number/PAN OR
6 Digits (BIN)
9 Digits (Account Number)
1 Digit (Check Digit)
Minimum 14 and Maximum 19 characters.

Returns - HTTP 200

Parameter	Type	Description
result	String	Result of the API request [SUCCESS OR FAIL].

Sample Request

{
"msisdn”:  “27832006283",
"accountNumber”: “5338921234567891"
}

Block

This request blocks a card from a wallet based on the MSISDN of the wallet.

Parameter

Type

Description

msisdn

String

MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format

accountNumber

String

The account number that ties into the PAN that will be loaded to the wallet
Consists of:

Bank Card Number/PAN OR
6 Digits (BIN)
9 Digits (Account Number)
1 Digit (Check Digit)
Minimum 14 and Maximum 19 characters.

Returns - HTTP 200

Parameter	Type	Description
result	String	Result of the API request [SUCCESS OR FAIL].

Sample Request

{
"msisdn”:  “27832006283",
"accountNumber”: “5338921234567891"
}

Unblock

This request unblocks a card from a wallet based on the MSISDN of the wallet.

Parameter

Type

Description

msisdn

String

MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format

accountNumber

String

The account number that ties into the PAN that will be loaded to the wallet
Consists of:

Bank Card Number/PAN OR
6 Digits (BIN)
9 Digits (Account Number)
1 Digit (Check Digit)
Minimum 14 and Maximum 19 characters.

Returns - HTTP 200

Parameter	Type	Description
result	String	Result of the API request [SUCCESS OR FAIL].

Sample Request

{
"msisdn”:  “27832006283",
"accountNumber”: “5338921234567891"
}

Update

This request updates a card that is linked to a wallet already.

Parameter	Type	Description
msisdn	String	MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumber	String	The account number that ties into the PAN that will be loaded to the wallet Consists of: Bank Card Number/PAN OR 6 Digits (BIN) 9 Digits (Account Number) 1 Digit (Check Digit) Minimum 14 and Maximum 19 characters.
expiryDate	String	Expiry date of the accountNumber/PAN in format MMYY [This is an optional parameter, if imageId is supplied]
imageId	Long	A wallet identifier to differentiate different wallet types [This is an optional parameter, if expiryDate is supplied].
cardholderName	String	The name of the card holder/account holder [This is an optional parameter] Minimum 3 characters and Maximum 26 characters.

Returns - HTTP 200

Parameter	Type	Description
result	String	Result of the API request: SUCCESS FAIL ALREADY LINKED CARD LINKED TO PROFILE MAX CARDS LINKED CARD BLACKLISTED CARD NOT SUPPORTED CARD CHECK DIGITS FAIL CARD EXPIRED EXPIRY INVALID IMAGE ID INVALID CARDHOLDER NAME INVALID CARD DELINKED

Sample Request

{
"msisdn”:  “27832006283",
"accountNumber”: “5338921234567891",
"expiryDate”: “1216",
"imageId”:  “12345678901234567890",
“cardholderName”: “Mr J Smith”
}

Check Card Status

This request checks the status of a card.

Parameter

Type

Description

msisdn

String

MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format

accountNumber

String

The account number that ties into the PAN that will be loaded to the wallet
Consists of:

Bank Card Number/PAN OR
6 Digits (BIN)
9 Digits (Account Number)
1 Digit (Check Digit)
Minimum 14 and Maximum 19 characters.

Returns - HTTP 200

Parameter	Type	Description
result	String	Result of the API request. Expected results: ACTIVE BLOCKED DELINKED

Sample Request

{
"msisdn”:  “27832006283",
"accountNumber”: “5338921234567891"
}

Send Brand Indicator

This request sends a picture of the brand indicator as well as a description that will display in the wallet once the imageId is used on Register Card or Update Card.

Parameter	Type	Description
description	String	Narrative that will be displayed on the wallet for the card. Maximum characters allowed is 30.
image	Byte Array	The picture that forms part of the Brand Indicator that will be displayed on wallet.

Returns - HTTP 200

Parameter	Type	Description
imageId	Long	A wallet identifier to differentiate different wallet types. This must be used on the Register Card request if the wallet is to display the branding.

Sample Request

{
"description”: “ABC Bank"
}

Delink XXX

This request delinks a card from a wallet based on the MSISDN of the wallet.

METHOD: POST

Parameter

Type

Description

msisdn

String

MSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format

accountNumber

String

The account number that ties into the PAN that will be loaded to the wallet
Consists of:

Bank Card Number/PAN OR
6 Digits (BIN)
9 Digits (Account Number)
1 Digit (Check Digit)
Minimum 14 and Maximum 19 characters.

Returns - HTTP 200

Parameter	Type	Description
result	String	Result of the API request [SUCCESS OR FAIL].

Sample Request

{
"msisdn”:  “27832006283",
"accountNumber”: “5338921234567891"
}

Result Responses

The below can be expected if there is a problem with an API request; when a HTTP 200 is not returned.

Parameter	Description
HTTP 400	Bad Request.
HTTP 403	Invalid login details.
HTTP 440	Validation error.
HTTP 500	General system error.