PSP/Aggregator requests

Create Merchant

This is used to create a merchant on behalf of a PSP/Aggregator. Once the merchant is created it will be in an active state and transactions can be processed using the account information. The email address used on this request will receive an email confirming that a merchant has been created.

METHOD: POST
ENDPOINT: /create

Parameter	Type	Description
email	String	The admin email that will get access to the merchant account to view transactions and generate API credentials, if required (Mandatory parameter).
merchantName	String	The name of the merchant that will be created (Mandatory parameter – up to 45 characters).
cardAcceptorTerminalId	String	The terminal id as provided by the acquirer (Mandatory parameter – 8 characters) Note: If the acquirer is NEDBANK then the application id must be populated in this field.
cardAcceptorIdentificationCode	String	The merchant id as provided by the acquirer (Mandatory parameter – left zero filled up to 15 characters) Note: If the acquirer is NEDBANK then the application id must be populated in this field.
cardAcceptorNameLocation	String	This is the country code for the merchant being created. Eg: ZA for South Africa (Mandatory parameter – 2 characters).
merchantCategoryCode	String	The 4-digit merchant category code (MCC) as per the merchant being created (Mandatory parameter).
acquirer	String	The acquirer for the merchant being created. Must be one of the following: ABSA CAPITEC FNB NEDBANK(merchants processing via iVeri to Nedbank acquiring) NEDBANK-DIRECT (merchants processing directly to Nedbank acquiring) SBSA TRADEROOT-NEDBANK (merchants processing via Traderoot to Nedbank acquiring) (Mandatory parameter)
address	String	Address of the merchant. This is a JSON object consisting of the following: (i) addressLine1 – street address or building name (max 145 characters) (ii) addressLine2 – street address or building name (max 145 characters) (iii) suburb – suburb of the merchant (max 75 characters) (iv) city – city of the merchant (max 75 characters) (v) country – country of the merchant (max 45 characters) (vi) postalCode – postal code of the merchant (max 10 characters) (vii) latitude – latitude in relation to the merchant’s location (float eg. -26.133811350561043) (viii) longitude – longitude in relation to the merchant’s location (float eg. 28.069205899997492)
acceptedCards	String	The card schemes accepted by the merchant. Current supported card schemes: master visa maestro cup amex diners discover** If this field is omitted the below default will be applied in relation with the acquirer: ABSA: master, visa, maestro CAPITEC: master, visa, maestro NEDBANK(Iveri): master, visa, maestro, amex NEDBANK-DIRECT: master, visa, maestro, amex SBSA: master, visa, maestro, diners FNB: master, visa, maestro TRADEROOT-NEDBANK: master, visa, maestro

Returns - HTTP 200

Parameter	Type	Description
email	String	The admin email that was used echoed back.
merchantName	String	The name of the merchant that was created.
cardAcceptorTerminalId	String	The terminal id or application id as provided by the acquirer.
cardAcceptorIdentificationCode	String	The merchant id or application id as provided by the acquirer.
cardAcceptorNameLocation	String	This is the country code for the merchant being created.
merchantCategoryCode	String	The 4-digit merchant category code (MCC).
acquirer	String	The acquirer for the merchant.
pspId	Long	The PSP id that was used on this request.
address	String	Address of the merchant. This is a JSON object consisting of the following: (i) addressLine1 – street address or building name (ii) addressLine2 – street address or building name (iii) suburb – suburb of the merchant (iv) city – city of the merchant (v) country – country of the merchant (vi) postalCode – postal code of the merchant (vii) latitude – latitude in relation to the merchant’s location (viii) longitude – longitude in relation to the merchant’s location
merchantStatus	String	The status of the create merchant request. Once the merchant is created it will be in a “ACTIVE” state.

Sample Request

{
"email":"[email protected]",
"merchantName":"MRA Test Merch 04",
"cardAcceptorTerminalId":"12345678",
"cardAcceptorIdentificationCode":"123456789012345",
"cardAcceptorNameLocation":"ZA",
"merchantCategoryCode":"4812",
"acquirer":"SBSA",
"address":{"addressLine1":"12 Smith Place","addressLine2":"First Floor","suburb":"Melrose Arch","city":"Johannesburg","country":"South Africa","postalCode": "2196","latitude":"-26.133811350561043","longitude":"28.069205899997492",
"acceptedCards":["master", "visa"]
}

Sample Response

{
"email": "[email protected]",
"merchantName": "MRA Test Merch 04",
"acquirer": "SBSA",
"cardAcceptorTerminalId": "12345678",
"cardAcceptorIdentificationCode": "123456789012345",
"cardAcceptorNameLocation": "ZA",
"merchantCategoryCode": "4812",
"pspId": 272,
"merchantId": 451,
    "address": {
        "addressLine1": "12 Smith Place",
        "addressLine2": "First Floor",
        "suburb": "Melrose Arch",
        "city": "Jhb",
        "country": "South Africa",
        "postalCode": "2196",
        "latitude": -26.133812,
        "longitude": 28.069206
    }
"merchantStatus": "ACTIVE"
}

Suspend Merchant

This is used to suspend a merchant on behalf of a PSP/Aggregator. A reason for suspension must be provided. The merchant being suspended must be linked to the PSP/Aggregator. A reason must be provided.

METHOD: POST
ENDPOINT: /suspend

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that is being suspended linked to the PSP.
reason	String	A reason for suspending the merchant.

Sample Request

{
"merchantId": 451,
"reason": "Merchant no longer active"
}

Unsuspend Merchant

This is used to unsuspend a merchant on behalf of a PSP/Aggregator. A reason must be provided.

METHOD: POST
ENDPOINT: /unsuspend

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that is being suspended linked to the PSP.
reason	String	A reason for unsuspending the merchant.

Sample Request

{
"merchantId": 451,
"reason": "Merchant now active"
}

Update Merchant

This is used to update an existing merchant on behalf of a PSP/Aggregator.

METHOD: POST
ENDPOINT: /update

Parameter	Type	Description
email	String	The admin email that will get access to the merchant account to view transactions and generate API credentials, if required (Mandatory parameter).
merchantName	String	The name of the merchant that will be created (Mandatory parameter – up to 45 characters).
cardAcceptorTerminalId	String	The terminal id as provided by the acquirer (Mandatory parameter – 8 characters) Note: If the acquirer is NEDBANK then the application id must be populated in this field.
cardAcceptorIdentificationCode	String	The merchant id as provided by the acquirer (Mandatory parameter – left zero filled up to 15 characters) Note: If the acquirer is NEDBANK then the application id must be populated in this field.
cardAcceptorNameLocation	String	This is the country code for the merchant being created. Eg: ZA for South Africa (Mandatory parameter – 2 characters).
merchantCategoryCode	String	The 4-digit merchant category code (MCC) as per the merchant being created (Mandatory parameter).
acquirer	String	The acquirer for the merchant being created. Must be one of the following: ABSA CAPITEC FNB NEDBANK(merchants processing via iVeri to Nedbank acquiring) NEDBANK-DIRECT (merchants processing directly to Nedbank acquiring) SBSA TRADEROOT-NEDBANK (merchants processing via Traderoot to Nedbank acquiring) (Mandatory parameter)
address	String	Address of the merchant. This is a JSON object consisting of the following: (i) addressLine1 – street address or building name (max 145 characters) (ii) addressLine2 – street address or building name (max 145 characters) (iii) suburb – suburb of the merchant (max 75 characters) (iv) city – city of the merchant (max 75 characters) (v) country – country of the merchant (max 45 characters) (vi) postalCode – postal code of the merchant (max 10 characters) (vii) latitude – latitude in relation to the merchant’s location (float eg. -26.133811350561043) (viii) longitude – longitude in relation to the merchant’s location (float eg. 28.069205899997492)
acceptedCards	String	The card schemes accepted by the merchant. Current supported card schemes: master visa maestro cup amex diners discover** If this field is omitted the below default will be applied in relation with the acquirer: ABSA: master, visa, maestro CAPITEC: master, visa, maestro NEDBANK(Iveri): master, visa, maestro, amex NEDBANK-DIRECT: master, visa, maestro, amex SBSA: master, visa, maestro, diners FNB: master, visa, maestro TRADEROOT-NEDBANK: master, visa, maestro

Returns - HTTP 200

Parameter	Type	Description
email	String	The admin email that was used echoed back.
merchantName	String	The name of the merchant that was created.
cardAcceptorTerminalId	String	The terminal id or application id as provided by the acquirer.
cardAcceptorIdentificationCode	String	The merchant id or application id as provided by the acquirer.
cardAcceptorNameLocation	String	This is the country code for the merchant being created.
merchantCategoryCode	String	The 4-digit merchant category code (MCC).
acquirer	String	The acquirer for the merchant.
pspId	Long	The PSP id that was used on this request.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce.
merchantStatus	String	The status of the create merchant request. Once the merchant is created it will be in a “ACTIVE” state.

Sample Request

{
"email":"[email protected]",
"merchantName":"MRA Test Merch 06",
"cardAcceptorTerminalId":"1234abcd",
"cardAcceptorIdentificationCode":"123456789012345",
"cardAcceptorNameLocation":"ZA",
"merchantCategoryCode":"5967",
"acquirer":"CAPITEC",
"merchantId" :451,
"address":{"addressLine1":"12 Smith Place","addressLine2":"First Floor","suburb":"Melrose Arch","city":"Jhb","country":"South Africa","postalCode": "2196","latitude":"-26.133811350561043","longitude":"28.069205899997492"},
"acceptedCards":["master", "visa"]
}

Sample Response

{
"email": "[email protected]",
"merchantName": "MRA Test Merch 06",
"acquirer": "CAPITEC",
"cardAcceptorTerminalId": "1234abcd",
"cardAcceptorIdentificationCode": "123456789012345",
"cardAcceptorNameLocation": "ZA",
"merchantCategoryCode": "5967",
"pspId": 272,
"merchantId": 451,
    "address": {
        "addressLine1": "12 Smith Place",
        "addressLine2": "First Floor",
        "suburb": "Melrose Arch",
        "city": "Jhb",
        "country": "South Africa",
        "postalCode": "2196",
        "latitude": -26.133812,
        "longitude": 28.069206
    }
"merchantStatus": "ACTIVE"
}

Add HTTP Notification

This is used to add an HTTP payment notification to an existing merchant on behalf of a PSP/Aggregator. This is only required for integrations that require a real-time server-to-server notification. Once a transaction is performed for this merchant a notification payload is sent from Scan to Pay to the HTTP URL and the notification must be decrypted using the latest encrypt/notification key to obtain the payment status.

METHOD: POST
ENDPOINT: /notification/addHttp

Parameter	Type	Description
url	String	The URL that the payment notification payload will be sent to by Scan to Pay (Mandatory parameter).
merchantId	Long	The Scan to Pay merchant id that the HTTP notification URL will be loaded for (Mandatory parameter).

Returns - HTTP 200

Parameter	Type	Description
encryptKey	String	The notification key that will be used to decrypt the payload that was sent by Scan to Pay.
type	String	The notification type. This will be “http” when a HTTP notification is added to a merchant profile
url	String	The URL echoed back.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce.

Sample Request

{
"url":"https://www.notificationsiteurl.com/",
"merchantId": 451
}

Sample Response

{
"encryptKey": "5F539AB73FE72E1A488FE58779E18123",
"type": "http",
"url": "https://www.notificationsiteurl.com/",
"merchantId": 451
}

Renew HTTP Notification

This is used to renew the notification key for an existing merchant on behalf of a PSP/Aggregator. This is only required for integrations that require a real-time server-to-server notification. Once a transaction is performed for this merchant a notification payload is sent from Scan to Pay to the HTTP URL and the notification must be decrypted using the latest encrypt/notification key to obtain the payment status.

METHOD: POST
ENDPOINT: /notification/renewKey

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that the HTTP notification URL will be loaded for (Mandatory parameter).

Returns - HTTP 200

Parameter	Type	Description
encryptKey	String	The notification key that will be used to decrypt the payload that was sent by Scan to Pay.
type	String	The notification type.
url	String	The URL echoed back.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce.

Sample Request

{
"merchantId": 451
}

Sample Response

{
"encryptKey": "2837DF48F46D7B3CAED5BB6E17BB0123",
"type": "http",
"url": "https://www.notificationsiteurl.com/",
"merchantId": 451
}

List Notifications

This is used to list the notifications for a specific Scan to Pay merchant

METHOD: POST
ENDPOINT: /notification/list

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that the HTTP notification URL will be loaded for (Mandatory parameter).

Returns - HTTP 200

Parameter	Type	Description
value	String	The value configured for the notification type
type	String	The notification type. This could be either HTTP, EMAIL, or SMS
version	String	The version in relation to the notification type
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce echoed back from the request body.

Sample Request

{
"merchantId": 9885
}

Sample Response

{
        "value": "https://www.scantopay.io",
        "type": "HTTP",
        "merchantId": 9885,
        "version": "2"
    },
    {
        "value": "[email protected]",
        "type": "EMAIL",
        "merchantId": 9885,
        "version": "1"
    },
    {
        "value": "27832001234",
        "type": "SMS",
        "merchantId": 9885,
        "version": "1"
    }

Renew API Password

This is used to generate or renew the API password for a merchant on behalf of a PSP/Aggregator. Once the API password is renewed the old API password will no longer work.

METHOD: POST
ENDPOINT: /renewApiKey

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that the HTTP notification URL will be loaded for (Mandatory parameter).

Returns - HTTP 200

Parameter	Type	Description
apiKey	String	The API key that the merchant will use when sending requests for creating codes and generating ecommerce transactions.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce

Sample Request

{
"merchantId": 451
}

Sample Response

{
"apiKey": "0AA19D924BC7477855E70921D5812345",
"merchantId": 451
}

Show Merchant List

This displays a list of merchants linked to the PSP/Aggregator in a JSON array.
METHOD: GET
ENDPOINT: /list

Returns the following:

Parameter	Type	Description
email	String	The admin email that was used echoed back.
merchantName	String	The name of the merchant that was created.
cardAcceptorTerminalId	String	The terminal id or application id as provided by the acquirer.
cardAcceptorIdentificationCode	String	The merchant id or application id as provided by the acquirer.
cardAcceptorNameLocation	String	This is the country code for the merchant being created.
merchantCategoryCode	String	The 4-digit merchant category code (MCC).
acquirer	String	The acquirer for the merchant.
pspId	Long	The PSP id that was used on this request.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce.
merchantStatus	String	The status of the merchant. Can be ACTIVE, SUSPENDED.
address	String	Address of the merchant. This is a JSON object consisting of the following: (if address information is available) (i) addressLine1 – street address or building name (ii) addressLine2 – street address or building name (iii) suburb – suburb of the merchant (iv) city – city of the merchant (v) country – country of the merchant (vi) postalCode – postal code of the merchant (vii) latitude – latitude in relation to the merchant’s location longitude – longitude in relation to the merchant’s location

Sample Response

[
    {
        "email": "[email protected]",
        "merchantName": "Merchant123ABC",
        "acquirer": "SBSA",
        "cardAcceptorTerminalId": "0000KAB1",
        "cardAcceptorIdentificationCode": "000000002740000",
        "cardAcceptorNameLocation": "ZA",
        "merchantCategoryCode": "4814",
        "pspId": 199,
        "merchantId": 123,
        "address": {
            "addressLine1": "12 Smith Place",
            "addressLine2": "Test Street",
            "suburb": "Sandton",
            "city": "Johannesburg",
            "country": "South Africa",
            "postalCode": "2196",
            "latitude": -26.133812,
            "longitude": 28.06920
        },
        "merchantStatus": "ACTIVE"
    },
    {
        "email": "[email protected]",
        "merchantName": "The Test Shop",
        "acquirer": "ABSA",
        "cardAcceptorTerminalId": "98000678",
        "cardAcceptorIdentificationCode": "1007123",
        "cardAcceptorNameLocation": "ZA",
        "merchantCategoryCode": "5967",
        "pspId": 199,
        "merchantId": 222,
        "merchantStatus": "ACTIVE"
    }
]

Generate In-App (Lib Lite) Token

This is used to generate a Scan to Pay In-App (Lib Lite) token that is required when processing payments using the Scan to Pay In-App (Lib Lite) SDK.

METHOD: POST
ENDPOINT: /libLite/generateToken

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that the token will be generated for (Mandatory parameter).

Returns - HTTP 200

Parameter	Type	Description
token	String	The actual token that is generated on the Scan to Pay platform to be used when calling the Scan to Pay In App (Lib Lite) SDK.
status	String	The notification type.
dateCreated	String	The URL echoed back.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce.

Sample Request

{
"merchantId": 2305
}

Sample Response

[
    {
        "token": "6D3EAC4921584605B67FBF8DA3F81123",
        "merchantId": 2305,
        "dateCreated": "2019-10-31 07:31:55",
        "status": "ACTIVE"
    },
    {
        "token": "DAA6CDC727CACF6DE93C5EAE0F8C0123",
        "merchantId": 2300,
        "dateCreated": "2017-09-20 09:56:59",
        "status": "ACTIVE"
    }
]

Get In App (Lib Lite) Tokens

This is used to list all In App (Lib Lite) tokens for a specific merchant id on Scan to Pay

METHOD: GET
ENDPOINT: /libLite/listTokens/123 (where 123 is the Scan to Pay merchant id)

Parameter	Type	Description
merchantId	Long	The Scan to Pay merchant id that the token will be generated for (Mandatory parameter – used as part of the GET request)

Returns - HTTP 200

Parameter	Type	Description
token	String	The actual token that is generated on the Scan to Pay platform to be used when calling the Scan to Pay In App (Lib Lite) SDK.
status	String	The notification type.
dateCreated	String	The URL echoed back.
merchantId	Long	The Scan to Pay merchant id created for this merchant that will be used on other Scan to Pay API requests for creating codes and ecommerce.

Sample Request

{
"merchantId": 2305
}

Sample Response

[
    {
        "token": "6D3EAC4921584605B67FBF8DA3F81123",
        "merchantId": 2305,
        "dateCreated": "2019-10-31 07:31:55",
        "status": "ACTIVE"
    },
    {
        "token": "DAA6CDC727CACF6DE93C5EAE0F8C0123",
        "merchantId": 2300,
        "dateCreated": "2017-09-20 09:56:59",
        "status": "ACTIVE"
    }
]