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/{merchant_id}/oauth2/authorize	Replace the optional {merchant_id} with the id of the merchant, access is wanted for. If {merchant_id} is omitted, user will be presented a choice of merchants when having access to multiple.
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).

API reponses

API responses are in JSON format, and follows a REST design. Responses also utilizes standard HTTP response codes, and in the case of 4XX and 5XX response codes, the JSON body includes a detailed error message. Please note that the HTTP response code is in the header of the response.

HTTP codes

The following is a list of response codes one can expect to encounter using the API.

Code	Type	Description
200	OK	Standard successful response
201	Created	Resource was created sucessfully
202	Accepted	Request was sucessfully processed
400	Bad request	Request was badly formatted
401	Unauthorized	Authentication not valid
403	Forbidden	Authenticated, but denied access to requested resource
404	Not found	Resource not found
405	Method not allowed	HTTP method in request not allowed
409	Conflict	Request in conflict with resource state
422	Unprocessable entity	Request correctly formatted, but server was unable to process request
500	Internal server error	The server encountered an internal error

Error responses

JSON error response example

    {
      "errors": [
        {
          "message": "Error: card expired"
        }
      ]
    }

When encoutering either a 4XX or 5XX response code, an accompanying error message is to be found in the JSON body of the response. To the right is an example of an error message accompanying a 422 HTTP response code.

Payments

Create a new payment request

POST / v1 / payment / create

Create a new payment. Returns an object with link to the created payment.

JSON request example

{
    "currency": "DKK",
    "amount": 12000,
    "reference": "AF-847824",
    "accepturl": "https://example.com/accept",
    "type": "transaction",
    "method": "card",
    "language": "en",
    "declineurl": "https://example.com/decline",
    "callbackurl": "https://example.com/callback",
    "website": "https://example.com",
    "design": "window1",
    "expiration": 4200,
    "testmode": true,
    "info": {
      "name": "Emil Pedersen",
      "email": "emil@example.org",
      "account": {
        "id": "ABC-455454",
        "date_created": "2020-02-15",
        "date_change_date": "2020-03-02",
        "date_password_change": "2020-03-02",
        "purchases": 3,
        "attempts": 0,
        "shipping_first_use_date": "2020-02-15",
        "shipping_identical_name": "Y",
        "suspicious": "N",
        "attempts_day": 3,
        "attempts_year": 3
      },
      "billing": {
        "address_city": "Skanderborg",
        "address_country": "208",
        "address_line1": "Højvangn 4",
        "address_line2": "Line 2",
        "address_line3": "Line 3",
        "address_postal_code": "8660",
        "address_state": "NY"
      },
      "shipping": {
        "address_city": "Skanderborg",
        "address_country": "208",
        "address_line1": "Højvangen 4",
        "address_line2": "Line 2",
        "address_line3": "Line 3",
        "address_postal_code": "8660",
        "address_state": "NY"
      },
      "phone": {
        "home_cc": "45",
        "home_number": "37123456",
        "mobile_cc": "45",
        "mobile_number": "37123456",
        "work_cc": "45",
        "work_number": "37123456"
      },
      "address_identical_shipping": "Y",
      "delivery_email": "emil@example.org",
      "delivery_time_frame": "03",
      "gift_card_amount": 12000,
      "gift_card_count": 1,
      "preorder": "N",
      "preorder_date": "2020-04-01",
      "reorder": "N",
      "shipping_method": "01"
    },
    "cart": {
        "shipping": {
            "price": 4000,
            "discount": 0,
            "tax": 200
        },
        "handling": {
            "price": 0,
            "tax": 0
        },
        "discount": 400,
        "items": [
            {
                "name": "t-shirt",
                "price": 1200,
                "quantity": 2,
                "tax": 300
            },
            {
                "name": "pants",
                "price": 5200,
                "quantity": 1,
                "tax": 1300
            }
        ]
    }
}

Parameter	Value	Description	Example
currency*	`string`	The ISO4217 currency (Alpha3 code)	e.g `"DKK"` for Denmark
amount*	`integer`	The amount for the order, in minor units. If type is `subscription` set it to `0`.	`12000` For 120.00 DKK.
reference*	`string ([a-zA-Z0-9\-\.]{1,36})`	Has to be unique, your own internal reference, even tho both upper and lower case is accepted they are treated the same in the system	`AF-847824`
website*	Valid URL	URL to the website where the checkout process was started	`https://example.com/`
accepturl	Valid URL	Where to send the user after a successful reservation is made.	`https://example.com/accept`
type	`transaction` or `subscription`	Defaults to `transaction`	`transaction`
method	See Methods	If none is provided, the user is presented with a choice of which method to use.
language	`da`, `de`, `en`, `es`, `fo`, `fr`, `it`, `nl`, `no`, `pl` or `sv`	The language of the payment window. Defaults to English	`en`
declineurl	Valid URL	Where to send the user in case payment failed, if this value is not set the accepturl will be used!	`https://example.com/decline`
callbackurl	Valid URL	If set, onpay system will make a direct call to this URL to signal that a payment suceeded. See more here	`https://example.com/callback`
design	`string ([a-zA-Z0-9 ]+)`	The name of the window design to use. Use if you have more than one design defined in the backend	`window1`
expiration	`integer`	Seconds that the payment will be available before expiring. Default is 7 days (604800 seconds).	`4200`
testmode	`[01]`	If set to 1 the window will run in testmode, provided that it has been enabled. It is only necessary to set this parameter if production mode is also enabled	`1`
info	`object`	Additional info about the customer, see here for details
cart	`object`	Additional info about the cart, see here for details

Payment Response

JSON response example

{
  "data": {
    "payment_uuid": "dfe8bf50-aaaa-11e7-898d-be9d7bb73511",
    "amount": 12000,
    "currency_code": "980",
    "expiration": "2022-03-02 11:12:14",
    "language": "en",
    "method": "card",
  }
  "links": {
    "payment_window": "https://onpay.io/window/v3/dfe8bf50-aaaa-11e7-898d-be9d7bb73511"
  }
}

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response

Content

Model	Type	Description
SimplePayment	object	SimplePayment Object with payment link

Methods

The following methods are supported. When a specific method is sent to the payment window, the cardholder will be redirected to said method. If none is provided, the user is presented with a choice of which method to use.

Method	Parameter	Description	Supports subscriptions
Anyday	`anyday`	Payment using Anyday. Only currency `DKK` allowed.	No
Apple Pay	`applepay`	Payment using Apple Pay. Browser support required	Yes
Credit card	`card`	Payment using credit cards.	Yes
Google Pay	`googlepay`	Payment using Google Pay. Browser support required	Yes
MobilePay Online	`mobilepay`	Payment using MobilePay Online. Currencies allowed: `DKK` `NOK` `SEK` `GBP` `USD` `EUR`.	No
Swish	`swish`	Payment through Swish. Only currency `SEK` allowed.	No
ViaBill	`viabill`	Payment using ViaBill. Currencies allowed: `DKK` `EUR`	No
Vipps	`vipps`	Payment through Vipps. Only currency `NOK` allowed.	No

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=2017-10-27&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",
              "testmode": false,
              "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": "https://api.onpay.io/v1/transaction/page=14",
                "next": "https://api.onpay.io/v1/transaction/page=16"
            }
         }
      }
   }

Common HTTP codes

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": "https://api.onpay.io/v1/transaction/df682406-aaaa-11e7-898d-be9d7bb73511"
                    }
             },
             ...
        ],
        "meta": {
            "next_cursor": "/v1/transaction/0bb17c90-a80e-11e7-8fc8-b61928e29a9f"
        }
    }

Common HTTP codes

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": 4,
            "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": {
                  ...
                }
            },
            "testmode": false,
            "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"
        }
    }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response
404	Not found	Transaction not found

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 examples

    {
        "data": {
            "amount": 12300
        }
    }

    {
        "data": {
            "postActionChargeAmount": 12300
        }
    }

Parameter	Method	Description	Value	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	`[0-9]{11}`	false **
postActionChargeAmount	body	The expected `charged` amount after the capture action is done	`[0-9]{11}`	false **

* Either of these is required. But only one of them, not both.

** Only one of them, not both. If neither is provided, the entire available amount will be captured.

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": 4,
         "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",
         "has_cardholder_data": false,
         "cardholder_data": {
           ...
         },
         "testmode": false,
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response
404	Not found	Transaction not found

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 examples

    {
        "data": {
            "amount": 10000
        }
    }

    {
        "data": {
            "postActionRefundAmount": 10000
        }
    }

Parameter	Method	Description	Value	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.	`[0-9]{11}`	false **
postActionRefundAmount	body	The expected `refunded` amount after the refund action is done	`[0-9]{11}`	false **

* Either of these is required. But only one of them, not both.

** Only one of them, not both. If neither is provided, the entire available amount will be refunded.

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": 4,
         "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",
         "has_cardholder_data": false,
         "cardholder_data": {
           ...
         },
         "testmode": false,
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response
404	Not found	Transaction not found

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": 4,
         "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",
         "has_cardholder_data": false,
         "cardholder_data": {
           ...
         },
         "testmode": false,
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response
404	Not found	Transaction not found

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=2017-10-27&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": "",
              "testmode": false,
              "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": "https://api.onpay.io/v1/subscription/page=14",
                  "next": "http://api.onpay.io/v1/subscription/page=16"
              }
          }
      }
  }

Common HTTP codes

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": 4,
         "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": "",
         "testmode": false,
         "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"
      }
   }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response
404	Not found	Subscription not found

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	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": 4,
         "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": "",
         "has_cardholder_data": false,
         "cardholder_data": {
           ...
         },
         "testmode": false,
         "history": [
           ...
         ]
      },
      "links": {
         ...
      }
   }

Common HTTP codes

Code	Type	Description
201	Created	Resource was created response
404	Not found	Subscription not found
409	Conflict	Request in conflict with subscription state
422	Unprocessable entity	Request correctly formatted, but server was unable to process request

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": 4,
         "expiry_year": 2020,
         "ip": "127.0.0.1",
         "order_id": "1234567891",
         "status": "cancelled",
         "subscription_number": 123,
         "uuid": "0bb17c90-a80e-11e7-8fc8-b61928e29a9f",
         "wallet": "",
         "testmode": false,
         "history": [
           ...
         ],
         "transactions": [
          ...
         ]
      },
      "links": {
         ...
      }
   }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response
404	Not found	Subscription not found

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"
          ]
      }
  }

Common HTTP codes

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"
    }
  }

Common HTTP codes

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"
      }
    ]
  }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response

Content

Model	Type	Description
SimpleGatewayWindowDesign	array	Array of SimpleGatewayWindowDesign.

Acquirers

Get list of acquirers

Relative URL example

    /v1/acquirer

GET / v1 / acquirer

Returns a list of SimpleAcquirer. All acquirers with current status.

Request parameters

JSON request example

{ }

Response

JSON response example

  {
    "data": {
      {
        "name": "bambora",
        "active": true,
        "links": {
            "self": "/v1/acquirer/bambora"
        }
      },
      {
        "name": "clearhaus",
        "active": true,
        "links": {
            "self": "/v1/acquirer/clearhaus"
        }
      },
      {
        "name": "nets",
        "active": true,
        "links": {
            "self": "/v1/acquirer/nets"
        }
      },
      {
        "name": "swedbank",
        "active": true,
        "links": {
            "self": "/v1/acquirer/swedbank"
        }
      }
    }
  }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response

Content

Model	Type	Description
SimpleAcquirer	item	List of SimpleAcquirer, simple information about acquirer.

Get a specific acquirer

Relative URL example

    /v1/acquirer/clearhaus

GET / v1 / acquirer / { acquirer name }

Returns a specific acquirer as a DetailedAcquirer.

Request parameters

JSON request example

{ }

Response

JSON response example

  {
    "data": {
      "name": "clearhaus",
      "active": true,
      "api_key": "3764eca2-a225-44b6-b5cc-c069efaf38ac",
      "exemption": {
        "sca_low_value": true,
      },
      "mastercard_bin": "123456",
      "mcc": "1234",
      "merchant_id": "000000001234567",
      "sca_mode": "all",
      "visa_bin": "123456",
      "links": {
          ...
      }
    }
  }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response

Content

Model	Type	Description
DetailedAcquirer	item	DetailedAcquirer, a list of current settings for acquirer.

Update settings of an acquirer

Relative URL example

    /v1/acquirer/nets

PATCH / v1 / acquirer / { acquirer name }

Patches one or more settings of a specific acquirer, and returns said acquirer as DetailedAcquirer.

Request parameters

JSON request example

  {
    "data": {
      "active": true,
      "tof": "12345678",
    }
  }

It is possible to patch single or multiple fields, no fields are required. However not all fields are available for patching, this depends on the acquirer. These fields are as follows:

Bambora

Parameter	Method	Description	Value	Available
active	body	Whether acquirer is active	`boolean`
customer_number	body	Customer number, provided by Bambora	`string`
exemptions	body	Exemptions for acquirer	Exemptions
mcc	body	MCC (Merchant category code), provided by Bambora	`string`
sca_mode	body	When SCA will be used.	`string`	`all` `eu` `off`
tof	body	TOF (Terminaloperator ID), provided by Bambora	`string`

Clearhaus

Parameter	Method	Description	Value	Available
active	body	Whether acquirer is active	`boolean`
api_key	body	API key used with Clearhaus	`[a-zA-Z0-9\-]{1,36}`
exemptions	body	Exemptions for acquirer	Exemptions
sca_mode	body	When SCA will be used.	`string`	`all` `eu` `off`

Clearhaus settings are a bit special, since the fields mastercard_bin, mcc, merchant_id and visa_bin are not patchable. When api_key has been successfully patched with a valid API key, the fields mentioned before will be populated automatically, with information directly from Clearhaus.

Nets

Parameter	Method	Description	Value	Available
active	body	Whether acquirer is active	`boolean`
amex_id	body	American Express ID provided by Nets	`[0-9]{10}`
exemptions	body	Exemptions for acquirer	Exemptions
mcc	body	MCC (Merchant category code), provided by Nets	`[0-9]{4}`
international_id	body	International Merchant ID, provided by Nets	`[0-9]{7}`
mastercard_bin	body	Mastercard BIN, provided by Nets	`[0-9]{6}`
sca_mode	body	When SCA will be used.	`string`	`all` `eu` `off`
tof	body	TOF (Terminaloperator ID), provided by Nets	`[0-9]{6,8}`
visa_bin	body	Visa BIN, provided by Nets	`[0-9]{6}`

Swedbank Pay

Parameter	Method	Description	Value
active	body	Whether acquirer is active	`boolean`
mcc	body	MCC (Merchant category code), provided by Swedbank	`string`
merchant_id	body	Merchant ID, provided by Swedbank	`string`

Response

JSON response example

  {
    "data": {
      "name": "nets",
      "active": true,
      "amex_id": "1234567890",
      "exemptions" : {
        "sca_low_value": true,
      },
      "international_id": "1234567",
      "mastercard_bin": "123456",
      "mcc": "1234",
      "sca_mode": "all",
      "tof": "12345678",
      "visa_bin": "123456",
      "links": {
          ...
      }
    }
  }

Common HTTP codes

Code	Type	Description
202	Accepted	Request was sucessfully processed
400	Bad request	Request was badly formatted

Content

Model	Type	Description
DetailedAcquirer	item	DetailedAcquirer, a list of current settings for acquirer.

Wallets

Get list of wallets

Relative URL example

    /v1/wallet

GET / v1 / wallet

Returns a list of SimpleWallet. All wallets with current status.

Request parameters

JSON request example

{ }

Response

JSON response example

  {
    "data": {
      {
        "name": "applepay",
        "active": true,
      },
      {
        "name": "googlepay",
        "active": true,
      },
      {
        "name": "mobilepay",
        "active": true,
      },
      {
        "name": "vipps",
        "active": true,
      }
    }
  }

Common HTTP codes

Code	Type	Description
200	OK	Standard successful response

Content

Model	Type	Description
SimpleWallet	item	List of SimpleWallet, simple information about wallet.

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, Acquirer	`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, Wallet	`string`
has_cardholder_data	Whether cardholder data is available on transaction	`boolean`
testmode	Transaction was completed in testmode	`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, Acquirer	`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, Wallet	`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`
testmode	Transaction was completed in testmode	`boolean`
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, Acquirer	`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, Wallet	`string`
testmode	Subscription was completed in testmode	`boolean`
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, Acquirer	`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, Wallet	`string`
testmode	Subscription was completed in testmode	`boolean`
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`

SimpleAcquirer

Parameter	Description	Value	Available
name	Name of the acquirer	`string`
active	Whether acquirer is active	`boolean`
links	Link object	`Links`	`self`

DetailedAcquirer

Parameter	Description	Value	Available
name	Name of the acquirer	`string`
active	Whether acquirer is active	`boolean`
links	Link object	`Links`	`self`
extra	Extra fields depending on acquirer. See below.	`array`

DetailedAcquirer objects includes the fields described above in DetailedAcquirer, but they have their own specific fields depending on the acquirer, as described below.

Bambora

Parameter	Description	Value	Available
customer_number	Customer number, provided by Bambora	`string`
mcc	MCC (Merchant category code), provided by Bambora	`string`
sca_mode	When SCA will be used.	`string`	`all` `eu` `off`
tof	TOF (Terminaloperator ID), provided by Bambora	`string`
exemptions	List of exemptions	Exemptions

Clearhaus

Parameter	Description	Value	Available
api_key	API key used with Clearhaus	`string`
mastercard_bin	Mastercard BIN, given by Clearhaus	`string`
mcc	MCC (Merchant category code), given by Clearhaus	`string`
merchant_id	Merchant ID, given by Clearhaus	`string`
sca_mode	When SCA will be used.	`string`	`all` `eu` `off`
visa_bin	Visa BIN, given by Clearhaus	`string`
exemptions	List of exemptions	Exemptions

Nets

Parameter	Description	Value	Available
amex_id	American Express ID provided by Nets	`string`
mcc	MCC (Merchant category code), provided by Nets	`string`
international_id	International Merchant ID, provided by Nets	`string`
mastercard_bin	Mastercard BIN, provided by Nets	`string`
sca_mode	When SCA will be used.	`string`	`all` `eu` `off`
tof	TOF (Terminaloperator ID), provided by Nets	`string`
visa_bin	Visa BIN, provided by Nets	`string`
exemptions	List of exemptions	Exemptions

Swedbank Pay

Parameter	Description	Value	Available
mcc	MCC (Merchant category code), provided by Swedbank	`string`
merchant_id	Merchant ID, provided by Swedbank	`string`

Exemptions

Parameter	Description	Value	Available
sca_low_value	Whether SCA excemptions is made for low value payments (30 EUR or less)	`boolean`

SimpleWallet

Parameter	Description	Value
name	Name of the wallet	`string`
active	Whether wallet is active	`boolean`

SimplePayment

Parameter	Description	Value
payment_uuid	The unique identification for this payment request	`string`
amount	Amount in the payment request	`int`
currency_code	Selected currency for this payment	`string`
expiration	Expiration for this payment in format `Y-m-d H:is`	`string`
language	Selected language for this payment	`string`
method	Selected method for this payment	`string`
links	Contains a 'payment_window' element with a link to the payment window	`array`

PaymentInfo

Parameter	Value	Description	Example
account	`object`	See Account Info
billing	`object`	See Billing Info
shipping	`object`	See Shipping Info
phone	`object`	See Phone Info
name	`.{2,45}`	The name of the cardholder/customer	`Emil Pedersen`
email	`.{1,254}`	The email address of the customer	`emil@example.org`
address_identical_shipping	`Y`, `N`	Indicates whether the billing and shipping address are the same, only relevant if actually shipping anything.	`Y`
delivery_email	`.{1,254}`	Only used for electronic delivery.	`emil@example.org`
delivery_time_frame	`01`, `02`, `03`, `04`	Indicates the delivery timeframe. 01 = Electronic, 02 = Same-day shipping, 03 = Overnight shipping, 04 = Two-day or more shipping	`03`
gift_card_amount	`[0-9]+`	The total amount of all gift cards within the order, only major units. (DKK 123.45 is 123)	`123`
gift_card_count	`[0-9]+`	The total quantity of gift cards within the order.	`1`
preorder	`Y`, `N`	Indicates if this order is a pre-order. A pre-order is an order for an item that has not yet been released to the market.	`N`
preorder_date	date	For a pre-ordered purchase, the expected date that merchandise will be available	`2020-04-01`
reorder	`Y`, `N`	Indicates if this order is a re-order of a previous one	`N`
shipping_method	`01`, `02`, `03`, `04`, `05`, `06`, `07`	The shipping method for the transaction, use the one that best describes the order. Physical goods takes precedence over digital, and then the most expensive if multiple shipping methods for same order. 01 = Ship to billing address, 02 = Ship to another verified address, 03 = Ship to other, 04 = "Ship to store" store address should be set in shipping address fields, 05 = Digital goods, 06 = Travel & event tickets, 07 = Other (digital services, electronic subscriptions, etc.)	`01`

Account

Parameter	Value	Description	Example
id	`\w{1,64}`	Account identifier, could be a customer number.	`ABC-455454`
date_created	date	When the account was created at the merchant.	`2020-02-15`
date_change	date	When the account was last changed, this includes billing and shipping address.	`2020-03-02`
date_password_change	date	When the account last had its password changed.	`2020-03-02`
purchases	`[0-9]+`	The number of completed purchases with this account in the last 6 months (excluding the current one).	`3`
attempts	`[0-9]+`	The number of payment attempts on this account in the past 24 hours.	`0`
shipping_first_use_date	date	The date of when the shipping address was first used on this account.	`2020-02-15`
shipping_identical_name	`Y`, `N`	Indicates whether the account holder name matches the shipping details.	`Y`
suspicious	`Y`, `N`	Indicates whether the merchant has experienced suspicious actitivy on the account previously (including fraud)	`N`
attempts_day	`[0-9]+`	Number of transactions attempted (successful or not) for this account, in the past 24 hours.	`3`
attempts_year	`[0-9]+`	Number of transactions attempted (successful or not) for this account, in the past 365 days.	`3`

Billing

Parameter	Value	Description	Example
billing_address_city	`.{1,50}`	Billing address city	`Skanderborg`
billing_address_country	`[0-9]{3}`	Billing address country code, in the numeric format from ISO-3166-1	`208`
billing_address_line1	`.{1,50}`	First line of the address	`Højvangen 4`
billing_address_line2	`.{1,50}`	Second line of the address, if needed.	`Address Line 2`
billing_address_line3	`.{1,50}`	Third line of the address, if needed.	`Address Line 3`
billing_address_postal_code	`[\w\s-]{1,16}`	The postal code of the address.	`8660`
billing_address_state	`\w{1,3}`	The subdivision code of the address, according to ISO-3166-2 (Only the part after the country code, so `US-NY` becomes `NY`. Should only be used when relevant for the country.	`NY`

Shipping

Parameter	Value	Description	Example
address_city	`.{1,50}`	Shipping address city	`Skanderborg`
address_country	`[0-9]{3}`	Shipping address country code, in the numeric format from ISO-3166-1	`208`
address_line1	`.{1,50}`	First line of the address	`Højvangen 4`
address_line2	`.{1,50}`	Second line of the address, if needed.	`Address Line 2`
address_line3	`.{1,50}`	Third line of the address, if needed.	`Address Line 3`
address_postal_code	`[\w\s-]{1,16}`	The postal code of the address.	`8660`
address_state	`.{1,3}`	The subdivision code of the address, according to ISO-3166-2 (Only the part after the country code, so `US-NY` becomes `NY`. Should only be used when relevant for the country.	`NY`

Phone

Parameter	Value	Description	Example
home_cc	`[0-9]{1,3}`	The country code part of the phone number	`45`
home_number	`[0-9]{1,15}`	The actual phone number, without the country part.	`37123456`
mobile_cc	`[0-9]{1,3}`	The country code part of the phone number	`45`
mobile_number	`[0-9]{1,15}`	The actual phone number, without the country part.	`37123456`
work_cc	`[0-9]{1,3}`	The country code part of the phone number	`45`
work_number	`[0-9]{1,15}`	The actual phone number, without the country part.	`37123456`

PaymentCart

Cart information can be provided, and on some methods it is mandated.

Recommendation is to always send the data when available, to ensure future demands from payment methods can be easily met.

Be aware that amount on [payment-request](#create-a-new-payment-request) must match the sum of SUM(item price * quantity) + cart_shipping_price + cart_handling_price - cart_shipping_discount - cart_discount

Parameter	Value	Description	Example
shipping	`object`	See ShippingObject
handling	`object`	See HandlingObject
discount	`[0-9]+`	The discount for the order, in minor units. Will be subtracted from the total before matching with `amount` of payment-request	`0` or `5000`
items	list of `object`	A list of the different items in the cart. If more than 20 items, merge the 20th item together with the excess items, so there is never send more than 20 items. See ItemObject

ShippingObject

Parameter	Value	Description	Example
price	`[0-9]+`	The shipping price in minor units, including any taxes but before discount.	`500`
tax	`[0-9]+`	The tax on the shipping.	`500`
discount	`[0-9]+`	Any discount that should be subtracted from the shipping_price.	`500`

HandlingObject

Parameter	Value	Description	Example
onpay_cart_handling_price	`[0-9]+`	Handling price, includes all handling related fees	`500`
onpay_cart_handling_tax	`[0-9]+`	The tax on the handling.	`500`

ItemObject

Parameter	Value	Description	Example
name*	`.{1,127}`	Item name	`Item 1`
price*	`[0-9]+`	The per item price, including taxes.	`100`
tax*	`[0-9]+`	The per item tax.	`20`
quantity*	`[0-9]+`	The amount of items	`1`
description	`.{1,127}`	Item description	`Longer description`
sku	`.{1,127}`	SKU of the item	`AB47871`

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 []`

Links

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

Acquirer

Acquirer string values and what acquirer/provider they correspond to.

Parameter	Description
bambora	Card acquirer Bambora
clearhaus	Card acquirer Clearhaus
nets	Card acquirer Nets
swedbank	Card acquirer Swedbank
anyday	Provider Anyday (Never for subscriptions)
klarna	Provider Klarna (Never for subscriptions)
paypal	Provider PayPal (Never for subscriptions)
swish	Provider Swish (Never for subscriptions)
viabill	Provider ViaBill (Never for subscriptions)

Wallet

Wallet string values and what wallet provider they correspond to.

Parameter	Description
applepay	Apple Pay - Mobile payment solution on Apple devices
googlepay	Google Pay - Mobile payment solution on Google/Android devices
mobilepay	MobilePay - Mobile payment across mobile devices
vipps	Vipps - Mobile payment across mobile devices

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.

Link

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. If a code returned from acquirer is available, this will also be included.

Parameter	Description	Value
message	Human readable error description	`string`
acquirerCode	Code (if available) returned from acquirer	`string`