Introduction

Rest API

Security

This API is an SSL-only API over HTTP protocol (HTTPS). Authentication is required to access API-resources using API-keys. API-keys are available inside the regular administration interface.

curl -u {api_key}: https://{yourdomain}/api/v1/...

curl -u 5410aa9585216d14eafad502: 
https://pay.yourcompany.com/api/v1/merchants

Example

Headers

This is a JSON-only API. You must supply a Content-Type: application/json header on PUT and POST operations. You must set a Accept: application/json header on all requests. You may get a text/plain response in case of error, e.g. in case of a bad request, you should treat this as an error you need to take action on.

Common Response Structures

We respond to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, we will render the resulting JSON representation in the response body and set a Location header pointing to the resource, e.g:

Status: 201 Created
Location: https://{domain}/api/v1/merchants/{mid}/users/{id}

{
    "username": "testbutik", 
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "object": "user", 
    "real_name": "Kalle Andersson", 
    "id": 35, 
    "last_logged_in": null
}

We respond to unsuccessful requests with HTTP status codes in the 400 range. The response may be content type text/plain for API level error messages (e.g. when trying to call the API without SSL). The response will be content type application/json for business level error messages. The latter contains a JSON hash with elaborate error messages to supplement the HTTP status code:

Status: 400 Bad Request

{
    "message": "Validation failed", 
    "object": "error", 
    "errors": [
        {
            "message": "Missing field: 'name'"
        }, 
        {
            "message": "Missing field: 'street'"
        }, 
        {
            "message": "Missing field: 'city'"
        }, 
        ...
    ]
}

Collections

Collections return a maximum of 100 records per request, and by default return 100 records per request. You can set this on a per request basis by passing e.g. limit=50 in the request parameters. You iterate the collection by incrementing the offset attribute, e.g. offset=3. The response includes a total count of records that can be used when iterating through available records.

{
    "total_count": 10, 
    "object": "list", 
    "data": [
        {
            "object": "user", 
            ...
        },
        ...
}

Merchants

Json Format

NAME	PARENT	TYPE	READ ONLY	DESCRIPTION
id		string	yes	Unique id for this merchant
name		string	no	Name of merchant
info		object	yes	Object containing information regarding the merchant
org_nr		string	no	Organization number of merchant
address		object	yes	Object containing address information
street	address	string	no	Street address of merchant
zip	address	string	no	Zip code of merchant
city	address	string	no	City of merchant
country	address	string	no	Country of merchant, for example: SWE
paywin		object	yes	Object containing paywin settings
pay_methods	paywin	array	no	String array containing pay methods available for the merchants, possible string-values: Cards and/or Banks
secret	paywin	string	no	String containing the secret word to calculate the SHA256 HMAC.
logo_path	paywin	string	yes	Name of uploaded logo-file.
production	paywin	boolean	yes	True if mapped for card payments and ready for live payments.
onboarding_data		object	yes	Optional section used for qualifying merchants for payments
web	onboarding_data	string	no	Online sales?
moto	onboarding_data	string	no	Mail order telephone order (uncommon in Sweden but for instance hotels might use this)
card_present	onboarding_data	string	no	Sales from physical store
primary_business_face_to_face	onboarding_data	string	no	Yes if card present is yes
prev_card_acceptance	onboarding_data	string	no	Has merchant previously accepted cards
mcc	onboarding_data	string	no	Merchant Categroy Code (Used by banks to set prices, similar to SNI)
business_model_description	onboarding_data	string	no	Provide a clear description of what will be processed.
primary_contact_name	onboarding_data	string	no
primary_contact_phone	onboarding_data	string	no
primary_contact_name	onboarding_data	string	no
street	onboarding_data	string	no	Street address of headquarter
city	onboarding_data	string	no	City of headquarter
zip_code	onboarding_data	string	no	Post code number of headquarter
country	onboarding_data	string	no	Post code number of headquarter
annual_mc_sales_gt_1e6_dollar	onboarding_data	string	no
currency	onboarding_data	string	no
monthly_turnover_target	onboarding_data	string	no	Expected monthly processing volume
website_url	onboarding_data	string	no	Merchant’s processing URL
merchant_name_on_ch_statement	onboarding_data	string	no	Descriptor which will appear on the customer statement (D2I* plus max 18 characters)
iban	onboarding_data	string	no	Merchant IBAN (International Bank Account Number) to receving payments
bic	onboarding_data	string	no	Merchant's bank BIC code (Bank Identfier Code) for receiving payments
sni_2007	onboarding_data	string	no	Include only if not including MCC
sni	onboarding_data	string	no	Included if no including MCC and not using SNI (2007) and SNI standard is latest
account_data	onboarding_data	string	no	Merchant account number (bankgiro number), if not sending IBAN
account_type	onboarding_data	string	no	Merchant account number type, include if account_data field is used, Bankgiro/Plusgiro etc

Listing merchants

Merchant

GET /api/v1/merchants

Merchants are ordered chronologically by created date, from newest to oldest.

Using curl

curl https://{domain}/api/v1/merchants -u {api_key}:

Filter

?offset=0&limit=1

Example Response

Status: 200 OK 
{
    "total_count": 14, 
    "object": "list", 
    "data": [
        {
            "info": {
                "org_nr": "551122-1234"
            }, 
            "name": "Testbutik", 
            "object": "merchant", 
            "address": {
                "city": "Stockholm", 
                "street": "Testgatan 13", 
                "zip": "123 25", 
                "country": "SWE"
            }, 
            "id": "1007", 
            "paywin": {
                "pay_methods": [
                    "cards", 
                    "banks"
                ], 
                "logo_path": null,
                "production": false
            }
        },
        ...
    ]
}

Creating merchants

Getting merchants

GET /api/v1/merchants/{id}

Using curl

curl https://{domain}/api/v1/merchants/1007 -u {api_key}:

Example Response

Status: 200 OK

{
    "info": {
        "org_nr": "551122-1234"
    }, 
    "name": "Testbutik", 
    "object": "merchant", 
    "address": {
        "city": "Stockholm", 
        "street": "Testgatan 13", 
        "zip": "123 25", 
        "country": "SWE"
    }, 
    "id": "1007", 
    "paywin": {
        "pay_methods": [
            "cards", 
            "banks"
        ], 
        "logo_path": null,
        "production": false
    }
}

POST /api/v1/merchants/{id}

Supplying {id} is optional, if absent the newly created id will be returned in the response.

Using curl

curl https://{domain}/api/v1/merchants/1007 -d '{"info": {"org_nr": "551122-1234"}, "name": "Testbutik", "paywin": {"secret": "asdadasd1213ae", "pay_methods": ["cards", "banks"]}, "address": {"city": "Stockholm", "street": "Testgatan 13", "zip": "123 52", "country": "SWE"}}' -H "Content-Type: application/json" {api_key}: -X POST

Example Response

Status: 201 Created
Location: https://{domain}/api/v1/merchants/1007

{
    "info": {
        "org_nr": "551122-1234"
    }, 
    "name": "Testbutik", 
    "object": "merchant", 
    "address": {
        "city": "Stockholm", 
        "street": "Testgatan 13", 
        "zip": "123 25", 
        "country": "SWE"
    }, 
    "id": "1007", 
    "paywin": {
        "pay_methods": [
            "cards", 
            "banks"
        ], 
        "logo_path": null,
        "production": false
    }
}

The POST request takes one parameter, a merchant object that lists the values to set when the merchant is created.

Request Parameters

  
    
NAME
MANDATORY
DESCRIPTION

name
yes
Name of merchant

org_nr
yes
Organization number of merchant

street
yes
Street address of merchant

zip
yes
Zip code of merchant

city
yes
City of merchant

country
yes
Country of merchant, for example: SWE

pay_methods
yes
String array containing pay methods available for the merchants, possible string-values: cards and/or banks

secret
yes
String containing the secret word to calculate the SHA256 HMAC.

web
no*
Online sales?

moto
no*
Mail order telephone order (uncommon in Sweden but for instance hotels might use this)

card_present
no*
Sales from physical store

primary_business_face_to_face
no*
Yes if card present is yes

prev_card_acceptance
no*
Has merchant previously accepted cards

mcc
no*
Merchant Categroy Code (Used by banks to set prices, similar to SNI)

business_model_description
no*
Provide a clear description of what will be processed.

primary_contact_name
no*
 

primary_contact_phone
no*
 

primary_contact_name
no*
 

street
no*
Street address of headquarter

city
no*
City of headquarter

zip_code
no*
Post code number of headquarter

country
no*
Post code number of headquarter

annual_mc_sales_gt_1e6_dollar
no*
 

currency
no*
 

monthly_turnover_target
no*
Expected monthly processing volume

website_url
no*
Merchant’s processing URL

merchant_name_on_ch_statement
no*
Descriptor which will appear on the customer statement (D2I* plus max 18 characters)

iban
no*
Merchant IBAN (International Bank Account Number) to receving payments

bic
no*
Merchant's bank BIC code (Bank Identfier Code) for receiving payments

sni_2007
no*
Include only if not including MCC

sni
no*
Included if no including MCC and not using SNI (2007) and SNI standard is latest

account_data
no*
Merchant account number (bankgiro number), if not sending IBAN

account_type
no*
Merchant account number type, include if account_data field is used, Bankgiro/Plusgiro etc

* onboarding data is optional and is used to automatically qualify a merchant for payments and in this case the field is mandatory. Exceptions, only one of the fields mmc, sni, sni_2007 needs to be sent, BIC and IBAN must be included or account_data and account_type must be included.

Example request

{
    "info": {
        "org_nr": "551122-1234"
    }, 
    "name": "Testbutik", 
    "address": {
        "city": "Stockholm", 
        "street": "Testgatan 13", 
        "zip": "123 25", 
        "country": "SWE"
    }, 
    "paywin": {
        "pay_methods": [
            "cards", 
            "banks"
        ]
    }
}

Updating merchants

PUT /api/v1/merchants/{id}

Using curl

curl https://{domain}/api/v1/merchants/1007 -d '{"info": {"org_nr": "551122-4321"}, "name": "Testbutiken", "address": {"street": "Testgatan 15"}}' -H "Content-Type: application/json" {api_key}: -X PUT

Example Response

Status: 200 OK

{
    "info": {
        "org_nr": "551122-4321"
    }, 
    "name": "Testbutiken", 
    "object": "merchant", 
    "address": {
        "city": "Stockholm", 
        "street": "Testgatan 15", 
        "zip": "123 25", 
        "country": "SWE"
    }, 
    "id": "1007", 
    "paywin": {
        "pay_methods": [
            "cards", 
            "banks"
        ], 
        "logo_path": null,
        "production": false
    }
}

Request parameters

The PUT request takes one parameter, a merchant object that lists the values to update. All properties are optional.

  
    
  NAME
  MANDATORY
  DESCRIPTION

name
no
Name of merchant

org_nr
no
Organization number of merchant

street
no
Street address of merchant

zip
no
Zip code of merchant

city
no
City of merchant

  country
  no
  Country of merchant, for example: SWE

pay_methods
no
String array containing pay methods available for the merchants, possible string-values: cards and/or banks

secret
no
String containing the secret word to calculate the SHA256 HMAC.

web
no*
Online sales?

moto
no*
Mail order telephone order (uncommon in Sweden but for instance hotels might use this)

card_present
no*
Sales from physical store

primary_business_face_to_face
no*
Yes if card present is yes

prev_card_acceptance
no*
Has merchant previously accepted cards

mcc
no*
Merchant Categroy Code (Used by banks to set prices, similar to SNI)

business_model_description
no*
Provide a clear description of what will be processed.

primary_contact_name
no*
 

primary_contact_phone
no*
 

primary_contact_name
no*
 

street
no*
Street address of headquarter

city
no*
City of headquarter

zip_code
no*
Post code number of headquarter

country
no*
Post code number of headquarter

annual_mc_sales_gt_1e6_dollar
no*
 

currency
no*
 

monthly_turnover_target
no*
Expected monthly processing volume

website_url
no*
Merchant’s processing URL

merchant_name_on_ch_statement
no*
Descriptor which will appear on the customer statement (D2I* plus max 18 characters)

iban
no*
Merchant IBAN (International Bank Account Number) to receving payments

bic
no*
Merchant's bank BIC code (Bank Identfier Code) for receiving payments

sni_2007
no*
Include only if not including MCC

sni
no*
Included if no including MCC and not using SNI (2007) and SNI standard is latest

account_data
no*
Merchant account number (bankgiro number), if not sending IBAN

account_type
no*
Merchant account number type, include if account_data field is used, Bankgiro/Plusgiro etc

Example Request

{
    "info": {
        "org_nr": "551122-4321"
    }, 
    "name": "Testbutiken" 
    "address": {
        "street": "Testgatan 15" 
    }
}

Deleting merchants

DELETE /api/v1/merchants/{id}

Using curl

curl https://{domain}/api/v1/merchants/1007 -u {api_key}: -X DELETE

Example Response

Status: 204 No Content

Transactions

JSON format

NAME	PARENT	TYPE	READ-ONLY	DESCRIPTION
object		string	yes	Object type transaction
id		string	yes	Unique id for this transaction
paid_at		timestamp	yes	Timestamp when payment were completed, example: 2013-12-04 11:41:53.242431
amount		integer	yes	Total amount that was reserved
amount_settled		integer	yes	Amount that has been settled of the reserved amount
amount_refunded		string	yes	Amount that has been refunded of the settled amount
voided		boolean	yes	true if reserved amount has been voided, otherwise false.
settled		boolean	yes	true if reserved amount has been settled, otherwise false.
refunded		boolean	yes	true if settled amount has been refunded, otherwise false.
pay_method		string	yes	Possible values: card, bank or invoice.
currency		array	yes	Currency code according to ISO 4217, for example: SEK for Swedish krona.
test		boolean	yes	true if transactions is a test payment, otherwise false.
card		object	yes	Object containing details about the card used in the payment.
object	card	string	yes	Object type card.
first_name	card	string	yes	First name written on card.
last_name	card	string	yes	Last name written on card.
card_no	card	string	yes	First 6 and last 4 digits of card number.
exp_mon	card	string	yes	Expiry month of card.
exp_year	card	string	yes	Expiry year of card.
approval_code	card	string	yes	Approval code of authorization (reservation).
bank		object	yes	Object containing details about the bank used in the payment.
object	bank	string	yes	Object type bank.
name	bank	string	yes	Name of bank used in payment.
invoice		object	yes	Object containing details about the invoice used in the payment.
object	invoice	string	yes	Object type invoice.
invoice_number	invoice	string	yes	Invoice number in payment.
merchant		object	yes	Object containing merchant details. (More details in Merchants here)

Listing transactions

GET /api/v1/transactions

GET /api/v1/merchants/{id}/transactions

Transactions are ordered chronologically by created date, from newest to oldest.

Using curl

curl https://{domain}/api/v1/transactions -u {api_key}:

Filter

?offset=0&limit=1

Example Response

Status: 200 OK

{
    "total_count": 21, 
    "object": "list", 
    "data": [
        {
            "merchant": {
                "object": "merchant",
                ...
            }, 
            "amount_refunded": 0, 
            "refunded": false, 
            "object": "transaction", 
            "voided": false, 
            "currency": "sek", 
            "paid_at": "2013-12-04 11:41:53.242431", 
            "invoice": {}, 
            "id": "529f06f1701c21661900008c", 
            "card": {
                "first_name": "-", 
                "last_name": "-", 
                "object": "card", 
                "exp_mon": "01", 
                "approval_code": "12345", 
                "exp_year": "22", 
                "card_no": "444433......1111"
            }, 
            "customer": {}, 
            "pay_method": "card", 
            "amount_settled": 0, 
            "amount": 17700, 
            "bank": {}, 
            "test": true, 
            "settled": false
        },
        ...
    ]
}

Getting transactions

GET /api/v1/transactions/{id}

GET /api/v1/merchants/{mid}/transactions/{id}

Using curl

curl https://{domain}/api/v1/merchants/1007/transactions/ \
   -u {api_key}:

Example Response

Status: 200 OK

{
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "amount_refunded": 0, 
    "refunded": false, 
    "object": "transaction", 
    "voided": false, 
    "currency": "sek", 
    "paid_at": "2013-12-04 11:41:53.242431", 
    "invoice": {}, 
    "id": "529f06f1701c21661900008c", 
    "card": {
        "first_name": "-", 
        "last_name": "-", 
        "object": "card", 
        "exp_mon": "01", 
        "approval_code": "12345", 
        "exp_year": "22", 
        "card_no": "444433......1111"
    }, 
    "customer": {}, 
    "pay_method": "card", 
    "amount_settled": 0, 
    "amount": 17700, 
    "bank": {}, 
    "test": true, 
    "settled": false
}

Subscriptions

JSON format

NAME	PARENTTYPE	READ-ONLY	DESCRIPTION
object	string	yes	Object type subscription
object	string	yes	Object type subscription
active	boolean	no	true if this is an active subscription, false if inactive.
card	object	yes	Object containing card details used in subscription. (More details of card format: Transaction)
merchant	object	yes	Object containing merchant details. (More details here: Merchants)

Listing subscriptions

GET /api/v1/subscriptions GET /api/v1/merchants/{id}/subscriptions

Subscriptions are ordered chronologically by created date, from newest to oldest.

Using curl

curl https://{domain}/api/v1/subscriptions -u {api_key}:

Filter

?offset=0&limit=1

Example Response

Status: 200 OK

{
    "total_count": 10, 
    "object": "list", 
    "data": [
        {
            "active": true, 
            "merchant": {
                "object": "merchant",
                ...
            }, 
            "object": "subscription", 
            "id": "109", 
            "card": {
                "object": "card", 
                ...
            }
        },
        ...
    ]
}

Getting subscriptions

GET /api/v1/subscriptions/{id} GET /api/v1/merchants/{mid}/subscriptions/{id}

Using curl

curl https://{domain}/api/v1/subscriptions/1007 -u {api_key}:

Example Response

Status: 200 OK

{
    "active": true, 
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "object": "subscription", 
    "id": "109", 
    "card": {
        "object": "card", 
        ...
    }
}

Updating subscriptions

PUT /api/v1/merchants/{mid}/subscriptions/{id}

Using curl

curl https://{domain}/api/v1/merchants/{mid}/subscriptions/{id} -d '{"active": false}' -H "Content-Type: application/json" {api_key}: -X PUT

Example Response

Status: 200 OK

{
    "active": false, 
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "object": "subscription", 
    "id": "109", 
    "card": {
        "object": "card", 
        ...
    }
}

Request parameters

The PUT request takes one parameter, a merchant object that lists the values to update. All properties are optional.

  
  NAME
  MANDATORY
  DESCRIPTION

  active
  no
  
    Possible values true or false to enable or disable this subscription.

{
    "active": false
}

Example request

Deleting subscriptions

DELETE /api/v1/merchants/{mid}/subscriptions/{id}

Using curl

curl https://{domain}/api/v1/subscriptions/{id} -u {api_key}: -X DELETE

Status: 204 No Content

Example response

Users

JSON format

NAME	PARENTTYPE	READ-ONLY	DESCRIPTION
object	string	yes	Object type user
id	string	yes	Unique id for this user.
username	string	no	Username for the user.
real_name	string	no	Real name of this user.
last_logged_in	timestamp	yes	Timestamp when user was last logged in.
password	string	no	Password for the user.
merchant	object	yes	Object containing merchant details. (More details here: Merchants)

Listing users

GET /api/v1/users

GET /api/v1/merchants/{id}/users

Users are ordered chronologically by created date, from newest to oldest.

Using curl

curl https://{domain}/api/v1/users -u {api_key}:

Filter

?offset=0&limit=1

Example Response

Status: 200 OK

{
    "total_count": 10, 
    "object": "list", 
    "data": [
        {
            "username": "testbutik", 
            "merchant": {
                "object": "merchant",
                ...
            }, 
            "object": "user", 
            "real_name": "Kalle Andersson", 
            "id": 35, 
            "last_logged_in": null
        },
        ...
    ]
}

Getting users

GET /api/v1/users/{id}

GET /api/v1/merchants/{mid}/users/{id}

Using curl

curl https://{domain}/api/v1/users/1007 -u {api_key}:

Example Response

Status: 200 OK

{
    "username": "testbutik", 
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "object": "user", 
    "real_name": "Kalle Andersson", 
    "id": 35, 
    "last_logged_in": null
}

Creating users

POST /api/v1/merchants/{mid}/users

Using curl

curl https://{domain}/api/v1/users/ -d '{"username": "testbutik", "real_name": "Kalle Andersson", "password": "c7JkvLRVPg"}' -H "Content-Type: application/json" {api_key}: -X POST

Example Response

Status: 201 Created
Location: https://{domain}/api/v1/merchants/{mid}/users/{id}

{
    "username": "testbutik", 
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "object": "user", 
    "real_name": "Kalle Andersson", 
    "id": 35, 
    "last_logged_in": null
}

The POST request takes one parameter, a merchant object that lists the values to set when the merchant is created.

Request parameters

  
    
NAME
TYPE
DEFAULT
DESCRIPTION

backdrop
boolean or the string 'static'
true
Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.

{
    "username": "testbutik",
    "real_name": "Kalle Andersson",
    "password": "c7JkvLRVPg"
}

Example request

Updating users

PUT /api/v1/merchants/{mid}/users/{id}

Using curl

curl https://{domain}/api/v1/merchants/{mid}/users/{id} -d '{"real_name": "Kalle Eriksson", "password": "p85jePNABa"}' -H "Content-Type: application/json" {api_key}: -X PUT

Example Response

Status: 200 OK

{
    "username": "testbutik", 
    "merchant": {
        "object": "merchant",
        ...
    }, 
    "object": "user", 
    "real_name": "Kalle Eriksson", 
    "id": 35, 
    "last_logged_in": null
}

The PUT request takes one parameter, a merchant object that lists the values to update. All properties are optional.

Request parameters

  
    
NAME
TYPE
DEFAULT
DESCRIPTION

backdrop
boolean or the string 'static'
true
Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.

Deleting users

Example request

{
    "real_name": "Kalle Eriksson",
    "password": "p85jePNABa"
}

DELETE /api/v1/merchants/{mid}/users/{id}

Using curl

curl https://{domain}/api/v1/users/{id} -u {api_key}: -X DELETE

Example Response

Status: 204 No Content

Files

Listing files

Using curl

curl https://{domain}/api/v1/file/ -u {api_key}:

Example Response

Status: 200 OK
{
    "files": [
         {
            "creation": "2018-09-19 01:09:05:635", 
            "lastaccess": "2018-09-19 06:09:28:510", 
            "expires": "2018-09-26 01:09:05:635",
            "filename": "report-241103000011991-20180915-day.csv"
         },
         {
            "creation": "2018-09-19 01:09:12:463",
            "lastaccess": "2018-09-19 06:09:28:558", 
            "expires": "2018-09-26 01:09:12:463", 
            "filename": "report-241103000011990-20180915-day.csv"
         },
         ...
     ]
}

Download file

Using curl

curl https://{domain}/api/v1/file/{file-name} -u {api_key}:

Example Response

Status: 200 OK
{binary file data}

Upload file

Using curl

curl https://{domain}/api/v1/file/{file-name} -T {file-name} -u {api_key}:

Example Response

Status: 200 Ok