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. |
Updated almost 2 years ago