Introduction

The 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

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 info 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.

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.

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.
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
secret no String 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

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 crones.
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 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

Name parent type 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
}
Request parameters

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

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

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