Technical Reference

General

PayEx' eCommerce platform is built using the REST architectural style and the request and responses come in the JSON format. The API has predictable, resource-oriented URIs and use default HTTP features, like HTTP authentication (using OAuth2), HTTP methods and headers. These techniques are widely used and understood by most HTTP client libraries.

Common eCommerce Resources

Consumers and Payment Orders are the two fundamental resources that Checkin and Payment Menu build upon. Use Checkin and Payment Menu together to get PayEx Checkout.  

Core Payment Resources

Explore our Core Payment Resources and payment instruments (Card, Direct Debit, Invoice, MobilePay, Swish, Vipps). 

Please make sure to not POST sensitive personal information in parameters, where it is not expected - e.g. in payment.description, paymentorder.metadata, payeeInfo.orderReference.

This applies to all free text parameters where you, the merchant, POST data that will not be automatically masked by PayEx.


Connection and Protocol

All requests towards PayEx' REST API platform are made with HTTP/1.1 over a secure a TLS 1.1 (or higher) connection. Older HTTP clients running on older operating systems and frameworks might receive connection errors when connecting to PayEx' APIs. This is most likely due to the connection being made from the client with TLS 1.0 or even SSL, which are all insecure and deprecated. If such is the case, ensure that you are able to connect over a TLS 1.1 connection by reading information regarding your programming languages and environments (Java, PHP Curl, PHP Zend, Ruby, Python, Node.js Request).

You can inspect PayEx' TLS and cipher suite support at SSL Labs. Support for HTTP/2 in our APIs is being investigated.

Headers

All requests against the eCommerce API should have a few common headers:

POST /some/resource HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: "Bearer 123456781234123412341234567890AB"
Session-Id: 779da454399742248f2942bb064c4707
Forwarded: for=82.115.151.177; host=example.com; proto=https
HeaderRequiredDescription
Content-TypeYThe content type of the body of the HTTP request. Usually set to application/json.
AcceptYThe content type accepted by the client. Usually set to application/json.
AuthorizationYThe OAuth 2 Access Token is generated in PayEx Admin. See the admin guide on how to get started.
Session-IdNA trace identifier used to trace calls through the PayEx systems (ref RFC 7329). Each request must mint a new GUID/UUID. If no Session-Id is provided, PayEx will generate one.
ForwardedNThe IP address of the consumer as well as the host and protocol of the consumer-facing web page. When the header is present, only the for parameter containing the consumer IP address is required, the other parameters are optional. See RFC 7239 for details.

URI usage

The base URIs of the eCommerce APIs are:

An important part of REST is its use of hypermedia. Instead of having to perform complex state management and hard coding URIs and operations in the client, this task is moved to the server. The client simply follows links and performs operations provided by the API, given the current state of the resource. The server controls the state and lets the client know through hypermedia what's possible in the current state of the resource. To get an introduction to hypermedia, please watch this 20 minute video.

What to avoid

It is very important that only the base URIs of PayEx' APIs are stored in your system. All other URIs are returned dynamically in the response. PayEx cannot guarantee that your implementation will remain working if you store any other URIs in your system. When performing requests, please make sure to use the complete URIs that are returned in the response. Do not attempt to parse or build upon the returned data - you should not put any special significance to the information you might glean from an URI. URIs should be treated as identifiers you can use to retrieve the identified resource – nothing more, nothing less. If you don't follow this advice, your integration most assuredly will break when PayEx makes updates in the future. 

POST and PATCH requests and responses

When a POST or PATCH request is performed the whole target resource representation is returned in the response, as when performing a GET request after the initial request. This is an economic approach that limits the number of necessary GET requests. 

Expansion

The payment resource contain the ID of related sub-resources in its response properties. These sub-resources can be expanded inline by using the request parameter expand. This is an effective way to limit the number of necessary calls to the API, as you return several properties related to a Payment resource in a single request.

Note that the expand parameter is available to all API requests but only applies to the request response. This means that you can use the expand parameter on a POST  or PATCHrequest to get a response containing the target resource including expanded properties.

This example below add the urls and authorizations property inlines to the response, enabling you to access information from these sub-resources.

Expansion
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c?$expand=urls,authorizations HTTP/1.1
Host: api.payex.com

To avoid unnecessary overhead, you should only expand the nodes you need info about.

Data Types

Some datatypes, like currency, dates and amounts, are managed in a coherent manner across all eCom APIs

Currency

All currencies are expressed accoring to the ISO 4217 standard, e.g SEK, EUR, NOK

Dates

All dates are expressed according to the ISO 8601 standard that combine dates, time and timezone, e.g. 2018-09-14T13:21:57.6627579Z.

Locale

When defining locale, we use the combination of language (ISO 639-1) and country codes (ISO 3166), e.g. nb-NO, sv-SE, en-US.

Monetary amounts

All monetary amounts are entered in the lowest momentary units of the selected currency. The amount of SEK and NOK are in ören/ører, and EUR is in cents.  E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK, 1000 = 10 EUR.

Operations

When a payment resource is created and during its lifetime, it will have a set of operations that can be performed on it. Which operations that are available in a given state varies depending on payment instrument used, what the access token is authorized to do, etc. A subset of possible operations are described below. Visit the technical reference page of a payment instrument for instrument specific operations. 

{
   "payment": {},
   "operations": [
        {
           "href": "http://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "rel": "update-payment-abort",
           "method": "PATCH"
        },
        {
           "href": "https://ecom.externalintegration.payex.com/creditcard/payments/authorize/123456123412341234123456789012",
           "rel": "redirect-authorization",
           "method": "GET"
        },
        {
           "href": "https://ecom.externalintegration.payex.com/swish/core/scripts/client/px.swish.client.js?token=cfb9e24832d56fec7ab79709f56accc53d79a699756687d39095b517bc5f011b",
           "rel": "view-payment",
           "method": "GET",
           "contentType": "application/javascript"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures",
           "rel": "create-capture",
           "method": "POST"
        }
    ]
}

Properties

PropertyDescription
hrefThe target URI to perform the operation against.
relThe name of the relation the operation has to the current resource.
methodThe HTTP method to use when performing the operation.

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only constants is the rel and method as href composition is the relative identifer of a payment URI.

PayeeReference

The payeeReference given when creating transactions and payments has some specific processing rules depending on specifications in the contract.

  1. It must be unique for every operation, used to ensure exactly-once delivery of a transactional operation from the merchant system.
  2. Its length and content validation is dependent on whether the transaction.number or the payeeReference is sent to the acquirer.
    1. If you select Option A in the settlement process (PayEx will handle the settlement), PayEx will send the transaction.number to the acquirer and the payeeReference may have the format of string(30).
    2. If you select Option B in the settlement process (you will handle the settlement yourself), PayEx will send the payeeReference to the acquirer and it will be limited to the format of string(12) and all characters must be digits.

Read more about the settlement process here.

Abort

To abort a payment, perform the update-payment-abort operation that is returned in the payment request. You need to include the following HTTP body:

Request
PATCH /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
 "payment": {
   "operation": "Abort",
   "abortReason": "CancelledByConsumer"
  }
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": {
       "id": "/psp/creditcard/payments/e73da1da-1148-476c-b6bb-08d67623d21b",
       "number": 70100130293,
       "created": "2019-01-09T13:11:28.371179Z",
       "updated": "2019-01-09T13:11:46.5949967Z",
       "instrument": "CreditCard",
       "operation": "Purchase",
       "intent": "AutoCapture",
       "state": "Aborted",
       "currency": "DKK",
       "prices": {
           "id": "/psp/creditcard/payments/e73da1da-1148-476c-b6bb-08d67623d21b/prices"
        },
       "amount": 0,
       "description": "creditcard Test",
       "payerReference": "100500",
       "initiatingSystemUserAgent": "PostmanRuntime/7.1.1",
       "userAgent": "Mozilla/5.0",
       "language": "nb-NO",
       "urls": {
           "id": "/psp/creditcard/payments/e73da1da-1148-476c-b6bb-08d67623d21b/urls"
        },
       "payeeInfo": {
           "id": "/psp/creditcard/payments/e73da1da-1148-476c-b6bb-08d67623d21b/payeeinfo"
        },
       "metadata": {
           "id": "/psp/creditcard/payments/e73da1da-1148-476c-b6bb-08d67623d21b/metadata"
        }
    },
   "operations": []
}

The response will be the payment resource with its state set to Aborted.

Callback

The Callback  functionality is similar for all payment methods.

  • Setting a callbackUrl in the HTTP POST API is optional, but highly recommended. If a payer closes the browser window, a network error or something else happens that prevents the payer from being redirect from PayEx back to the merchant website, the callback is what ensures that you receive information about what happened with the payment.
  • When a change or update from the back-end system are made on a payment or transaction, PayEx will perform a callback to inform the payee (merchant) about this update.
  • PayEx will make an HTTP POST to the callbackUrl that was specified when the payee (merchant) created the payment.
  • When the callbackUrl receives such a callback, an HTTP GET request must be made on the payment or on the transaction. The retrieved payment or transaction resource will give you the necessary information about the recent change/update.
  • The callback will be retried if it fails. Below are the retry timings, in milliseconds from the initial transaction time:
    1. 30000 ms
    2. 60000 ms
    3. 360000 ms
    4. 432000 ms
    5. 864000 ms
    6. 1265464 ms
  • The callback is sent from the following IP addresses:
    • 82.115.146.1

Payment Instrument Callback

{
  "payment": {
      "id": "/psp/<payment instrument>/payments/22222222-2222-2222-2222-222222222222",
      "number": 222222222
    },
  "transaction": {
      "id": "/psp/<payment instrument>/payments/22222222-2222-2222-2222-222222222222/<transaction type>/33333333-3333-3333-3333-333333333333",
      "number": 333333333
    }
}

Payment Order Callback

{
   "paymentOrder":{
       "id": "/psp/paymentorders/11111111-1111-1111-1111-111111111111",
       "instrument": "<payment instrument>"
    },
   "payment":{
       "id": "/psp/<payment instrument>/payments/22222222-2222-2222-2222-222222222222",
       "number": 222222222
    },
   "transaction":{
       "id": "/psp/<payment instrument>/payments/22222222-2222-2222-2222-222222222222/<transaction type>/33333333-3333-3333-3333-333333333333",
       "number": 333333333
    }
}
ParameterDescription
Payment InstrumentCreditCard, Invoice, Swish, Vipps, DirectDebit, MobilePay
Transaction TypeAuthorizations, Captures, Cancellations, Reversals

The sequence diagram below shows the HTTP POST you will receive from PayEx, and the two GET requests that you make to get the updated status.

Problems

When performing operations against the API, it will respond with a problem message that contain details of the error type if the request could not be successfully performed. Regardless of why the error occurred, the problem message will follow the same structure as specified in the Problem Details for HTTP APIs (RFC 7807) specification.

The structure of a problem message will look like this:

{
   "type": "https://api.payex.com/psp/<error_type>",
   "title": "There was an input error",
   "detail": "Please correct the errors and retry the request",
   "instance": "9a20d737-670d-42bf-9a9a-d36736de8721",
   "status": 400,
   "action": "RetryNewData",
   "problems": [{
       "name": "CreditCardParameters.Issuer",
       "description": "minimum one issuer must be enabled "
    }]
}

Properties

ParameterData typeDescription
typestringThe URI that identifies the error type. This is the only property usable for programmatic identification of the type of error! When dereferenced, it might lead you to a human readable description of the error and how it can be recovered from.
titlestringThe title contains a human readable description of the error.
detailstringA detailed, human readable description of the error.
instancestringThe identifier of the error instance. This might be of use to PayEx support personnel in order to find the exact error and the context it occurred in.
statusintegerThe HTTP status code that the problem was served with.
actionstringThe action indicates how the error can be recovered from.
problemsarrayThe array of problem detail objects.
problems[].namestringThe name of the property, header, object, entity or likewise that was erroneous.
problems[].descriptionstringThe description of what was wrong with the property, header, object, entity or likewise identified by name.

Common Problems

All common problem types will have a URI in the format https://api.payex.com/psp/<error-type>. The URI is an identifier and is currently not possible to dereference, although that might be possible in the future.

TypeStatusNotes
inputerror400The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax, size to large, invalid request).
forbidden403The request was valid, but the server is refusing the action. The necessary permissions to access the resource might be lacking.
notfound404The requested resource could not be found, but may be available in the future. Subsequent requests are permissible.
systemerror500A generic error message.
configurationerror500A error relating to configuration issues.

Payment Instrument Specific Problems

Problem types for a specific payment instrument will have a URI in the format https://api.payex.com/psp/<payment-instrument>/<error-type>. You can read more about the payment instrument specific problem messages below:

Created by Asbjørn Ulsberg on 2018/03/06 12:54