Management API
QuickStart Guide
13 min
service details the sandbox service can be reached at https //mgmt api torogateway dev the production service will be at mgmt api torogateway com you can test connectivity at https //mgmt api torogateway dev/v1/status openapi/swagger documentation the documentation is served as json at https //mgmt api torogateway dev/v1/docs and via a swagger ui at https //mgmt api torogateway dev/v1/swagger ui these endpoints are protected by basic auth, using the same password as this documentation and user user we recommend having the swagger documentation open while you run through this guide, to get a better idea of the options available to you your account details an account has been created for you the id will be communicated separately an api key has been created with the permissions necessary to create users , api keys and roles the key will be communicated to you separately getting started you will first want to create either a new user or a new api key with broader permissions to create a new api key create a role with appropriate permissions create the api key curl x post https //mgmt api torogateway dev/v1/roles \\ h "content type application/json" \\ h "api key \<key>" \\ d '{ "name" "admin", 	 "description" "full access to everything", 	 "permissions" \[ 	 "account memberships\ create", 	 "account memberships\ delete", 	 "account memberships\ read", 	 "account memberships\ update", 	 "api keys\ create", 	 "api keys\ delete", 	 "api keys\ read", 	 "api keys\ update", 	 "roles\ create", 	 "roles\ delete", 	 "roles\ read", 	 "roles\ update", 	 "users\ create", 	 "users\ delete", 	 "users\ read", 	 "users\ update", 	 "webhook endpoints\ create", 	 "webhook endpoints\ delete", 	 "webhook endpoints\ read", 	 "webhook endpoints\ update", 	 "messages\ read", 	 "receipts\ read", 	 "merchant groups\ create", 	 "merchant groups\ delete", 	 "merchant groups\ read", 	 "merchant groups\ update", 	 "merchants\ create", 	 "merchants\ delete", 	 "merchants\ read", 	 "merchants\ update", 	 "poi groups\ create", 	 "poi groups\ delete", 	 "poi groups\ read", 	 "poi groups\ update", 	 "pois\ create", 	 "pois\ delete", 	 "pois\ read", 	 "pois\ update", 	 "configurations public\ read", 	 "configurations public\ update", 	 "configurations public\ create", 	 "configurations public\ delete" 	 ] }' \# note it's not ideal to have an 'admin' account you can limit \# the scope for problems by having more limited roles; a user can have \# multiple `account memberships` in a single account with different roles, \# giving more granular control over an individual's permissions { "id" "rol new", 	 "name" "admin", "account id" "acc 123abc", "creator id" "apk 54321zyxwv", // the id of the api key or user that created the role "description" "full administrative access to everything", 	 "permissions" \[ 	 "account memberships\ create", 	 "account memberships\ delete", 	 "account memberships\ read", 	 "account memberships\ update", 	 "api keys\ create", 	 "api keys\ delete", 	 "api keys\ read", 	 "api keys\ update", 	 "roles\ create", 	 "roles\ delete", 	 "roles\ read", 	 "roles\ update", 	 "users\ create", 	 "users\ delete", 	 "users\ read", 	 "users\ update", 	 "webhook endpoints\ create", 	 "webhook endpoints\ delete", 	 "webhook endpoints\ read", 	 "webhook endpoints\ update", 	 "messages\ read", 	 "receipts\ read", 	 "merchant groups\ create", 	 "merchant groups\ delete", 	 "merchant groups\ read", 	 "merchant groups\ update", 	 "merchants\ create", 	 "merchants\ delete", 	 "merchants\ read", 	 "merchants\ update", 	 "poi groups\ create", 	 "poi groups\ delete", 	 "poi groups\ read", 	 "poi groups\ update", 	 "pois\ create", 	 "pois\ delete", 	 "pois\ read", 	 "pois\ update", 	 "configurations public\ read", 	 "configurations public\ update", 	 "configurations public\ create", 	 "configurations public\ delete" 	 ], "created at" "2025 01 01t00 00 00", "updated at" "2025 01 01t00 00 00" } curl x post https //mgmt api torogateway dev/v1/api keys \\ h "content type application/json" \\ h "api key \<key>" \\ d '{ "name" "admin test", "description" "api key with admin permissions for testing purposes", "role id" "\<id>", "expires at" "2026 01 01 00 00" }' \# note the date field should be rfc 9557 compliant and not include a \# timezone this may be made more flexible in future { "id" "apik new", "account id" "acc 123abc", "identifier" "1234567890", "last used at" "2025 01 01t00 00z", "created at" "2025 01 01t00 00z", "updated at" "2025 01 01t00 00z", "key" "xyz098abc123" } to create a new user create a user nb email address need to be unique this will return a password, which you should make a note of (a more robust password creation flow will be implemented later, so please don't rely on this for automation) create a role with appropriate permissions (as above) create an account membership linking the user to your account and giving it the new role curl x post https //mgmt api torogateway dev/v1/users \\ h "content type application/json" \\ h "api key \<key>" \\ d '{ "email" "example\@email com", "name" "jane doe", "is active" true }' \# email addresses must be unique { "id" "usr newrandomid", "email" "example\@email com", "name" "jane doe", "is active" true, "created at" "2025 01 01t00 00z", "updated at" "2025 01 01t00 00z", "password" "random password" } \# nb the 'password' property is only being \# returned as a temporary measure, until \# a more robust system can be developed curl x post https //mgmt api torogateway dev/v1/accounts/\ acc id/memberships \\ 	 h "content type application/json" \\ h "api key \<key>" \\ d '{ 	 "user id" "\<id>", 	 "role id" "\<id>" 	}'{ 	"id" "acm new", 	"account id" "acc abc123", 	"user id" "usr 12345abcde", 	"role id" "rol 98765abcde", 	"invitation id" null, 	"creator id" "apik someid", 	"created at" "2023 01 01t00 00 00z", 	"updated at" "2023 01 01t00 00 00z" } you now have full access to the api in order to process transactions, you will need a poi (point of interaction) linked to a merchant merchants and pois to set up an end user to be able to process transactions, we need to have a record of their poi (point of interaction e g card payment terminal or softpos installation) linked to a 'merchant' a merchant represents a single legal entity that has a direct transactional relationship with customers (e g with a fleet of self employed taxi drivers you might have one per driver, but as a chain of supermarkets you might have just one merchant) curl x post https //mgmt api torogateway dev/v1/merchants \\ 	 h "content type application/json" \\ 	 h "api key \<key>" \\ 	 d '{ 	 "legal name" "test merchant", 	 "address" { 	 "account id" \<id>, "line 1" "1 some street", "city" "london" }, 	 "configuration id" \<id>, 	 "merchant group id" null, 	 "is active" true 	}' \# note 1 instead of the `address` parameter you can provide the id of an \# existing address as `address id` { 	"id" "mer new", 	"account id" "acc 123abc", 	"legal name" "test merchant", 	"address id" "addr new", 	"configuration id" null, 	"merchant group id" null, 	"is active" true, } curl x post https //mgmt api torogateway dev/v1/pois \\ 	 h "content type application/json" \\ 	 h "api key \<key>" \\ 	 d '{ 	 "manufacturer id" "\<string>", 	 "label id" "\<string>", 	 "model id" "miura m21", 	 "model version" "test01 v3 4", 	 "merchant id" "\<id>", 	 "configuration id" "\<id>", 	 "poi group id" null, 	 "is active" true 	}' \# note 1 as we need to supply specific details to the acquirer banks, \# and our certifications are model specific, poi `models` need to be set up \# by our team an api endpoint for listing available/supported models \# will be added soon for now please just use the model id and model version \# provided above \# note 2 the `manufacturer id` is the id assigned by the manufacturer, \# most commonly referred to as a serial number it must be the value that \# will be returned by the terminal's firmware when queried (returned by \# getdeviceinfo in our sdk) \# note 3 `label id` can be any string you like, but is intended to be used \# for the id phisically printed on the device (typically on a sticker) \# note 3 the `label id` is simply whatever is written on the physical device \# this field is just for convenience when iding your inventory { 	"id" "poi new", 	"account id" "acc 123abc", 	"manufacturer id" "21100222", 	"label id" "021 100222", 	"model id" "tmp 12345abcde", 	"model version" "test01 v3 4", 	"merchant id" "mer new", 	"configuration id" null, 	"poi group id" null, 	"is active" true, 	"created at" "2025 01 01t00 00 00", 	"updated at" "2025 01 01t00 00 00" } note that we set configuration id to null for both of these in the sandbox environment we've set up account wide default configurations with enough details to get you going at this point you're ready to process transactions! transactions processed on your pois can now be processed, using the manufacturer id field (the id returned by the terminal's firmware) to link them to your account no changes need to be made on the client/sdk side to enable this next steps less privileged users you will probably want to create less privileged users simply create new roles with appropriate permissions for example curl x post https //mgmt api torogateway dev/v1/roles \\ h "content type application/json" \\ h "api key \<key>" \\ d '{ "name" "taxi driver", 	"description" "read only access to finalised transactions", 	"permissions" \[ 	 "receipts\ read" 	] }' a user with this role will have access to their own user details and to the /v1/receipts endpoints, which will return basic details of completed transactions (financially captured or failed) user authentication in out examples we've used an api key, but we also support bearer authentication (which we expect to be more useful for e g end user dashboards) we use the refresh token pattern if you've never worked with this auth0 com has a useful primer ( https //auth0 com/blog/refresh tokens what are they and when to use them/ ) in our system we have three types of token user refresh tokens, which are the long lived refresh token, user access tokens, which are access tokens allowing a user to access and update their own user details but nothing else in the account, and role access tokens which grant access to resources account wide based on the role 's permissions note that user can only access a role they are linked to via an account membership see the relevant section above for how to set this up a user can have many memberships in a single account, so you might for example have an 'accounts' role with access only to transaction history (the receipts\ read permission) and a 'driver support' role with a range of permissions to allow them to create and update merchants and allocate pois to them, and a single user could access either of these roles with the same credentials get transactions finalised transactions can be retrieved at the /v1/receipts endpoint see the swagger documentation for available filters curl x get https //mgmt api torogateway dev/v1/receipts \\ 	 h "content type application/json" \\ 	 h "api key \<key>" merchant and poi groups pois and merchants can be grouped this is useful for two purposes you can filter by group, and you can attach a configuration to a whole group one use case for this is to apply different trading names to different parts of your fleet curl x post https //mgmt api torogateway dev/v1/poi groups \\ 	 h "content type application/json" \\ 	 h "api key \<key>" \\ 	 d '{ 	 "parent group id" null, 	 "configuration id" null 	}' \# note the way configurations work for nested pois/groups is that the child \# overrides the parent e g if you have a poi with config \# `{foo true, bar null}` and it belongs to a poi group with config \# `{foo false, bar false}` the final config will be `{foo true, bar false}`{ "id" "poig new", "account id" "acc 123abc", "parent group id" null, "configuration id" null, "created at" "2025 01 01t00 00z", "updated at" "2025 01 01t00 00z" } curl x post https //mgmt api torogateway dev/v1/poi groups/\ group id/pois \\ 	 h "content type application/json" \\ 	 h "api key \<key>" \\ 	 d '{ 	 "poi id" "\<id>" 	}'{ poi id "poi new", group id "poig 12345abcde" } creating and updating a merchant group works exactly the same nb you can't mix and match groups; merchants and merchant groups can only belong to merchant groups, and pois and poi groups can only belong to poi groups configuration in the sandbox environment we've set up account wide default configurations with enough details to get you going, but to get production ready you'll need to be able to configure pois or parts of your poi estate separately we have a flexible configuration system that lets you set the same configuration options on a poi, merchant, poi group, or merchant group important values include the 'doing business as' name that will be set on transactions, and any acquirer specific configuration there are also configuration options that can only be set by administrators, like whether transactions should be captured with the authorisation request or in a completion message please see the configuration chapter in the documentation for full details
