NAV
curl PHP

Introduction

OnPay supports a REST API, the data format is JSON.

Additional fields may be returned in the future, so any implementation should be able to handle this.

We recommend using the Uuid of single items for identification, though other fields are supported at some endpoints.

Minor units

Minor units mentioned with amounts throughout the API, is an integer representation of a float value. Minor units is based on the exponent of the currency. For most currencies the exponent is 2, however sometimes more or less. Please refer to the ISO4217 definition for the currency in question.

Minor units are calculated by multiplying the amount by the result of 10 to the power of the exponent.

120.00 * (10^2)

120.00 DKK becomes 12000

Timestamps

All Datetime values in the API are according to the timezone UTC ± 00:00. Datetime values are not adjusted by any DST conventions.

Authentication

OAUTH2

It is not necessary to register clients prior to usage, the client id should be set to the domain name of the integration owner.

OnPay only supports the Authorization Code and Refresh token flow of the OAUTH2 protocol.

It is recommended to use a existing library implementing the OAUTH2 protocol.

When using the authorization code flow, after successful authorization an access token and refresh token will be returned. It is then possible to issue a new access token, when it expires based on the refresh token.

Parameter Value Notes
client_id example.com Should be set to the domain of the integration owner.
authorize_url https://manage.onpay.io/{gateway_id}/oauth2/authorize Replace the {gateway_id} with the id of the gateway access is wanted for
access_url https://api.onpay.io/oauth2/access_token The endpoint to get token for auth code
scope full Only the value "full" is supported for now
resource_owner_details https://api.onpay.io/oauth2/resource_owner Will return information about the current gateway

API tokens

From OnPay management panel it is possible to create API tokens for use with the API.

To create a new API token in the management panel, go to: Settings > API, then press the 'New API token' button, enter a name for the API token and lastly press the 'Create' button.

Now a API token will be genereated and be ready for copying to a safe location. Please make sure to keep this API token a secret, since it allows full API access to the gateway that it's created for.

Using the API token

  curl --location --request GET 'https://api.onpay.io/v1/gateway/information' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImQxNDgzMDEyZTFkNDM2OThhYTgxODYxZjVmMGNhNDllMjdlNjY2OTIzNDlkYTU0YzQ0MTUyNGZlMjY4ZmI5MmNkMmM5NTA4ZDdlMzZiYjE4In0.eyJhdWQiOiJFbWlscyBUb2tlbiIsImp0aSI6ImQxNDgzMDEyZTFkNDM2OThhYTgxODYxZjVmMGNhNDllMjdlNjY2OTIzNDlkYTU0YzQ0MTUyNGZlMjY4ZmI5MmNkMmM5NTA4ZDdlMzZiYjE4IiwiaWF0IjoxNjA1MTkyMzk1LCJuYmYiOjE2MDUxOTIzOTUsImV4cCI6DjE0NzQ4MzY0Nywic3ViIjoiMjc4NTk5NDI3ODUzODA5Iiwic2NvcGVzIjpbImZ1bGwiXX0.c9z5oCqvwYkRfzrxWNlF0Hen3gSznptOjb7f3aOlbnEoryos7gNk8FnU96KDkBvSTgJVpMMcj51G-zgaWaRz2jCOFCk6iJGKfg2Qx-jNZP3JpaDECch4lzK4ka-y8aOi2WdB9xFMUMSccblVWHkbhBHzLn9HfDa_-rzT-gMDFdSkspkkroAbpWhTdkspdMEdkUmTlrLxLhqRcMguo2oKTq3MXjSpVIviHYs0ckJMcbKBI9zVl4EtNHjsE_MipbKiA5PjCzl6LGTyNfvq4Ttw53KF1Bg2rIeKKi-vDui9ThwHFyinZv7pzSAlQqmw21bOOsqZoTvis1iLM4Y8s1KPZg'
  <?php

  $curl = curl_init();
  $apiToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImQxNDgzMDEyZTFkNDM2OThhYTgxODYxZjVmMGNhNDllMjdlNjY2OTIzNDlkYTU0YzQ0MTUyNGZlMjY4ZmI5MmNkMmM5NTA4ZDdlMzZiYjE4In0.eyJhdWQiOiJFbWlscyBUb2tlbiIsImp0aSI6ImQxNDgzMDEyZTFkNDM2OThhYTgxODYxZjVmMGNhNDllMjdlNjY2OTIzNDlkYTU0YzQ0MTUyNGZlMjY4ZmI5MmNkMmM5NTA4ZDdlMzZiYjE4IiwiaWF0IjoxNjA1MTkyMzk1LCJuYmYiOjE2MDUxOTIzOTUsImV4cCI6DjE0NzQ4MzY0Nywic3ViIjoiMjc4NTk5NDI3ODUzODA5Iiwic2NvcGVzIjpbImZ1bGwiXX0.c9z5oCqvwYkRfzrxWNlF0Hen3gSznptOjb7f3aOlbnEoryos7gNk8FnU96KDkBvSTgJVpMMcj51G-zgaWaRz2jCOFCk6iJGKfg2Qx-jNZP3JpaDECch4lzK4ka-y8aOi2WdB9xFMUMSccblVWHkbhBHzLn9HfDa_-rzT-gMDFdSkspkkroAbpWhTdkspdMEdkUmTlrLxLhqRcMguo2oKTq3MXjSpVIviHYs0ckJMcbKBI9zVl4EtNHjsE_MipbKiA5PjCzl6LGTyNfvq4Ttw53KF1Bg2rIeKKi-vDui9ThwHFyinZv7pzSAlQqmw21bOOsqZoTvis1iLM4Y8s1KPZg";

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.onpay.io/v1/gateway/information",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
      "Content-Type: application/json",
      "Authorization: Bearer " . $apiToken
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;

The API token is used by setting an Authorization header in the HTTP request sent to the API using the Authorization Bearer scheme.

The Authorization header is set with the value 'Bearer ' followed by the API token (See examples).

Transactions

Get list of transactions

Relative URL example

    /v1/transaction/?page=2&page_size=50&order_by=created&direction=ASC&query=1234&status=active
    /v1/transaction/?page=2&page_size=20&date_after=27-10-2017&date_before=2017-11-17

GET / v1 / transaction /

Returns a list of transactions by multiple parameters.

Request parameters

JSON request example

  { }
Parameter Method Description Value Default Required
page query Pagination page [0-9]+ 1 false
page_size query Items per page, to a maximum of 100 <= 100 25 false
order_by query Column to order list by transaction_number, created, order_id, or amount transaction_number false
direction query Direction of order_by, either ascending or descending ASC, DESC DESC false
query query Search transactions by either exact Order id or exact transaction number [a-zA-Z0-9]+ false
status query Status to get transactions by. If none is defined, transactions by all status are returned. active, cancelled, created, declined, finished, refunded, pre_auth false
date_after query Request transactions from after this date. Date included. YYYY-MM-DD false
date_before query Request transactions from before this date. Date included. YYYY-MM-DD false

Response

JSON response example

    {
      "data": [
          {
              "3dsecure": false,
              "acquirer": "nets",
              "amount": 12300,
              "card_type": "visa",
              "charged": 0,
              "created": "2017-10-04 09:38:46",
              "currency_code": 208,
              "order_id": "1234567890",
              "refunded": 0,
              "status": "active",
              "transaction_number": 1234,
              "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
              "wallet": "mobilepay",
              "links": {
                  "self": "/v1/transction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f"
              }
          }
      ],
      "meta": {
          "pagination": {
              "total": 200,
              "count": 10,
              "per_page": 10,
              "current_page": 15,
              "total_pages": 20,
              "links": {
                "previous": "http://api.esm.test/v1/transaction/page=14",
                "next": "http://api.esm.test/v1/transaction/page=16"
            }
         }
      }
   }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
SimpleTransaction array Array of SimpleTransaction, simpler information about transaction
Pagination item Information about current pagination

Get transaction events

Relative URL example

    /v1/transaction/events/
    /v1/transaction/events/?cursor=

GET / v1 / transaction/events /

Returns transaction history events, this endpoint is optimal if you need to keep a system updated with latest events. This list will always be sorted with the newest events last, and the cursor can be saved for a later call to avoid fetching everything again. If there are no more pages, the cursor returned will be an empty string, previous cursor should then be saved for later refetch for new events.

Usage of this endpoint should be able to handle that the same event may appear on multiple pages, the uuid of each event can be used to handle this.

Request parameters

Parameter Method Description Value Default Required
cursor query Pagination cursor .+ false

Response

JSON response example

    {
        "data": [
             {
                    "uuid": "dfe8bf50-aaaa-11e7-898d-be9d7bb73511",
                    "transaction": "df682406-aaaa-11e7-898d-be9d7bb73511",
                    "date_time": "2019-03-24 07:49:49",
                    "action": "authorize",
                    "successful": true,
                    "amount": 8584,
                    "result_code": "0",
                    "result_text": "approved",
                    "author": "system",
                    "ip": "127.0.0.1",
                    "links": {
                        "transaction": "http://api.onlinepay.io/v1/transaction/df682406-aaaa-11e7-898d-be9d7bb73511"
                    }
             },
             ...
        ],
        "meta": {
            "next_cursor": "/v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f"
        }
    }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
TransactionEvent item TransactionEvent

Get a specific transaction

Relative URL example

    /v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f
    /v1/transaction/1234

GET / v1 / transaction / { uuid | transaction number }

Returns a specific transaction either through the uuid or the transaction number. Either is required.

Request parameters

JSON request example

    { }
Parameter Method Description Value Default Required
uuid path Uuid of transaction [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
transaction number path Transaction's number [0-9]+ true *
* Either of these is required. But only one of them, not both.

Response

JSON response example

    {
        "data": [
            {
                "3dsecure": false,
                "acquirer": "nets",
                "amount": 12300,
                "card_bin": "457199",
                "card_type": "visa",
                "card_country": 208,
                "charged": 0,
                "created": "2017-10-04 09:38:46",
                "currency_code": 208,
                "expiry_month": 12,
                "expiry_year": 2020,
                "ip": "127.0.0.1",
                "ip_country": 208,
                "order_id": "1234567890",
                "refunded": 0,
                "status": "active",
                "subscription_number": 321,
                "subscription_uuid": "03e8162a-a7ac-11e7-9d00-b61928e29a9f",
                "transaction_number": 1234,
                "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
                "wallet": "mobilepay",
                "has_cardholder_data": true,
                "cardholder_data": {
                    "first_name": "First name",
                    "last_name": "Last name",
                    "attention": "Attention name",
                    "company": "OnPay",
                    "street": "Street name",
                    "number": "42",
                    "floor": "",
                    "door": "",
                    "postal_code": "0000",
                    "country": 208,
                    "email": "email@onpay.io",
                    "phone": "11223344",
                    "delivery_address": {
                      ...
                    },
                    "extra": {
                      ...
                    }
                },
                "history": [
                    {
                        "action": "authorize",
                        "amount": 12300,
                        "author": "email@onpay.io",
                        "date_time": "2017-10-04 09:38:46",
                        "ip": "127.0.0.1",
                        "result_code": "000",
                        "result_text": "Approved",
                        "uuid": "15194d80-32ae-45a9-843d-f1acb9b9d484",
                        "successful": true
                    }
                ]
            }
        ],
        "links": {
            "self": "/v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
            "subscription": "/v1/subscription/03e8162a-a7ac-11e7-9d00-b61928e29a9f"
        }
    }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
DetailedTransaction item DetailedTransaction, Detailed information about the transaction

Capture a transaction

Relative URL example

    /v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f/capture
    /v1/transaction/1234/capture

POST / v1 / transaction / { uuid | transaction number } / capture

Captures specific transaction, and returns content of captured transaction.

Request parameters

JSON request example

    {
        "data": {
            "amount": 12300
        }
    }
Parameter Method Description Value Default Required
uuid path Uuid of transaction [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
transaction number path Transaction's number [0-9]+ true *
amount body Amount to capture on transaction. If no value is sent, entire available amount will be captured. [0-9]{11} all false
* Either of these is required. But only one of them, not both.

Response

JSON response example

   {
      "data": {
         "3dsecure": false,
         "acquirer": "nets",
         "amount": 12300,
         "card_bin": "457199",
         "card_type": "visa",
         "charged": 12300,
         "created": "2017-10-04 09:38:46",
         "currency_code": 208,
         "expiry_month": 12,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "order_id": "1234567890",
         "refunded": 0,
         "status": "captured",
         "subscription_number": 321,
         "subscription_uuid": "03e8162a-a7ac-11e7-9d00-b61928e29a9f",
         "transaction_number": 1234,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "mobilepay",
         "history": [
            ...
         ]
      },
      "links": {
         ...
      }
   }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
DetailedTransaction item DetailedTransaction, Detailed information about the transaction

Refund a transaction

Relative URL example

    /v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f/refund
    /v1/transaction/1234/refund

POST / v1 / transaction / { uuid | transaction number } / refund

Refunds specific transaction, and returns content of refunded transaction.

Request parameters

JSON request example

    {
        "data": {
            "amount": 10000
        }
    }
Parameter Method Description Value Default Required
uuid path Uuid of transaction [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
transaction number path Transaction's number [0-9]+ true *
amount body Amount to refund on transaction. If no value is sent, entire available amount will be refunded. [0-9]{11} all false
* Either of these is required. But only one of them, not both.

Response

JSON response example

   {
      "data": {
         "3dsecure": false,
         "acquirer": "nets",
         "amount": 12300,
         "card_bin": "457199",
         "card_type": "visa",
         "charged": 2300,
         "created": "2017-10-04 09:38:46",
         "currency_code": 208,
         "expiry_month": 12,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "order_id": "1234567890",
         "refunded": 0,
         "status": "captured",
         "subscription_number": 321,
         "subscription_uuid": "03e8162a-a7ac-11e7-9d00-b61928e29a9f",
         "transaction_number": 1234,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "mobilepay",
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
DetailedTransaction item DetailedTransaction, Detailed information about the transaction

Cancel a transaction

Relative URL example

    /v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f/cancel
    /v1/transaction/1234/cancel

POST / v1 / transaction / { uuid | transaction number } / cancel

Cancels specific transaction, and returns content of cancelled transaction.

Request parameters

JSON request example

    { }
Parameter Method Description Value Default Required
uuid path Uuid of transaction [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
transaction number path Transaction's number [0-9]+ true *
* Either of these is required. But only one of them, not both.

Response

JSON response example

   {
      "data": {
         "3dsecure": false,
         "acquirer": "nets",
         "amount": 12300,
         "card_bin": "457199",
         "card_type": "visa",
         "charged": 0,
         "created": "2017-10-04 09:38:46",
         "currency_code": 208,
         "expiry_month": 12,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "order_id": "1234567890",
         "refunded": 0,
         "status": "cancelled",
         "subscription_number": 321,
         "subscription_uuid": "03e8162a-a7ac-11e7-9d00-b61928e29a9f",
         "transaction_number": 1234,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "mobilepay",
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
DetailedTransaction item DetailedTransaction, Detailed information about the transaction

Subscriptions

Get all subscriptions

Relative URL example

    /v1/subscription?page=2&pagesize=50&order_by=created&direction=ASC&query=1234&status=active
    /v1/subscription?page=2&pagesize=20&after_date=27-10-2017&date_before=2017-11-27

GET / v1 / subscription

Returns a list of subscriptions by multiple parameters.

Request parameters

JSON request example

  { }
Parameter Method Description Value Default Required
page query Pagination page [0-9]+ 1 false
page_size query Items per page, to a maximum of 100 <= 100 25 false
order_by query Column to order list by subscription_number, created, order_id, or status subscription_number false
direction query Direction of order_by, either ascending or descending ASC, DESC DESC false
query query Search subscriptions by either exact Order id or exact subscription number [a-zA-Z0-9]+ false
status query Status to get transactions by. If none is defined, subscriptions by all status are returned. active, cancelled false
date_after query Request subscriptions from after this date. Date included. YYYY-MM-DD false
date_before query Request subscriptions from before this date. Date included. YYYY-MM-DD false

Response

JSON response example

  {
      "data": [
          {
              "3dsecure": false,
              "acquirer": "nets",
              "card_type": "visa",
              "created": "2017-10-04 09:38:46",
              "currency_code": 208,
              "order_id": "1234567891",
              "status": "active",
              "subscription_number": 123,
              "uuid": "03c8c78e-a7ac-11e7-9cff-b61928e29a9f",
              "wallet": "",
              "links": {
                  "self": "/v1/subscription/03c8c78e-a7ac-11e7-9cff-b61928e29a9f"
              }
          }
      ],
      "meta": {
          "pagination": {
              "total": 200,
              "count": 10,
              "per_page": 10,
              "current_page": 15,
              "total_pages": 20,
              "links": {
                  "previous": "http://api.esm.test/v1/subscription/page=14",
                  "next": "http://api.esm.test/v1/subscription/page=16"
              }
          }
      }
  }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
SimpleSubscription array Array of SimpleSubscription, simpler information about subscription
Pagination item Information about current pagination

Get a specific subscription

Relative URL example

    /v1/subscription/0bb17c90-a80e-11e7-8fc8-b61928e29a9f
    /v1/subscription/123

GET / v1 / subscription / { uuid | subscription number }

Returns a specific subscription either through the uuid or the subscription number. Either is required.

Request parameters

JSON request example

    { }
Parameter Method Description Value Default Required
uuid path Uuid of subscription [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
subscription number path Subscription's number [0-9]+ true *
* Either of these is required. But only one of them, not both.

Response

JSON response example

  {
      "data": {
         "3dsecure": false,
         "acquirer": "nets",
         "card_bin": "457199",
         "card_type": "visa",
         "card_country": 208,
         "created": "2017-10-04 09:38:46",
         "currency_code": 208,
         "expiry_month": 12,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "ip_country": 208,
         "order_id": "1234567891",
         "status": "active",
         "subscription_number": 123,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "",
         "history": [
            {
               "action": "authorize",
               "author": "email@onpay.io",
               "date_time": "2017-10-04 09:38:46",
               "ip": "127.0.0.1",
               "result_code": "000",
               "result_text": "Approved",
               "successful": true
            }
         ],
         "transactions": [
            {
               "3dsecure": false,
               "acquirer": "nets",
               "amount": 12300,
               "card_type": "visa",
               "charged": 0,
               "created": "2017-10-04 09:38:46",
               "currency_code": 208,
               "order_id": "1234567890",
               "refunded": 0,
               "status": "active",
               "transaction_number": 1234,
               "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
               "wallet": "",
               "links": [
                   {
                       "rel": "self",
                       "uri": "/v1/transction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f"
                   }
               ]
            }
         ]
      },
      "links": {
         "self": "/v1/subscription/0bb17c90-a80e-11e7-8fc8-b61928e29a9f"
      }
   }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
DetailedSubscription item DetailedSubscription, Detailed information about the subscription

Create new transaction from subscription

Relative URL example

    /v1/subscription/0bb17c90-a80e-11e7-8fc8-b61928e29a9f/authorize
    /v1/subscription/123/authorize

POST / v1 / subscription / { uuid | subscription number } / authorize

Used to create a new transaction based on an existing subscription by subscription uuid or number. Either is required. The created transaction is returned.

Request parameters

JSON request example

  {
      "data": {
          "amount": 12000,
          "order_id": "20171205143025"
      }
  }
Parameter Method Description Value Default Required
uuid path Uuid of subscription [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
subscription number path Subscription's number [0-9]+ true *
amount body Amount to authorize transaction with in minor units [0-9]{11} true
order_id body [a-zA-Z0-9\-\.]{1,36} true
* Either of these is required. But only one of them, not both.

Response

JSON response example

   {
      "data": {
         "3dsecure": false,
         "acquirer": "nets",
         "amount": 12300,
         "card_bin": "457199",
         "card_type": "visa",
         "charged": 0,
         "created": "2017-10-04 09:38:46",
         "currency_code": 208,
         "expiry_month": 12,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "order_id": "1234567890",
         "refunded": 0,
         "status": "cancelled",
         "subscription_number": 123,
         "subscription_uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "transaction_number": 1234,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "",
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

HTTP

Code Type Description
201 Created Resource was created response

Content

Model Type Description
DetailedTransaction item DetailedTransaction, Detailed information about the created transaction

Cancel subscription

Relative URL example

    /v1/subscription/0bb17c90-a80e-11e7-8fc8-b61928e29a9f/cancel
    /v1/subscription/123/cancel

POST / v1 / subscription / { uuid | subscription number } / cancel

Cancels a subscription, by subscription uuid or number. Either is required. Afterwards it will not be possible to create any new transactions from it.

Request parameters

JSON request example

    { }
Parameter Method Description Value Default Required
uuid path Uuid of subscription [a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12} true *
subscription number path Subscription's number [0-9]+ true *
* Either of these is required. But only one of them, not both.

Response

JSON response example

   {
      "data": {
         "3dsecure": false,
         "acquirer": "nets",
         "card_bin": "457199",
         "card_type": "visa",
         "created": "2017-10-04 09:38:46",
         "currency_code": 208,
         "expiry_month": 12,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "order_id": "1234567891",
         "status": "cancelled",
         "subscription_number": 123,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "",
         "history": [
           ...
         ],
         "transactions": [
          ...
         ]
      },
      "links": {
         ...
      }
   }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
DetailedSubscription item DetailedSubscription, Detailed information about the subscription

Gateway

Get gateway information

Relative URL example

    /v1/gateway/information

GET / v1 / gateway / information

Returns a list of information about the gateway. As by now the gateway ID is the only list entry.

Request parameters

JSON request example

  { }

Response

JSON response example

  {
      "data": {
          "gateway_id": "12345678910111213141516",
          "active_methods": [
              "card",
              "mobilepay",
              "mobilepay_checkout",
              "viabill"
          ]
      }
  }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
GatewayInformation item GatewayInformation, a list of information about the gateway.

Get payment window v3 integration settings

Relative URL example

    /v1/gateway/window/v3/integration/

GET / v1 / gateway / window / v3 / integration

Returns a list of payment window integration settings.

Request parameters

JSON request example

  { }

Response

JSON response example

  {
    "data": {
      "secret": "db78b4dac653b65a7bb09fa7d6512367c8056214c29558f6bd1e2327a3a2854c0c57683ec7f784ec596757adee0d901d53d88145ef7251c496444e8fececb0c7"
    }
  }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
GatewayWindowIntegration item GatewayWindowIntegration, a list of settings used for integrating the payment window.

Get payment window v3 designs

Relative URL example

    /v1/gateway/window/v3/design/

GET / v1 / gateway / window / v3 / design /

Returns a list of SimpleGatewayWindowDesign. The name of the design, is directly used by the payment window as a reference for the design that should be used.

Request parameters

JSON request example

  { }

Response

JSON response example

  {
    "data": [
      {
        "name": "Danish window"
      }, {
        "name": "International window"
      }
    ]
  }

HTTP

Code Type Description
200 OK Standard successful response

Content

Model Type Description
SimpleGatewayWindowDesign array Array of SimpleGatewayWindowDesign.

Models

SimpleTransaction

Parameter Description Value Available
3dsecure Whether 3DSecure was enabled when transaction was captured boolean
amount Transactions total amount in minor units integer
acquirer Acquirer used for transaction string
card_type Card used for transaction, CardType string
charged Amount currently charged of total integer
created Datetime when transaction was created in format: yyyy-mm-dd hh:mm:ss string
currency_code Integer value of standard ISO4217 integer
order_id ID of order related to transaction string
refunded Amount currently refunded of total integer
status Current status of transaction, Status string active cancelled created declined finished refunded pre_auth
transaction_number Transaction's number string
uuid Uuid of transaction string
wallet Wallet used for transaction string
has_cardholder_data Whether cardholder data is available on transaction boolean
links Link object Links self

DetailedTransaction

Parameter Description Value Available
3dsecure Whether 3DSecure was enabled when transaction was captured boolean
acquirer Acquirer used for transaction string
amount Transactions total amount in minor units integer
card_bin Bin for used card, usually first 6 digits string
card_type Card used for transaction, CardType string
card_country Country of origin for used card, integer value of standard ISO3166-1 integer
charged Amount currently charged of total integer
created Datetime when transaction was created in format: yyyy-mm-dd hh:mm:ss string
currency_code Integer value of standard ISO4217 integer
expiry_month Month number used card expires integer
expiry_year Year used card expires integer
ip IP address from which transaction was initialized string
ip_country Country of origin for IP address, integer value of standard ISO3166-1 integer
order_id ID of order related to transaction string
refunded Amount currently refunded of total integer
status Current status of transaction, Status string active cancelled created declined finished refunded pre_auth
subscription_number Number of related subscription, if available integer null
subscription_uuid Uuid of related subscription, if available string null
transaction_number Transaction's number integer
uuid Uuid of transaction string
wallet Wallet used for transaction string
has_cardholder_data Whether cardholder data is available on transaction boolean
cardholder_data TransactionCardholderData object. Null if not available or data has expired. Data expires 14 days after creation. TransactionCardholderData null
history Array of TransactionHistory TransactionHistory []
links Link object Links self subscription

TransactionCardholderData

Parameter Description Value
first_name Cardholders first name string
last_name Cardholders last name string
attention Attention name string
company Company name string
address1 Address field 1 string
address2 Address field 2 string
postal_code Postal code string
city City name string
country Country, integer value of standard ISO3166-1 integer
email Cardholders email address string
phone Cardholders phonenumber string
delivery_address DeliveryAddress Object containing delivery address if available. DeliveryAddress null
extra Extra fields depending on acquirer/wallet. See Extra array

DeliveryAddress

If the cardholder has supplied a separate address for delivery, this address will be available in this field.

Parameter Description Value
first_name Delivery first name string
last_name Delivery last name string
attention Delivery attention name string
company Delivery company name string
address1 Delivery address field 1 string
address2 Delivery address field 2 string
postal_code Delivery postal code string
city Delivery city name string
country Delivery country, integer value of standard ISO3166-1 integer

Extra

Extra fields available depending on the acquirer/wallet used for the transaction. These are as follows:

MobilePayOnline (Wallet)

All extra fields related to MobilePayOnline are prefixed by mpo_. These fields are optional and might not be available in every context.

Parameter Description Value
mpo_email_validity Whether the email address provided is validated by MobilePay boolean
mpo_phone_validity Whether the phone number provided is validated by MobilePay boolean
mpo_address_validity Whether the address provided is validated as an actual address by DAWA boolean
mpo_address_customer_connected Whether the address provided is the official address of the cardholder boolean
mpo_delivery_address_validity Whether the delivery address provided is validated as an actual address by DAWA boolean
mpo_delivery_address_customer_connected Whether the delivery address provided is the official address of the cardholder boolean

TransactionHistory

Parameter Description Value Available
action Name of action string acs amount-change authorize cancel capture create refund renew
amount Amount used on action in minor units integer
author Registered user/system responsible for action string
date_time Datetime when action was registered in format: yyyy-mm-dd hh:mm:ss string
ip IP address registered in relation to action string
result_code Code indication result of action string
result_text A textual representation of actions result string
successful Whether action was successful or not boolean
uuid Uuid of transactionHistory string

TransactionEvent

Parameter Description Value Available
uuid UUID of this specific history item string
transaction UUID of the transaction associated with this event string
action Name of action string acs amount-change authorize cancel capture create refund renew
amount Amount used on action in minor units integer
author Registered user/system responsible for action string
date_time Datetime when action was registered in format: yyyy-mm-dd hh:mm:ss string
ip IP address registered in relation to action string
result_code Code indication result of action string
result_text A textual representation of actions result string
successful Whether action was successful or not boolean

SimpleSubscription

Parameter Description Value Available
3dsecure Whether 3DSecure was enabled when subscription was created boolean
acquirer Acquirer used for subscription string
card_type Card used for subscription, CardType string
created Datetime when subscription was created in format: yyyy-mm-dd hh:mm:ss string
currency_code Integer value of standard ISO4217 integer
order_id ID of order related to subscription string
status Current status of subscription, Status string active cancelled
subscription_number Subscription's number string
uuid Uuid of subscription string
wallet Wallet used for subscription string
links Link object Links self

DetailedSubscription

Parameter Description Value Available
3dsecure Whether 3DSecure was enabled when subscription was created boolean
acquirer Acquirer used for subscription string
card_bin Bin for used card, usually first 6 digits string
card_type Card used for subscription, CardType string
card_country Country of origin for used card, integer value of standard ISO3166-1 integer
created Datetime when subscription was created in format: yyyy-mm-dd hh:mm:ss string
currency_code Integer value of standard ISO4217 integer
expiry_month Month number used card expires integer
expiry_year Year used card expires integer
ip IP address from which subscription was initialized string
ip_country Country of origin for IP address, integer value of standard ISO3166-1 integer
order_id ID of order related to subscription string
status Current status of subscription, Status string active cancelled
subscription_number Subscription's number string
uuid Uuid of subscription string
wallet Wallet used for subscription string
history Array of SubscriptionHistory SubscriptionHistory []
transactions Array of SimpleTransaction SimpleTransaction []
links Link object Links self

SubscriptionHistory

Parameter Description Value Available
action Name of action string acs amount-change authorize cancel capture create refund renew
author Registered user/system responsible for action string
date_time Datetime when action was registered in format: yyyy-mm-dd hh:mm:ss string
ip IP address registered in relation to action string
result_code Code indication result of action string
result_text A textual representation of actions result string
successful Whether action was successful or not boolean
uuid Uuid of subscriptionHistory string

GatewayInformation

Parameter Description Value
gateway_id ID of gateway being used in the API string
active_methods List of currently active payment methods on gateway string[]

GatewayWindowIntegration

Parameter Description Value
secret The secret required to calculate sha sums from values in the payment window. string

SimpleGatewayWindowDesign

Parameter Description Value
name Name of the design, used as identifier for the design. string

Pagination

Pagination is contained within the meta namespace which is always at the same level as the data namespace.

Parameter Description Value
total Total number of items integer
count Items shown on current page integer
per_page Items shown per page integer
current_page Current page integer
total_pages Total number of pages integer
links Links related to pagination string []
Parameter Description Value
next_url Relative url to next page string null
previous_url Relative url to previous page string null

CardType

Card type string values and what card they correspond to.

Parameter Description
dankort Dankort card
visa Visa card
amex American Express card
maestro Maestro card
mastercard Mastercard
diners Diners Club card
jcb JCB
unionpay UnionPay
discover Discover card
fbf Forbrugsforeningen card

Status

Transactions and subscriptions statuses is explained.

Transaction

Status Description Actions available
active Transaction is authorized by acquirer/wallet. capture cancel refund
cancelled Transaction has been cancelled.
created Transaction has been created, awaiting further action from cardholder prior to authorization.
declined Transaction was declined by acquirer/wallet.
finished Transaction has been fully captured or fully refunded. refund
pre_auth Transaction has yet to be authorized by acquirer/wallet.

Subscription

Status Description Actions available
active Subscription is active authorize cancel
cancelled Subscription has been cancelled
created Transaction has been created, awaiting further action from cardholder prior to authorization.

The Links object can contain a multitude of elements depending on the object in which it is contained. Links items are named by their relation to the element contained in. If a link is not available for a certain element, it will not be available in the Links object at all.

As an example the following are links to the element itself, and to a related subscription:

Parameter Link Value
self "/v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f" string
subscription "/v1/subscription/03e8162a-a7ac-11e7-9d00-b61928e29a9f" string

For further information about which links that are available for which elements, please see documentation for the element in question.

Error

Errors returned from API are per default handled through HTTP response codes. Understanding of HTTP status codes and their meaning is implied by client. To an extend, an error model response accompanies unusual errors, with a more detailed description of error.

Parameter Description Value
message Human readable error description string