Request formats

The API uses JSON data that is sent over HTTP. Requests are sent either as GET requests or POST requests.

GET Requests

A GET API request contains one JSON object after the API URL. For more information about the variables that are present in the JSON object, see Request variables.

Example GET request:

mybank.com?{"request":"save","uid":-1,"type":"rule","mandator":1033,"revision":1051,"ruleset":1542,"data":{}}

POST Requests

A POST request sets the URL request to ?{"request":"postRequest"}. Then, the full data object is sent in the request body.

Example POST request (for the same request as the previous example GET request):

If the URL is:

mybank.com?{"request":"postRequest"}

The request body is:

{"request":"save","uid":-1,"type":"rule","mandator":1033,"revision":1051,"ruleset":1542,"data":{}}

Request variables

API requests have their own variables that must be passed. For a full list of variables, see the IBM® Safer Payments API Reference Guide.

The first request variable is always present. Whether other variables must be provided depends on the request type. If they are required, they must be provided in the correct sequence, as defined in the API Reference document. If sent out of order, default values for some variables are taken.

The following variables are commonly used. They must be sent in the following sequence:

request: This variable identifies the request type as text value. It must be present.
uid: Many requests reference an IBM Safer Payments element that is identified by a unique identifier (UID). For these requests, the UID is provided with the uid JSON variable. For requests that save settings of an element, the value -1 indicates that the element does not exist and therefore must first be created before it can be saved. In this case, IBM Safer Payments generates a new UID for it. When it is saved, the UID must be repeated in the data object. It must also be -1 when a new element is created.
type: Some requests exist in variants. In this case, the type variable denotes this variant.
mandator: For all requests that target mandator-specific actions, the mandator variable transmits the UID of the respective mandator.
revision: For all requests that target revision-specific actions, the revision variable transmits the UID of the respective revision.
ruleset: For all requests that target ruleset-specific actions, the ruleset variable transmits the UID of the respective ruleset.
data: Many requests, mostly the ones that save an entire element, need to deliver structured data to the IBM Safer Payments server. In this case, the data variable delivers a JSON object with this data. The variables that are present in the data field must follow the sequence that is given in the IBM Safer Payments API Reference Guide. Otherwise, they do not work correctly.

Spaces and other filler characters are not allowed within the quotation marks.