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_methodspaywinarrayno String 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.
onboarding_data-objectyesOptional section used for qualifying merchants for payments
webonboarding_datastringnoonline sales?
motoonboarding_datastringno mail order telephone order (uncommon in Sweden but for instance hotels might use this)
card_presentonboarding_datastringnosales from physical store
primary_business_face_to_faceonboarding_datastringnoyes if card present is yes
prev_card_acceptance onboarding_data stringnoHas merchant previously accepted cards
mcconboarding_datastringnoMerchant Categroy Code (Used by banks to set prices, similar to SNI)
business_model_descriptiononboarding_datastringnoProvide a clear description of what will be processed.
primary_contact_nameonboarding_datastringno
primary_contact_phoneonboarding_datastringno
primary_contact_nameonboarding_datastringno
streetonboarding_datastringnostreet address of headquarter
cityonboarding_datastringnocity of headquarter
zip_codeonboarding_datastringnopost code number of headquarter
countryonboarding_datastringnopost code number of headquarter
annual_mc_sales_gt_1e6_dollaronboarding_datastringno
currencyonboarding_datastringno
monthly_turnover_targetonboarding_datastringnoexpected monthly processing volume
website_urlonboarding_datastringnomerchant’s processing URL
merchant_name_on_ch_statementonboarding_datastringnodescriptor which will appear on the customer statement (D2I* plus max 18 characters)
ibanonboarding_datastringnomerchant IBAN (International Bank Account Number) to receving payments
biconboarding_datastringnomerchant's bank BIC code (Bank Identfier Code) for receiving payments
sni_2007onboarding_datastringnoinclude only if not including MCC
snionboarding_datastringnoincluded if no including MCC and not using SNI (2007) and SNI standard is latest
account_dataonboarding_datastringnomerchant account number (bankgiro number), if not sending IBAN
account_typeonboarding_datastringno merchant account number type, include if account_data field is used, Bankgiro/Plusgiro etc

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_methodsyes String 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.
webno*online sales?
motono*mail order telephone order (uncommon in Sweden but for instance hotels might use this)
card_presentno*sales from physical store
primary_business_face_to_faceno*yes if card present is yes
prev_card_acceptanceno*Has merchant previously accepted cards
mccno*Merchant Categroy Code (Used by banks to set prices, similar to SNI)
business_model_descriptionno*Provide a clear description of what will be processed.
primary_contact_nameno*
primary_contact_phoneno*
primary_contact_nameno*
streetno*street address of headquarter
cityno*city of headquarter
zip_codeno*post code number of headquarter
countryno*post code number of headquarter
annual_mc_sales_gt_1e6_dollarno*
currencyno*
monthly_turnover_targetno*expected monthly processing volume
website_urlno*merchant’s processing URL
merchant_name_on_ch_statementno*descriptor which will appear on the customer statement (D2I* plus max 18 characters)
ibanno*merchant IBAN (International Bank Account Number) to receving payments
bicno*merchant's bank BIC code (Bank Identfier Code) for receiving payments
sni_2007no*include only if not including MCC
snino*included if no including MCC and not using SNI (2007) and SNI standard is latest
account_datano*merchant account number (bankgiro number), if not sending IBAN
account_typeno*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.

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.
webno*online sales?
motono*mail order telephone order (uncommon in Sweden but for instance hotels might use this)
card_presentno*sales from physical store
primary_business_face_to_faceno*yes if card present is yes
prev_card_acceptanceno*Has merchant previously accepted cards
mccno*Merchant Categroy Code (Used by banks to set prices, similar to SNI)
business_model_descriptionno*Provide a clear description of what will be processed.
primary_contact_nameno*
primary_contact_phoneno*
primary_contact_nameno*
streetno*street address of headquarter
cityno*city of headquarter
zip_codeno*post code number of headquarter
countryno*post code number of headquarter
annual_mc_sales_gt_1e6_dollarno*
currencyno*
monthly_turnover_targetno*expected monthly processing volume
website_urlno*merchant’s processing URL
merchant_name_on_ch_statementno*descriptor which will appear on the customer statement (D2I* plus max 18 characters)
ibanno*merchant IBAN (International Bank Account Number) to receving payments
bicno*merchant's bank BIC code (Bank Identfier Code) for receiving payments
sni_2007no*include only if not including MCC
snino*included if no including MCC and not using SNI (2007) and SNI standard is latest
account_datano*merchant account number (bankgiro number), if not sending IBAN
account_typeno*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-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: card, bank 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