API Introduction

Versioning

The API version is indicated in the request URL e.g. /v3/payments indicates version 3. All changes made to the API are backwards compatible, hence any major features that are released, that would otherwise break existing implementations, will be released using a new version.

Encoding

• Our system expects data to be sent encoded in UTF-8.
• Using this Content-Type header can help: application/x-www-form-urlencoded; charset=UTF-8

Bearer Token

To make API calls, include the access token in the Authorization header with the Bearer authentication scheme.

Parameter/Header	Description	Format	Required
Authorization Bearer <access-token>	Authorization header with Bearer authentication scheme. Access token can be taken from the backend UI under Administration > Account data > Merchant / Channel Info only if you have specific administration rights.	Header	Required

HTTP Status Codes

For each request you send to our API the HTTP status code of the response will already tell you the basic result.

Status Code	Description
200	successful request
307	temporary redirect
400	bad request. This might either point to e.g. invalid parameters or values sent. It's also returned if the payment failed e.g. because the acquirer declined.
401	invalid authorization header provided
403	invalid access token provided
404	requested resource or endpoint is not found. I.e. endpoint/URL doesn't exist. This can also be caused by typos like POST /v3/payments instead of payments or wrong IDs like GET /v3/payments/{id} where no payment with {id} exists.

Notifications

Async notifications occur to notify you of a change in status of a payment. That change in status may happen for various reasons, often depending on the brand. For example, an offline invoice payment has been fulfilled or a risk transaction has moved from REVIEW status to ACCEPT. Async notifications can occur while using server-to-server API or checkout page API.

Notification is optional and you should contact your customer support if you needed. The notification message is the same as the response of Inquiry API.

Parameters

	Required	Format	Description
notificationUrl	Optional	AN2048 [\s\S]{6,2048}	This URL will receive the result of an asynchronous payment. Must be sent URL encoded.
shopperResultUrl	Conditional	AN2048 [\s\S]{6,2048}	This URL will receive the result of an asynchronous payment. Must be sent URL encoded.

Result Codes

The result codes are part of the response body containing a code and a description explaining the code.

A result code has the format ddd.ddd.ddd, i.e. 3 groups of 3-digit numbers. The codes are split into rough groups by the first number, then into more detailed sub-groups by the second number, then into the exact code by the third number.

Examples

• 800.100.153 means:
  • 800 Bank declined
  • 100 it declined the authorization
  • 153 it declined authorization because the CVV is wrong
• 000.000.000 represents transaction is succeeded.