How to use API
The API is comprised of various web resources with associated actions that can be used to interact with the system.
To execute a call within the management API, a user has to be authenticated within the gateway.
After your account is set up, you will receive service user credentials comprised of the username, which starts with "api-", and the password. You have to use these two values for authorization, which can be done via HTTP authentication. To learn more about this method, follow the link. To review examples for HTTP authentication with PHP and Java languages, follow the corresponding links.
Resource URL is a value uniquely identifying a particular resource within an API. Note that actual domain name will differ from the one listed in the documentation and always depends on your specific installation. URL is comprised of two types of sub-components: static and dynamic.
Static subcomponents are used for structural purposes and never change.
Dynamic subcomponents represent variables that must be set with appropriate values to access a specific resource or create one that is to be identified by a specific value. Dynamic subcomponents/variables are shown in square brackets (e.g. [variable-name]).
Actions are functions associated with resources that perform specific operations. Each action is associated with a single HTTP method. Actions are divided into two groups: implicit and explicit.
Implicit actions can be invoked without explicit indication of the action's name. The name is derived from the HTTP method used. Indicating explicitly name of the action for implicit actions has no negative consequences and can be done if desired.
Explicit actions require action name to be explicitly indicated because HTTP method is not sufficient to conclude that this specific action is desired.
To indicate action's name add / after the owning resource URI, followed by ~ identifying the beginning of the action's name, followed by the name of the action.
Example of calling an action called 'find' on the resource called 'merchants':
https://manager.pepgate.com/api/v01/merchants/~find
Dynamic WADL file is available at the following URL:
https://manager.pepgate.com/api.wadl?domain=yourdomain
You can specify the value of the domain and generate the file for this domain.
Example of generating WADL file for a particular domain:
https://manager.pepgate.com/api.wadl?domain=[server-name].com
Each action consumes and produces various content types. The following types are supported:
Consumes (request content type):
Produces (response content type):
Request content type is derived automatically from the request message sent to the server. Response content type can be identified by appending a dot (.) followed by the name of the content type at the end of the request URL.
Example of calling an action called 'find' on the resource called 'merchants', requesting response content to be xml:
https://manager.pepgate.com/api/v01/merchants/~find.xml
When multiple response content types are supported and no preference is indicated by the request, json content type is assumed by default.
Complex Type Parameters
When URL parameter is a complex type, the name of this parameter is derived by concatenation of the original parameters' name and the name of sub-field of the complex type (using dot (.) as a separator).
Authentication
To execute a call within the management API, a user has to be authenticated within the gateway.
After your account is set up, you will receive service user credentials comprised of the username, which starts with "api-", and the password. You have to use these two values for authorization, which can be done via HTTP authentication. To learn more about this method, follow the link. To review examples for HTTP authentication with PHP and Java languages, follow the corresponding links.
Resource URL
Resource URL is a value uniquely identifying a particular resource within an API. Note that actual domain name will differ from the one listed in the documentation and always depends on your specific installation. URL is comprised of two types of sub-components: static and dynamic.
Static subcomponents are used for structural purposes and never change.
Dynamic subcomponents represent variables that must be set with appropriate values to access a specific resource or create one that is to be identified by a specific value. Dynamic subcomponents/variables are shown in square brackets (e.g. [variable-name]).
Actions
Actions are functions associated with resources that perform specific operations. Each action is associated with a single HTTP method. Actions are divided into two groups: implicit and explicit.
Implicit actions can be invoked without explicit indication of the action's name. The name is derived from the HTTP method used. Indicating explicitly name of the action for implicit actions has no negative consequences and can be done if desired.
Explicit actions require action name to be explicitly indicated because HTTP method is not sufficient to conclude that this specific action is desired.
To indicate action's name add / after the owning resource URI, followed by ~ identifying the beginning of the action's name, followed by the name of the action.
Example of calling an action called 'find' on the resource called 'merchants':
https://manager.pepgate.com/api/v01/merchants/~find
WADL
Dynamic WADL file is available at the following URL:
https://manager.pepgate.com/api.wadl?domain=yourdomain
You can specify the value of the domain and generate the file for this domain.
Example of generating WADL file for a particular domain:
https://manager.pepgate.com/api.wadl?domain=[server-name].com
Content Type
Each action consumes and produces various content types. The following types are supported:
Consumes (request content type):
- json - JSON message
- xml - XML message
- query - query string style parameters
- multipart/binary - binary stream within multi-part request
Produces (response content type):
- json - JSON message
- xml - XML message
- query - query string style parameters
- csv - pipe (|) delimited file
- binary - binary stream
Request content type is derived automatically from the request message sent to the server. Response content type can be identified by appending a dot (.) followed by the name of the content type at the end of the request URL.
Example of calling an action called 'find' on the resource called 'merchants', requesting response content to be xml:
https://manager.pepgate.com/api/v01/merchants/~find.xml
When multiple response content types are supported and no preference is indicated by the request, json content type is assumed by default.
Complex Type Parameters
When URL parameter is a complex type, the name of this parameter is derived by concatenation of the original parameters' name and the name of sub-field of the complex type (using dot (.) as a separator).