General description of the NVP protocol

Introduction

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.

Target group

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.

Prerequisites

To understand the documentation knowledge of the language/environment you use, as well as basic knowledge of the HTTP protocol, is assumed.

API request

The HTTP 1.0 protocol provides the basis - this means that the queries are carried out via the GET and/or POST methods.

Syntax

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}​&param1=value1​&paramN=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'.

Coding

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.

Optional parameters

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!

Structured parameters

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.

Example of the "freeParams" parameter

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

API-Response

With the return value of an API call this is a semi-structured text.

General structure

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.

Structured return value

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

Example of the "freeParams" parameter

Your data:

foo=bar
bar=foo
foobar=foobar

Data in coded form:

freeParams[foo]=bar
freeParams[bar]=foo
freeParams[foobar]=foobar

Lists as special form of structured return value

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

Specialities of return values

There are some special return values/processes which must be mentioned.

Error handling

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

Individual return values

When functions only have a single return value, like "resetTest" for example, then the name of the return value is result.

Coding

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.

Notifications

The notifications serve to inform you about events, which occur asynchronously with yours along with our API activated communication.

Syntax

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}​&param1=value1​&paramN=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'.

Configuration of the URL

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.

Requests/Response

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.