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/{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 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": 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 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": 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 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": 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 Available
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 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
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 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
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 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
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 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
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.

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