REST API Requests

Register

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

METHOD: POST

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format.
accountNumberStringThe 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.
accountStringThe 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]
expiryDateStringExpiry date of the accountNumber/PAN in format MMYY [This is an optional parameter].
imageIdLongA wallet identifier to differentiate different wallet types [This is an optional parameter].
cardholderNameStringThe name of the card holder/account holder [This is an optional parameter]
Minimum 3 characters and Maximum 26 characters.
dateOfBirthStringThe date of birth of the cardholder/account holder in the format CCYYMMDD
[This is an optional parameter]..
nodeStringThis 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.
stateStringThis 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.
validationMethodStringThis 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

ParameterTypeDescription
ResultsStringResult 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

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumberStringThe 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

ParameterTypeDescription
resultStringResult 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.

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumberStringThe 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

ParameterTypeDescription
resultStringResult 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.

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumberStringThe 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

ParameterTypeDescription
resultStringResult 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.

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumberStringThe 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.
expiryDateStringExpiry date of the accountNumber/PAN in format MMYY [This is an optional parameter, if imageId is supplied]
imageIdLongA wallet identifier to differentiate different wallet types [This is an optional parameter, if expiryDate is supplied].
cardholderNameStringThe name of the card holder/account holder [This is an optional parameter]
Minimum 3 characters and Maximum 26 characters.

Returns - HTTP 200

ParameterTypeDescription
resultStringResult 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.

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumberStringThe 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

ParameterTypeDescription
resultStringResult 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.

ParameterTypeDescription
descriptionStringNarrative that will be displayed on the wallet for the card. Maximum characters allowed is 30.
imageByte ArrayThe picture that forms part of the Brand Indicator that will be displayed on wallet.

Returns - HTTP 200

ParameterTypeDescription
imageIdLongA 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

ParameterTypeDescription
msisdnStringMSISDN of the wallet or app that the card will be loaded to. The MSISDN must be in international format
accountNumberStringThe 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

ParameterTypeDescription
resultStringResult 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.

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