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.

Using curl
curl -u {api_key}: https://{yourdomain}/api/v1/...
Example
curl -u 5410aa9585216d14eafad502: https://pay.yourcompany.com/api/v1/merchants

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

Nameparenttyperead-onlydescription
id-stringyesUnique id for this merchant
name-stringnoName of merchant
info-objectyesObject containing information regarding the merchant
org_nrinfostringnoOrganization number of merchant
address-objectyesObject containing address information
streetaddressstringnoStreet address of merchant
zipaddressstringnoZip code of merchant
cityaddressstringnoCity of merchant
countryaddressstringnoCountry of merchant, for example: SWE
paywin-objectyesObject containing paywin settings
pay_methodspaywinarraynoString array containing pay methods available for the merchants, possible string-values: cards and/or banks
secretpaywinstringnoString containing the secret word to calculate the SHA256 HMAC.
logo_pathpaywinstringyesName of uploaded logo-file.
productionpaywinbooleanyestrue if mapped for card payments and ready for live payments.

Listing merchants

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
            }
        },
        ...
    ]
}

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

Creating merchants

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
    }
}
Request parameters

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

NameMandatorydescription
nameyesName of merchant
org_nryesOrganization number of merchant
streetyesStreet address of merchant
zipyesZip code of merchant
cityyesCity of merchant
countryyesCountry of merchant, for example: SWE
pay_methodsyesString array containing pay methods available for the merchants, possible string-values: cards and/or banks
secretyesString containing the secret word to calculate the SHA256 HMAC.
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.

NameMandatorydescription
namenoName of merchant
org_nrnoOrganization number of merchant
streetnoStreet address of merchant
zipnoZip code of merchant
citynoCity of merchant
countrynoCountry of merchant, for example: SWE
secretnoString containing the secret word to calculate the SHA256 HMAC.
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

Nameparenttyperead-onlydescription
object-stringyesObject type transaction
id-stringyesUnique id for this transaction
paid_at-timestampyesTimestamp when payment were completed, example: 2013-12-04 11:41:53.242431
amount-integeryesTotal amount that was reserved
amount_settled-integeryesAmount that has been settled of the reserved amount
amount_refunded-stringyesAmount that has been refunded of the settled amount
voided-booleanyestrue if reserved amount has been voided, otherwise false.
settled-booleanyestrue if reserved amount has been settled, otherwise false.
refunded-booleanyestrue if settled amount has been refunded, otherwise false.
pay_method-stringyesPossible values: cardbank or invoice.
currency-arrayyesCurrency code according to ISO 4217, for example: SEK for Swedish krona.
test-booleanyestrue if transactions is a test payment, otherwise false.
card-objectyesObject containing details about the card used in the payment.
objectcardstringyesObject type card.
first_namecardstringyesFirst name written on card.
last_namecardstringyesLast name written on card.
card_nocardstringyesFirst 6 and last 4 digits of card number.
exp_moncardstringyesExpiry month of card.
exp_yearcardstringyesExpiry year of card.
approval_codecardstringyesApproval code of authorization (reservation).
bank-objectyesObject containing details about the bank used in the payment.
objectbankstringyesObject type bank.
namebankstringyesName of bank used in payment.
invoice-objectyesObject containing details about the invoice used in the payment.
objectinvoicestringyesObject type invoice.
invoice_numberinvoicestringyesInvoice number in payment.
merchant-objectyesObject containing merchant details. (More details here: Merchants)

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 parent type read-only description
object - string yes Object type subscription
id - string yes Unique id for this 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.
Example request
{
    "active": false
}

Deleting subscriptions

DELETE /api/v1/merchants/{mid}/subscriptions/{id}
Using curl
curl https://{domain}/api/v1/subscriptions/{id} -u {api_key}: -X DELETE
Example Response
Status: 204 No Content

Users

JSON format

Nameparenttyperead-onlydescription
object-stringyesObject type user
id-stringyesUnique id for this user.
username-stringnoUsername for the user.
real_name-stringnoReal name of this user.
last_logged_in-timestampyesTimestamp when user was last logged in.
password-stringnoPassword for the user.
merchant-objectyesObject 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
}
Request parameters

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

Nametypedefaultdescription
backdropboolean or the string 'static'trueIncludes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
Example request
{
    "username": "testbutik",
    "real_name": "Kalle Andersson",
    "password": "c7JkvLRVPg"
}

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
}
Request parameters

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

Nametypedefaultdescription
backdropboolean or the string 'static'trueIncludes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
Example request
{
    "real_name": "Kalle Eriksson",
    "password": "p85jePNABa"
}

Deleting users

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