This documentation describes the general procedure when you submit a query to the micropayment API's (NVP protocol) and have to evaluate the response returned.
NVP stands for Name Value Pair
At a number of points reference is made to the Reference of the corresponding API, it is therefore also recommended to open a reference in parallel, e.g. the Credit card API.
Links to the references are in the Technical Documentation.
Users of the micropayment API's who do not want to or cannot use the Service client, as this has PHP as a prerequisite, users of other server-side languages/environments (ASP/ASP.net, Java, Perl, Python, etc.) are the target group of this documentation.
To understand the documentation knowledge of the language/environment you use, as well as basic knowledge of the HTTP protocol, is assumed.
The HTTP 1.0 protocol provides the basis - this means that the queries are carried out via the GET and/or POST methods.
The call syntax is kept relatively simple, whereby the parameter action is assigned a special role:
http(s)://webservices.micropayment.de/path/to/{service}/{version}/nvp/?action={method}¶m1=value1¶mN=valueN
The place holder {service} identifies a collection of functionalities (usually a payment type), that will be expanded with a version number of the API ({version}) , to preserve backward compatibility when a new version is released.
Please find the exact URL or the API to be used in the relevant API reference, in the 'URL of the API' section.
The parameter action identifies the methods (functionality) that will be initiated by the call.
Where the place holder {method} is to be replaced with the desired name from the reference (observe upper/lower case).
You can see which methods are available in the relevant API reference, in the section 'Range of API functions' > 'Methods'.
Naturally all parameters must be encoded. For this use a function of your language, which encodes the parameter according to the MIME type application/x-www-form-urlencoded.
In the parameter lists of the methods in the 'Compulsory' column you get information about whether the parameter must be set (yes) or not (no) If it is not compulsory there is a standard value.
A parameter is considered to be not set, if it is not contained in a QueryString or an HTTP body.
The standard Value [NULL] signals that the standard value corresponds to the Null value and thus is considered to be not set. Please do not confuse [NULL] with the "[NULL]" string!
Some API methods, e.g. "sessionCreate" or "customerCreate" create the possibility of assigning your own freely definable data - for example via the parameter "freeParams").
The data is saved in the form of a data structure, that are called associative arrays or also HashMap.
To communicate this structure the keys (name of the field/properties) are framed in square brackets parameter[Key]=Value.
Your data:
foo=bar
bar=foo
foobar=foobar
Your data in coded form:
&freeParams%5Bfoo%5D=bar
&freeParams%5Bbar%5D=foo
&freeParams%5Bfoobar%5D=foobar
With the return value of an API call this is a semi-structured text.
The structure is kept simple:
field1=value1<line-delimiter>
fieldN=valueN<line-delimiter>
The place holder <line-delimiter> corresponds to the control character \n or Hex \x0A.
As it is possible to assign structured data to objects (e.g. Session/Customer), this data must of course be able to be queried again.
The procedure here resembles the delivery of structured parameters. There are however some differences in the coding that will be explained in more detail later.
Also in the return the key (name of the field/properties) will be framed in square brackets: Field name[Key]=Value
Your data:
foo=bar
bar=foo
foobar=foobar
Data in coded form:
freeParams[foo]=bar
freeParams[bar]=foo
freeParams[foobar]=foobar
Lists represent a special form of structured Return value, as the Key/Index is numerical in this case (unsigned integer).
Field name[<index>]=Value
It should be noted that the Index always starts with 0 and is incremented by 1 with each entry.
For example for "fieldname string[]" with 2 list entries:
fieldname[0]=stringvalue1
fieldname[1]=stringvalue2
There are some special return values/processes which must be mentioned.
For each response an error code is always sent back as the first line:
error=<errorcode>
Here it means that the error code 0 corresponds to no error.
When the error code corresponds to a value not equal to 0, the server puts an additional field in the response with the error text available: errorMessage=<errormessage>
For example for a call to a non-existing function:
error=3002
errorMessage=method+to+invoke+%22not_existing_method%22+not+exists
When functions only have a single return value, like "resetTest" for example, then the name of the return value is result.
Even the return values are encoded (application/x-www-form-urlencoded); however ONLY the values of the fields!
This additional coding is necessary on the grounds of historical growth to correctly transfer the UTF-8 coded data of the credit card API.
The notifications serve to inform you about events, which occur asynchronously with yours along with our API activated communication.
The same syntax is used as with API requests just that the URL invoked is located on your server. The parameter action also has a special role here:
{notification-url}?action={notification}¶m1=value1¶mN=valueN
The parameter action identifies the event that the notification is informing about.
Whereby the place holder {notification} is to be replaced with the desired name from the reference. (observe upper/lower case)
You can see which notifications are sent from the API used in the relevant API reference, in the section 'Range of API functions' > 'Notifications'.
Please configure the URL in the ControlCenter of your account, by going to 'My Configuration' in the main menu and then selecting the 'APIs and permissions' sub-menu available there to reach the list of available APIs.
Select the payment type to be configured as well as the project, to configure them in the framework of the available options to which in any case the 'Notification URL' belongs.
The approach with the notifications corresponds to that of API-Request & API-Response the difference being that the roles of client & server are reversed.
This means put simply, that the micropayment server takes over the role of the client, puts queries to its server, and awaits a response corresponding to the {notification} transmitted.