Acquirer Requests

Create Merchant

This is used to create a merchant on behalf of an acquirer. Once the merchant is created it will be in an “ACTIVE”. 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).
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)
secureCodeMerchantId	String	This is a custom merchant id that will be used specifically for processing 3DSecure transactions as part of the 3DSecure lookup request. This can only be obtained by the merchant’s acquirer. If not sent, a default acquirer specific merchant id will be used. If an incorrect value is sent, 3DSecure transactions will not process correctly. (Optional parameter – max 45 characters)

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

Sample Request

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

Sample Response

{
"email": "[email protected]",
"merchantName": "MRA Test Merch 07",
"acquirer": "SBSA",
"cardAcceptorTerminalId": "12345678",
"cardAcceptorIdentificationCode": "123456789012345",
"cardAcceptorNameLocation": "ZA",
"merchantCategoryCode": "4812",
"pspId": 11,
"merchantId": 2305,
    "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 an acquirer. A reason for suspension 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 acquirer.
reason	String	A reason for suspending the merchant.

Sample Request

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

Unsuspend Merchant

This is used to unsuspend a merchant on behalf of an acquirer. A reason must be provided.

METHOD: POST
ENDPOINT: /unsuspend

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

Sample Request

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

Update Merchant

This is used to update an existing merchant on behalf of an acquirer.

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).
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)
secureCodeMerchantId	String	This is a custom merchant id that will be used specifically for processing 3DSecure transactions as part of the 3DSecure lookup request. This can only be obtained by the merchant’s acquirer. If not sent, a default acquirer specific merchant id will be used. If an incorrect value is sent, 3DSecure transactions will not process correctly. (Optional parameter – max 45 characters)

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.
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 longitude – longitude in relation to the merchant’s location

Sample Request

{
"email":"[email protected]",
"merchantName":"MRA Test Merch 07",
"cardAcceptorTerminalId":"1234abcd",
"cardAcceptorIdentificationCode":"123456789012345",
"cardAcceptorNameLocation":"ZA",
"merchantCategoryCode":"5967",
"pspId" :35,
"merchantId" :2305
}

Sample Response

{
"email": "[email protected]",
"merchantName": "MRA Test Merch 07",
"acquirer": "CAPITEC",
"cardAcceptorTerminalId": "1234abcd",
"cardAcceptorIdentificationCode": "123456789012345",
"cardAcceptorNameLocation": "ZA",
"merchantCategoryCode": "5967",
"pspId": 35,
"merchantId": 2305,
"merchantStatus": "ACTIVE"
}

Add HTTP Notification

This is used to add a HTTP payment notification to an existing merchant on behalf of an acquirer. 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.
version	String	Can be either 1 or 2. This will default to version 1; version 2 is for a future release on the HTTP notification module

Sample Request

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

Sample Response

{
"encryptKey": "9D263F97DFD2B10E7FE2F0A4AE712345",
"type": "http",
"url": "https://www.notificationsiteurl.com/",
"merchantId": 2305,
"version": "1"
}

Renew HTTP Notification

This is used to renew the notification key for an existing merchant on behalf of an acquirer. 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": 2305,
}

Sample Response

{
"encryptKey": "9D263F97DFD2B10E7FE2F0A4AE7ABC12",
"type": "http",
"url": "https://www.notificationsiteurl.com/",
"merchantId": 2305
}

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 an acquirer. 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": 2305,
}

Sample Response

{
"apiKey": "8CD0E11FE852E96EF75428347F5AFC99",
"merchantId": 2305
}

Show Merchant List

This displays a list of merchants linked to the acquirer 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 create merchant request. Once the merchant is created it will be in a “WAITING ACTIVATION” status and then needs to be activated.
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": "MRA Test Merch 06",
"acquirer": "CAPITEC",
"cardAcceptorTerminalId": "12345678",
"cardAcceptorIdentificationCode": "123456789012345",
"cardAcceptorNameLocation": "ZA",
"merchantCategoryCode": "4812",
"pspId": 35,
"merchantId": 2305,
"merchantStatus": "WAITING ACTIVATION"
},
{
"email": "[email protected]",
"merchantName": "MRA Test Merch 07",
"acquirer": "CAPITEC",
"cardAcceptorTerminalId": "1234abcd",
"cardAcceptorIdentificationCode": "123456789012345",
"cardAcceptorNameLocation": "ZA",
"merchantCategoryCode": "5967",
"pspId": 35,
"merchantId": 2306,
"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": 2305,
        "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": 2305,
        "dateCreated": "2017-09-20 09:56:59",
        "status": "ACTIVE"
    }