This call is used to retrieve a list of all the clients in the MYGW-CM database for a specific merchant. URLs: Test https://api.test.oneroadpayments.com/merchants/{merchantID}/clients?next={next client} Production https://api.oneroadpayments.com/merchants/{merchantID}/clients?next={next client} Request Method: GET Headers: The header ‘x-api-key’ should be set to the value of the Merchant API Key allocated to the merchant or PSP at sign up. URL Parameters: Name | Description | R/M/O | merchantID | The unique merchant ID provided by the PSP or allocated by the MYGW system | M | next | The client ID of the client to start downloading the client list from | O |
Client Body - List Clients Request NA – No client body data required. The list clients request should be sent to the MYGW server using the GET method. Client Body - List Clients Response The MYGW server will respond including a status code, signifying whether the call succeeded, as described above - MYGW API Responses. An example of the JSON object sent in a response to a successful list clients request is as follows. { "response": { "statusCode":200,"message":"OK" }, "clients":[ { "merchantID":"1234abcd-5678-efgh-9012-123456abcdef", "merchantName":"The Merchant", "mobileNumber":"222333444555", "clientID":"TheClient_1", "created":"2023-11-06T06:46:53.953", "updated":"2024-07-14T08:18:22.747", "name":"First Client", "id":"16639678-2c4f-481b-bda6-3144cf9ae8fb", "emailAddress":"client_1@client1.com", "black":false, "valid":true, "correlatedBlack":false }, { "merchantID":"1234abcd-5678-efgh-9012-123456abcdef", "merchantName":"The Merchant", "mobileNumber":"666777888", "clientID":"TheClient_2", "created":"2023-11-06T08:06:26.065", "updated":"2024-07-14T06:51:57.540", "name":"Second Client", "id":"826f55b0-4f7d-4700-b53c-b616bceef3f6", "emailAddress":"client_2@client2.com", "black":false, "valid":true, "correlatedBlack":false }, { // A record in the clients array for each client stored for this merchant .......... } ], “next”: “nextClientID” } A successful response will include in the response JSON object a list of every client stored at the server for the merchant. Each client object will include all the information stored at the server for that client, in the format described above – The JSON Client Object. However, the individual client information will not necessarily include a complete client object, only fields that were included when the client was created or updated on the system. If some of those fields (such as cards or billingAddress) are not set, they will not be returned from the host. If the next element is included in the response, it signifies that there are clients which have still not been loaded, most probably because the client list is too long to send in a single response. The next element contains the client ID of the first client in the remainder of the list. To retrieve the rest of the client list, the list clients API request should be called again, with the URL parameter ‘next’ set to the next client ID. To retrieve the entire list, this should be done repeatedly until the next parameter in the returned JSON object is not included. An example of the JSON object sent in a response to an unsuccessful create client request is as follows. { "response": { "statusCode": 400, "message": "Bad Request", "detail": "Invalid Merchant ID" } }
The status code and status message returned could be one of the following values.
Status Code | Description | Status Message | 200 | The client list was successfully loaded from the server | Message - OK | 400 | The merchant ID was invalid or not recognised, and the request failed | Message - Bad Request Detail – Invalid Merchant ID | 403 | The merchant API key could not be validated, and the request failed | Message - Forbidden | 500 | A server error occurred, and the request failed | Message – Internal processing exception |
List Clients - Sample Source Code An example of executable JavaScript sample source code to list a merchant’s clients can be found by clicking on the icon below. Note that this is an example of how a list clients request can be initiated, it is a not a recommendation for how to implement the client APIs in your own applications. .png)
| 
