Merchant Service


http://webservices.gr8pay.net/v2/Merchant.svc
The merchant service gives you the tools to manage the entire merchant onboarding and management lifecycle.

Register Method

The register method can be used to onboard a potential merchant, and all of the required information about the merchant, onto the system. This method doesn’t create a merchant record immediately. Instead, it stores the record under merchant registrations for further processing.

Request Fields

FieldNameMandatory?Field TypeDescriptionSample
RegistrationDataNoThis block contains data about the merchant
UserNameNoThe username for the merchant - will be used to create the account login.John.Smith
EmailNoStringMerchant's email addressJohn.Smith@home.com
PasswordNoStringThis will be the merchant's password to login to the MCP and services - if not sent a temp password will be create when "Auto-create" merchant if set.Password123!
ParentCompanyNoIntThe ID of the parent company you wish to register the merchant under - this will be taken from the Admin portal - remember you have to set the "Auto-create" merchant to trueACME
AddressNoStringMerchant's juridical address14 Arbour Road
BankAccountNumberNoStringMerchant's bank account number6251234567890
BankRoutingNumberNoStringThe account routing number.78523
BusinessDescriptionNoStringMerchant's business descriptionGroceries
BusinessStartDateNodateTimeDate when the merchant's business was founded25/09/2018
CanceledCheckImageNoBase64BinaryIn some cases registration process require a prof of address or a prof of banking details - use use this field to upload the necessary file.
CityNoStringMerchant's juridical cityJhb
DbaNameNoStringDoing Business As name - Brand nameJohns Groceries
FaxNoStringMerchant's fax number27115551235
FirstNameNoStringMerchant's first nameJohn
IndustryNoIntMerchant's industry. Should be chosen from the provided listFood
LastNameNoStringMerchant's last nameSmith
LegalBusinessNameNoStringMerchant's legal business nameJohns Groceries
LegalBusinessNumberNoStringMerchant's legal business number76543
OwnerDobNodateTimeDate of birth of the company's owner25/09/1990
OwnerSsnNoStringThe business owner personal ID number or Social Security Number.90092512345
PhisicalAddressNoStringMerchant's physical address14 Arbour Road
PhisicalCityNoStringMerchant's physical cityJhb
PhisicalStateNoStringMerchant's physical stateGauteng
PhisicalZipNoStringMerchant's physical postal code2195
PhoneNoStringMerchant's phone number0115551234
StateNoStringMerchant's juridical stateGauteng
StateOfIncorporationNoStringThe state in which the company was incorporated.Gauteng
TypeOfBusinessNoIntMerchant's type of business. Should be chosen from the provided listFood
IndustryDataIDNoStringThe industry the user belongs to, a more general approach then SetPosition which includes all of the Job history for the user.5500
UrlNoStringMerchant's website URLwww.johnsgroceries.biz
ZipcodeNoStringMerchant's juridical postal code2195
UBO1FirstNameNoStringUBO first nameJohn
UBO1LastNameNoStringUBO last nameSmith
UBO1DOBNoDateTimeUBO date of birth25/09/1990
UBO1Address1NoStringUBO address line 114 Arbour Road
UBO1Address2NoStringUBO address line 2
UBO1ZipNoStringUBO address ZIP2195
UBO1CityNoStringUBO address CityJhb
UBO1CountryNoStringUBO address CountrySouth Africa
UBO1PhoneNoStringUBO Phone number0115551234
UBO1PassportIDNoStringUBO Passport or ID90092512345
UBO1SSNNoStringUBO Social Security Number (US)
AnticipatedAverageTransactionAmountNoDecimalAnticipated average transaction amount100
AnticipatedLargestTransactionAmountNoDecimalAnticipated largest transaction amount1500
AnticipatedMonthlyVolumeNoDecimalAnticipated monthly volume15000
PercentDelivery0to7NoIntWhat is the percentage of goods to be delivered to client within 7 days100
PercentDelivery15to30NoIntWhat is the percentage of goods to be delivered to client within 15 to 30 days0
PercentDelivery8to14NoIntWhat is the percentage of goods to be delivered to client within 8 to 14 days0
PercentDeliveryOver30NoIntWhat is the percentage of goods to be delivered to client after more than 30 days.0
M1NumberOfTransactionsNoDecimalNumber of transaction the last month (Count)150
M1TransactionVolumeNoDecimalTotal amount processed the last month150
M1NumberOfChargeBackNoDecimalNumber of Chargebacks the last month (Count)0
M1ChargebackVolumeNoDecimalTotal amount of refunds processed the last month0
M1NumberOfRefundsNoDecimalNumber of Refunds the last month (Count)2
M1RefundVolumeNoDecimalTotal amount of chargebacks processed the last month0
CurrentPreviousProviderNoStringCurrent/Previous PSP or Gateway usedNone
CurrentPreviousAcquirerNoStringCurrent/Previous Acquirer usedNone
ReasonsForLeavingAcquirerNoStringPlease describe the reason for leaving your previous provider.First Provider
OOTDomesticNoDecimalOrigin Of Transaction - Domestic - from the country of the merchantSouth Africa
OOTEuropeNoDecimalOrigin Of Transaction - EuropeN/A
OOTUSANoDecimalOrigin Of Transaction - USAN/A
OOTAsiaNoDecimalOrigin Of Transaction - AsiaN/A
OOTROWNoDecimalOrigin Of Transaction - Rest Of the WorldN/A
TechFirstNameNoDecimalTechnical contact first nameJoe
TechLastNameNoDecimalTechnical contact last nameSmith
TechEmailNoDecimalTechnical contact Email addressjoe@johnsgroceries.biz
TechPhoneNoDecimalTechnical contact Phone number27115551236
FinanceFirstNameNoDecimalFinance contact first nameJen
FinanceLastNameNoDecimalFinance contact last nameSmith
FinanceEmailNoDecimalFinance contact Email addressjen@johnsgroceries.biz
FinancePhoneNoDecimalFinance contact Phone number27115551237
RiskFirstNameNoDecimalRisk contact first nameJeff
RiskLastNameNoDecimalRisk contact last nameSmith
RiskEmailNoDecimalRisk contact Email addressjeff@johnsgroceries.biz
RiskPhoneNoDecimalRisk contact Phone number27115551238

Response Fields

FieldName FieldType Description
This method is void and has an empty response body
C#JavaScriptPHP

AddNewMerchant Method

The AddNewMerchant method registers the Merchant within the gateway. The merchant will be associated with the relevant Partner as specified by the PartnerID.

Request Fields

FieldNameMandatory?Field TypeDescriptionSample
LegalBusinessNameYesstringMerchant Business NameJohns Groceries
PhysicalAddressYesstringMerchant Physical Address14 Arbour Road
FirstNameYesStringContact First NameJohn
LastNameYesStringContact Last NameSmith
PhoneYesStringTelephone Number27115551235
MerchantEmailYesStringMerchant Contact EmailJohn.Smith@johnsgroceries.biz
UrlYesStringMerchant Urlwww.johnsgroceries.biz
CountryIsoCodeYesStringRegistered Business CountryZA
CurrencyIsoCodeYesstringCurrency Code ISO4217*ZAR
PartnerIDYesIntPartner ID Associated with the Merchant12345
C#JavaScriptPHP

UpdateMerchant Method

Update any of the merchants’ details within the system.

Request Fields

FieldName Mandatory?Field TypeDescriptionSample
LegalBusinessNameYesStringMerchant Business NameJohns Groceries
PhysicalAddressYesStringMerchant Physical Address14 Arbour Road
FirstNameYesStringContact First NameJohn
LastNameYesStringContact Last NameSmith
PhoneYesStringTelephone Number27115551235
MerchantEmailYesStringMerchant Contact EmailJohn.Smith@johnsgroceries.biz
UrlYesStringMerchant Urlwww.johnsgroceries.biz
CountryIsoCodeYesStringRegistered Business CountryZA
CurrencyIsoCodeYesstringCurrency Code ISO4217*ZAR
MerchantIDYesIntMerchant ID54321

Response Fields

Field NameField TypeDescription
IsSuccessBooleanDefines whether service call was processed successfully or not
MessageStringResult message
MerchantIDIntMerchant ID
C#JavaScriptPHP

UpdateMerchantStatus Method

This method is used specifically for setting the status of a merchant. Setting the StatusID to Active (30) will return the required Hashkey needed for use on the production environment.

Request Fields

FieldNameMandatory?Field TypeDescriptionSample
MerchantIDYesintMerchant ID54321
StatusIDYesintStatus ID30

Status Table

StatusIDDescriptionAction
1NewRegistered account. Vetting to take place.
10Awaiting ActivationAccount vetting in progress
30ActiveFully operational account.
40InActiveTemporary suspension of processing ability
2BlockedAccount is blocked from transacting
99DeletedAccount to be deleted from the system completely

Response Fields

Field NameField TypeDescription
IsSuccessBooleanTrue means successfully stored
MessagestringMessage description for failed or successful messages
HashkeystringHashkey returned once Merchant Status Set to 30
LiveUrlstringThe URL returned
C#JavaScriptPHP

GetMerchant Method

Returns the stored data for a merchant.

Request Fields

FieldName Mandatory?Field TypeDescriptionSample
LegalBusinessNameYesStringMerchant Business NameJohns Groceries
PhysicalAddressYesStringMerchant Physical Address14 Arbour Road
FirstNameYesStringContact First NameJohn
LastNameYesStringContact Last NameSmith
PhoneYesStringTelephone Number27115551235
MerchantEmailYesStringMerchant Contact EmailJohn.Smith@johnsgroceries.biz
UrlYesStringMerchant Urlwww.johnsgroceries.biz
CountryIsoCodeYesStringRegistered Business CountryZA
CurrencyIsoCodeYesStringCurrency Code ISO4217*ZAR
PartnerIDYesIntPartner ID12345
merchantIDYesIntMerchant ID54321
StatusIDYesIntStatus of the Merchant30

Response Fields

Field NameField TypeDescription
MerchantIDintMerchant ID
StatusIDint*See status table
C#JavaScriptPHP

ListMerchantStatus Method

Returns a list of merchants and their corresponding status for a specified Partner (PartnerID).

Request Fields

ParameterMandatoryTypeDescription
MerchantIDYesintMerchant ID

Response Fields

Field NameField TypeDescription
CodeInteger
IsSuccessBoolean
KeyString
MessageStringSee Return Codes Table*
NumberString
C#JavaScriptPHP