Merchant Management

Guides for creating and managing merchants (clients) via the REST API.

Creating a Merchant (Client)

Endpoint

POST /api/v1/merchant/create

Note

This endpoint is intended for Acquirers and Payment Service Providers (PSPs) with permissions to onboard new merchants.

Merchant Request Body

Field Name	Type	Mandatory	Description
`Name`	String	Yes	Merchant name
`Phone`	String	Yes	Phone (e.g., +27821234567)
`FInstID`	Integer	Yes	Financial institution ID
`AddressDeFacto`	String	Yes	Actual address
`ClientManager`	JsonObject	Yes	Client Manager object
`UserName`	String	Yes	Manager's name
`UserEmail`	String	Yes	Manager's email
`UserPhone`	String	Yes	Manager's phone number
`Location`	JsonObject	Yes	Location object
`Latitude`	Integer	Yes	Latitude
`Longitude`	Integer	Yes	Longitude
`Country`	String	Yes	Country
`CountryCode`	String	Yes	Country code
`DeviceInfo`	JsonObject	Yes	Device object
`PhoneManufacturer`	String	Yes	Manufacturer
`PhoneModel`	String	Yes	Model
`DeviceID`	String	Yes	Device ID
`DeviceType`	String	Yes	Device type
`AppFramework`	String	Yes	Application framework
`OS`	String	Yes	Operating system
`OSVersion`	String	Yes	System version
`AppID`	String	Yes	Application ID
`BuildNumber`	String	Yes	Build number
`GMT`	Integer	Yes	Time zone
`AppFramework`	String	Yes	Framework applications
`IP`	String	Yes	IP address from where the request is made
`Lang`	String	Yes	Language
`AddressDeJure`	String	No	Legal Address
`Description`	String	No	Brief description
`Web`	String	No	Web site
`State`	Integer	No	Status (0 - blocked, 1 active)
`SendWelcomeEmail`	Boolean	No	Send a welcome invitation
`ClientSource`	String	No	Client source or channel
`TaxSystemID`	Integer	No	Tax System ID
`SupportCuratorID`	Integer	No	Support curator ID
`HunterID`	Integer	No	Sales agent ID
`TaxID`	String	No	Tax ID (e.g. VAT number)
`OriginCuratorID`	Integer	No	Primary curator ID
`CashRegisterCuratorID`	Integer	No	Cash solution curator
`ProductSolutionID`	Integer	No	Product solution type
`ContractTypeID`	Integer	No	Contract type ID
`ClientMode`	Integer	No	Client mode
`MobileSettings`	JsonObject	No	Mobile settings object
`ClientImportance`	Integer	No	Importance of the merchant
`ClientType`	Integer	No	Merchant type
`ImageAvatar`	JsonObject	No	Client logo/avatar
`Sbp`	JsonObject	No	SBP Settings object
`CurrentAccountID`	Integer	No	ID of the user making the request

Value Dictionaries

ClientType

Type	Description
`1`	Common
`2`	WE
`4`	MultiMerchant

ClientMode

Type	Description
`1`	Normal
`2`	Third Party

ClientImportance

Type	Description
`10`	Normal
`100`	Important
`500`	Budget-forming

Configuration IDs

ProductSolutionID, ContractTypeID and TaxSystemID values are provided by your account manager.

Example: Create Merchant Request

{
  "Name": "Cycle Demo Pty Ltd",
  "Phone": "+27821234567",
  "FInstID": 3012,
  "AddressDeFacto": "123 Sample Street, Sandton, 2196",
  "AddressDeJure": "123 Sample Street, Sandton, 2196",
  "Description": "Retail Goods",
  "Web": "https://cycledemo.co.za/",
  "State": 1,
  "SendWelcomeEmail": true,
  "TaxSystemID": 1,
  "TaxID": "4123456789",
  "ProductSolutionID": 0,
  "ContractTypeID": 3,
  "ClientMode": 2,
  "ClientImportance": 10,
  "ClientType": 2,
  "MobileSettings": {
    "Features": {
      "AcceptCards": true,
      "AcceptCash": true,
      "AcceptPrepaid": true,
      "AcceptCredit": true,
      "AcceptOuterCard": true,
      "ShowInventory": true,
      "RegularPayments": true,
      "Offline": true,
      "AsyncCashProcessing": true,
      "InternalUpdate": true,
      "AutoLogin": true,
      "Inherited": true,
      "ChangeClientLogo": true
    },
    "MobHomeURL": "https://cycledemo.co.za/home",
    "MobHomeURLNull": false,
    "MobQRUrlNull": true,
    "AllowLinkedCards": 1,
    "BoxplatPayDashboard": false,
    "BoxplatPayDashboardNull": true,
    "AllowCreditVoucherReverses": 0,
    "MobileAppPasswordStore": true,
    "BarcodeScanner": true,
    "BarcodeScannerNull": true
  },
  "ClientManager": {
    "UserName": "Admin User",
    "UserEmail": "admin@cycledemo.co.za",
    "UserPhone": "+27821234568"
  },
  "CurrentAccountID": 21041,
  "Location": {
    "Latitude": -26.1076,
    "Longitude": 28.0567
  },
  "Country": "South Africa",
  "CountryCode": "ZA",
  "DeviceInfo": {
    "PhoneManufacturer": "Generic",
    "PhoneModel": "Windows_RestAPI",
    "DeviceID": "",
    "DeviceType": "1",
    "AppFramework": "java",
    "OS": "Windows",
    "OSVersion": "10",
    "AppID": "RestAPI",
    "BuildNumber": "2.4.390248"
  },
  "GMT": 2,
  "AppFramework": "java",
  "Lang": "en",
  "IP": "102.132.95.88"
}

Merchant Response Body

Field Name	Type	Description
`Merchant`	object	Merchant object
`ID`	Integer	The merchant ID
`State`	Integer	Status (0 - blocked, 1 active)
`FInstID`	Integer	Financial institution ID
`Name`	String	Merchant name
`LegalName`	String	Legal name of the merchant
`Email`	String	Email
`Phone`	String	Telephone
`Description`	String	Brief description
`Avatar`	Boolean	Indicates if avatar is present
`AddressDeJure`	String	Legal address
`AddressDeFacto`	String	Actual address
`ClientName`	String	Client name (can differ from merchant name)
`AvatarUrl`	String	Image link
`HasAvatar`	Boolean	Indicates if an avatar exists
`ProductDescCount`	Integer	Number of products
`ProductDescActiveCount`	Integer	Number of active products
`Deleted`	Boolean	Indicates if deleted
`FInstName`	String	Financial institution name
`ClientImportance`	Integer	Importance of the merchant
`Sbp`	JsonObject	SBP Settings
`ErrorCode`	Integer	Execution result code
`ErrorMessage`	String	Execution result message

Example: Create Merchant Response

{
  "Merchant": {
    "ID": 26991,
    "State": 1,
    "AccountTypeID": 10,
    "AccountType": 10,
    "ClientID": 26991,
    "BranchID": 3012,
    "FInstID": 3012,
    "Name": "Cycle Demo Pty Ltd",
    "LegalName": null,
    "Email": null,
    "Web": "https://cycledemo.co.za/",
    "TerminalID": null,
    "CurrencyID": "ZAR",
    "LanguageID": "en",
    "CountryID": "ZA",
    "Phone": "+27(82)123-45-67",
    "Description": "Retail Goods",
    "Avatar": false,
    "AddressDeJure": "123 Sample Street, Sandton, 2196",
    "AddressDeFacto": "123 Sample Street, Sandton, 2196",
    "ClientName": null,
    "AvatarUrl": "/i/x.png",
    "HasAvatar": false,
    "ProductDescCount": 0,
    "ProductDescActiveCount": 0,
    "ProductDescActiveAcceptPaymentCount": 0,
    "ProductDescActiveScheduleCount": 0,
    "Deleted": false,
    "FInstName": "Demo Finst",
    "ReceiptSkipHeader": false,
    "ClientImportance": 10
  },
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": null
}

Editing a Merchant (Client)

Endpoint

POST /api/v1/merchant/{merchantId}/update

Edit Merchant Request Body

Field Name	Type	Mandatory	Description
`Name`	String	Yes	Merchant name
`Phone`	String	Yes	Phone (e.g., +27821234567)
`AddressDeFacto`	String	Yes	Actual address
`AddressDeJure`	String	No	Legal Address
`Description`	String	No	Brief description
`Web`	String	No	Web site
`State`	Integer	No	Status (0 - blocked, 1 active)
`ClientSource`	String	No	Receipt channel
`TaxSystemID`	Integer	No	Tax System ID
`SupportCuratorID`	Integer	No	Curator in support
`OriginCuratorID`	Integer	No	Primary curator
`CashRegisterCuratorID`	Integer	No	Cash solution/application
`ProductSolutionID`	Integer	No	Solution
`ContractTypeID`	Integer	No	Customer type
`ClientMode`	Integer	No	Client mode
`ClientImportance`	Integer	No	Importance of the customer
`BarcodeScanner`	Boolean	No	Scanner barcode
`Image`	JsonObject	No	Client logo
`CurrentAccountID`	Integer	No	ID of the user making the request
`Location`	JsonObject	Yes	Location object
`Country`	String	Yes	Country
`CountryCode`	String	Yes	Country code
`DeviceInfo`	JsonObject	Yes	Device object
`GMT`	Integer	Yes	Time zone
`AppFramework`	String	Yes	Framework applications
`IP`	String	Yes	IP address from where the request is made
`Lang`	String	Yes	Language

Example: Edit Merchant Request

{
  "ID": "18349",
  "Name": "Jabu's Innovations Pty Ltd",
  "Phone": "+27111111111",
  "AddressDeFacto": "456 Sample Ave, Pretoria, 0002",
  "AddressDeJure": "789 Main Road, Cape Town, 8001",
  "Web": "jabu-innovations.co.za",
  "BarcodeScanner": false,
  "MobileSettings": {
    "AllowLinkedCards": 0
  },
  "Location": {
    "Latitude": -25.7479,
    "Longitude": 28.2293
  },
  "Country": "South Africa",
  "CountryCode": "ZA",
  "DeviceInfo": {
    "PhoneManufacturer": "Generic",
    "PhoneModel": "Windows_RestAPI",
    "DeviceID": "",
    "DeviceType": "1",
    "AppFramework": "java",
    "OS": "Windows",
    "OSVersion": "10",
    "AppID": "RestAPI",
    "BuildNumber": "2.4.390248"
  },
  "GMT": 2,
  "AppFramework": "java",
  "Lang": "en",
  "IP": "102.132.95.88"
}

Edit Merchant Response Body

Field Name	Type	Description
`Merchant`	object	Merchant object
`ID`	Integer	The merchant ID
`State`	Integer	Status (0 - blocked, 1 active)
`FInstID`	Integer	Financial institution ID
`Name`	String	Merchant name
`LegalName`	String	Legal name of the merchant
`Email`	String	Email
`Phone`	String	Telephone
`Description`	String	Brief description
`Avatar`	Boolean	Indicates if avatar is present
`AddressDeJure`	String	Legal address
`AddressDeFacto`	String	Actual address
`ClientName`	String	Client name (can differ from merchant name)
`AvatarUrl`	String	Image link
`HasAvatar`	Boolean	Indicates if an avatar exists
`ProductDescCount`	Integer	Number of products
`ProductDescActiveCount`	Integer	Number of active products
`Deleted`	Boolean	Indicates if deleted
`FInstName`	String	Financial institution name
`ClientImportance`	Integer	Importance of the merchant
`Sbp`	JsonObject	SBP Settings
`ErrorCode`	Integer	Execution result code
`ErrorMessage`	String	Execution result message

Example: Edit Merchant Response

{
  "Merchant": {
    "ID": 18349,
    "State": 1,
    "AccountTypeID": 10,
    "AccountType": 10,
    "ClientID": 18349,
    "BranchID": 3012,
    "FInstID": 3012,
    "Name": "Jabu's Innovations Pty Ltd",
    "LegalName": "Jabu's Innovations (Pty) Ltd",
    "Email": null,
    "Web": "jabu-innovations.co.za",
    "TerminalID": null,
    "CurrencyID": "ZAR",
    "LanguageID": "en",
    "CountryID": "ZA",
    "Phone": "+27(11)111-1111",
    "Description": "",
    "Avatar": false,
    "AddressDeJure": "789 Main Road, Cape Town, 8001",
    "AddressDeFacto": "456 Sample Ave, Pretoria, 0002",
    "ClientName": null,
    "AvatarUrl": "https://static-demo.cardport.net/item.aspx?ft=user&fid=3012&cid=18349&aid=18349&uft=avatar&stamp=2020-09-04T08%3a15%3a34.87&",
    "HasAvatar": true,
    "ProductDescCount": 5,
    "ProductDescActiveCount": 0,
    "ProductDescActiveAcceptPaymentCount": 0,
    "ProductDescActiveScheduleCount": 0,
    "Deleted": false,
    "FInstName": "Demo Finst",
    "ReceiptSkipHeader": false,
    "ClientImportance": 10
  },
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": null
}

Reference

Agents