Credentials

Hash key using the HMAC method with SHA-512. This is used for verifying that the request is correct and fom a valid server. Key Billmate key. Argument Data array as json encoded string.

version

false

string

Version of the Billmate API. Currently 2.1.7. Currently not mandatory, but helps when debugging in logs.

client

false

string

A unique name to identify client and version of client. Can be set by a plugin developer.

language

false

string

This is the language of the api, this will decide what language we will return for example error messages. Language codes used according to ISO 639-1, Currently supported sv, en.

serverdata

false

string

Web shop server data. For example user agent of the customer browser. Very useful for debugging.

time

false

decimal

Time when request was submitted. Time format is “PHP microtime”, which is seconds since the Unix Epoch (00000 January 1, 1970 GMT). If used, then logs will show “client time”, which is the time it takes for the request to reach Billmate servers. Good for debugging of delays.

getAddress is used for retrieving a person/company’s address from a personal or organization number. getAddress API is only permitted to be used together with Billmate payments. The return is an array in JSON format with the values of the person/company details or an error. You can find all the possible errors in below. To use addPayment methods factoring or part payment, the person/company who purchase the product must have the same invoice address and delivery address as the address returned from getAddress.

Request parameters

Data

Property

Required

Type

Description

pno

true

string

Social security number (SSN) or organisation number. Sweden Sent as YYMMDD-XXXX, it can be sent with or without “-” and with or without the two first numbers (19 or 20) in the year.

country

false

string

Country code for the pno according to ISO 3166-1 alpha-2, e.g. SE, DK, NO, GB. Default is SE if not submitted.

getPaymentplans is used for fetching part payment plans and for calculating monthly cost for part payments. Fetching paymentplans is normally used in admin panel for fetching an updated part payment plan and save it locally for calculation of monthly cost. Monthly cost for available plans can also be fetched for every checkout using getPaymentplans with an amount, totalwithtax.

Request parameters

Data

Property

Required

Type

Description

currency

true

string

Currency code to be used for the payment according to ISO 4217. Currently supported: SEK.

country

true

string

Country code for the country where purchase is made (normally store location) according to ISO 3166-1 alpha-2, e.g. SE, DK, NO, GB.

language

true

string

Language code for the language used on the invoice/recipt according to ISO 639-1. Currently supported: sv.

totalwithtax

true

int

The monthly cost with tax for each payment plan will be calculated from the total payment value with tax. If not submitted, all payment plans are returned. NOTE: Total payment including tax needs to be in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

Function

Property

Required

Type

Description

function

true

string

The function name to be used, for this page it’s getPaymentplans

Response body

Data

Property

Type

Description

paymentplanid

int

Part payment id of the payment plan.

description

string

Description of the selected part payment plan

nbrofmonths

int

The number of months for this part payment plan

startfee

int

The fee debited for start up of this part payment plan. Given in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

handlingfee

int

The invoice fee debited per month for this part payment plan. Given in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

minamount

int

The minimum purchase amount for this part payment plan. Given in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

maxamount

int

The maximum purchase amount for this payment plan. Given in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

country

string

The country code of the country of sales for the part payment plan

type

int

This is used to determine what type the part payment is and which calculation method is to be used. Type values: 0 = Campaign, 1 = Normal part payment

expirydate

string

The part payment plan last expiry date in the format YYYY-MM-DD

interestrate

dec

The interest rate in percentage for this part payment plan

currency

string

The currency code of the part payment plan

language

string

The language code of the part payment plan

totalfee

int

The total cost with tax for the payment plan given by the totalwithtax amount in request. Total is including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

monthlycost

int

The monthly total with tax for the payment plan given by the totalwithtax amount in request. Total is including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

Request parameters

Data

Cart

Property

Required

Type

Description

total.withtax

true

int

Total payment including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Note: Total Payment with Tax must be equal to Total Payment Excluding Tax + Total Tax + Rounding. This is a double check to make sure no rounding errors are present and payment always will be correct.

addPayment is used for creating payments. Note: For card and bank payment, a payment url is returned to which the customer must be redirected to finalize the payment. Note: For Factoring and Part Payment, billing and shipping address must be same as registered address (swedish: bokföringsadress) to be approved.

Payment Info

Country code for the country where purchase is made (normally store location) according to ISO 3166-1 alpha-2, e.g. SE, DK, NO,GB.

language

true

string

Language code for the language used on the invoice/recipt according to ISO 639-1, Currently supported: sv, da, no, en.

orderid

true

string

A unique order id generated by the shop as a reference.

currency

true

string

Currency code to be used for the payment according to ISO 4217. Currently supported: SEK, DKK, NOK, GBP, EUR, USD. Note: Method=16 (Bank) currently only accepts SEK and Method=4 (Part Payment) currently only accepts SEK.

autoactivate

false

string

Flag showing if the payment should be auto activated, thus if set, payment is finalized and no activatePayment command is required. For invoice, service and partpayment, autoactivation=1 locks invoice, sends it to Billmate. For invoice and service an invoice will be sent to the given customer email. For card/bank payment, autoactivate=1 captures amount immediately. Default=0. You can also enter a date for when the payment should be activated e.g. 2015-02-28.

logo

false

string

Change logo for the payment. You will find the reference to your logo in your billmate online account. You will find it in Settings -> Company details -> Company logo. The reference to be used is the file name e.g. Logo1.jpg. If left empty the standard logo will be used.

paymentplanid

false

int

Paymentplan id of the selected part payment plan. Required if paymentmethod is PartPayment. If you wish to use a different currency for part payment than SEK, please contact us by clicking on this link.

Card

Property

Required

Type

Description

promptname

false

int

Flag indicating if name should be prompted in payment window. Only valid for card payments (method=8). Default=0 (no prompt).

3dsecure

false

int

Flag indicating if 3D-Secure should be used. Only valid for card payments (method=8). Default=1 (use 3D-Secure).

recurring

false

int

Flag indicating if card payment is or should be saved to make it possible to do recurring payments, like monthly subscriptions. If set, then after first payment has been made, an addPayment call will make another card payment automatically. Requires a special aquirer agreement (inlösenavtal). Only valid for card payments (method=8). Default=0 (no recurring payment). Notice that this is only needed for the initial recurring payment.

recurringnr

false

int

Payment number (datanumber) received from first purchase for making a recurring payment.

accepturl

false

string

Url to which the customer is redirected after a completed payment. Data returned is same as for addPayment defined below.

cancelurl

false

string

Url to which the customer is redirected after a failed or cancelled payment. Data returned is error message and code as for addPayment defined below.

returnmethod

false

string

Http return method to accepturl, cancelurl and callbackurl. Default is ‘POST’, but can be set to ‘GET’ instead.

callbackurl

false

string

Url to which callback data is sent after the customer has succesfully completed a card or bank payment. Data returned is same as for addPayment defined below and for accepturl. Callback is made same time as accepturl, thus it can’t be assumed that callback data will arrive before accepturl data. No response is required to a callback request, the data just has to be received. If callback data is not received, Billmate server will try to send callback data again once a minute first 10 minutes, once an hour first 10 hours, once a day first 7 days, then finally once a month for next 3 months.

Payment Info

Property

Required

Type

Description

paymentdate

false

date

Payment date in invoice/receipt on format YYYY-MM-DD. Default is current date.

paymentterms

false

int

Payment terms field in invoice/receipt. Given in number of days.

yourreference

false

string

Your reference field in invoice/receipt.

ourreference

false

string

Our reference field in invoice/receipt.

projectname

false

string

Project name field in invoice/receipt.

delivery

false

string

Delivery method. Post, etc.

deliveryterms

false

string

Delivery terms field in invoice/receipt. FOB, etc.

autocredit

false

boolean

If this is set to true, then if the invoice is not paid before the duedate, the invoice will be automatically credited. Default is false.

Customer

Property

Required

Type

Description

nr

false

int

Customer number. If not given, next available customer number in Billmate will be assigned.

pno

false

string

Swedish social security number or swedish organization number. Sent as YYMMDD-XXXX, it can be sent with or without “-” and with or without the two first numbers (19 or 20) in the year. Mandatory field for Factoring and PartPayment methods, but not for receipt, card and bank payments.

Customer Billing

Property

Required

Type

Description

email

true

string

Billing email, required for all methods (except card/bank).

firstname

false

string

Firstname, mandatory if factoring or partpayment.

lastname

false

string

Lastname, mandatory if factoring or partpayment.

company

false

string

Company name if applicable, mandatory if company organisation number is given for factoring or partpayment.

zip

false

string

Zipcode, mandatory if factoring or partpayment.

city

false

string

City, mandatory if factoring or partpayment.

phone

false

string

Phone number.

company

false

string

Company name if applicable.

street

false

string

Street.

street2

false

string

Second row of Street if required.

zip

false

string

Zipcode.

Customer Shipping

Property

Required

Type

Description

firstname

false

string

Firstname, mandatory if factoring or partpayment.

lastname

false

string

Lastname, mandatory if factoring or partpayment.

company

false

string

Company name if applicable, mandatory if company organisation number is given for factoring or partpayment.

zip

false

string

Zipcode, mandatory if factoring or partpayment.

city

false

string

City, mandatory if factoring or partpayment.

phone

false

string

Phone number.

company

false

string

Company name if applicable.

street

false

string

Street.

street2

false

string

Second row of Street if required.

zip

false

string

Zipcode.

Articles

Property

Required

Type

Description

articles[0].taxrate

true

dec

First article tax rate in percent.

articles[0].withouttax

true

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Mandatory since at least one article is required to add up to total.withouttax. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

articles[0].artnr

false

string

First article number.

articles[0].title

false

string

First article description.

articles[0].quantity

false

dec

First article quantity.

articles[0].aprice

false

dec

First article unit price without tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

articles[0].discount

false

dec

First article discount in %.

articles[1].artnr

false

string

Second article number.

articles[1].title

false

string

Second article description.

articles[1].quantity

false

dec

Second article quantity.

articles[1].aprice

false

dec

Second article unit price without tax.

articles[1].taxrate

false

dec

Second article tax rate in percent.

articles[1].discount

false

dec

Second article discount in %.

articles[1].withouttax

false

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

Cart

Property

Required

Type

Description

total.withouttax*

true

int

Total payment excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will be checked against summation of all articles[x].withouttax, handlingcharge.withouttax and shipping.withouttax. If not matching values, an error will be returned.

total.tax

true

int

Total tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

total.withtax

true

int

Total payment including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Note Total Payment with Tax must be equal to Total Payment Excluding Tax + Total Tax + Rounding. This is a double check to make sure no rounding errors are present and payment always will be correct.

handling.withouttax

false

dec

Handling charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

handling.taxrate

false

dec

Handling vat rate in %.

shipping.withouttax

false

dec

Shipping charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

shipping.taxrate

false

dec

Shipping vat rate in %.

total.rounding

false

dec

Rounding in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

creditPayment is used for crediting payments. The original payment could be credited fully or partially. If partcredit flag is true, then no articles are required to be sent since complete invoice is credited. If partcredit flag is true, then add all artices that should be credited. Note that all amounts in a credit invoice have same sign as in original invoice, thus aprice and withouttax are positive values. Note: Discount on total payment/invoice is sent as an article with negative aprice and negative withouttax value. If multiple tax rates are used in the invoice, the discount tax (negative) and discount tax rate (positive) has to be calculated for each standard tax rate and be given as parameters. Thus, discount tax rate has to be fixed to a standard tax rate (i.e. 6%,12%,25%) and can not be given as a decimal value like 12.6%.

Request parameters

Data

Property

Required

Type

Description

number

true

int

The payment number of the payment you wish to credit.

partcredit

false

Boolean

If part credit, then articles that should be credited and the cart needs to be specified as below. If part credit is false, then full amount is always credited. Default is false.

Articles

Property

Required

Type

Description

articles[0].taxrate

true

dec

First article tax rate in percent.

articles[0].withouttax

true

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Mandatory since at least one article is required to add up to total.withouttax. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

articles[0].artnr

false

string

First article number.

articles[0].title

false

string

First article description.

articles[0].quantity

false

dec

First article quantity.

articles[0].aprice

false

dec

First article unit price without tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

articles[0].discount

false

dec

First article discount in %.

articles[1].artnr

false

string

Second article number.

articles[1].title

false

string

Second article description.

articles[1].quantity

false

dec

Second article quantity.

articles[1].aprice

false

dec

Second article unit price without tax.

articles[1].taxrate

false

dec

Second article tax rate in percent.

articles[1].discount

false

dec

Second article discount in %.

articles[1].withouttax

false

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

Cart

Property

Required

Type

Description

total.withouttax*

true

int

Total payment excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will be checked against summation of all articles[x].withouttax, handlingcharge.withouttax and shipping.withouttax. If not matching values, an error will be returned.

total.tax

true

int

Total tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

total.withtax

true

int

Total payment including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Note Total Payment with Tax must be equal to Total Payment Excluding Tax + Total Tax + Rounding. This is a double check to make sure no rounding errors are present and payment always will be correct.

handling.withouttax

false

dec

Handling charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

handling.taxrate

false

dec

Handling vat rate in %.

shipping.withouttax

false

dec

Shipping charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

shipping.taxrate

false

dec

Shipping vat rate in %.

total.rounding

false

dec

Rounding in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

updatePayment is used for updating payments. NOTE: You can only update a payment that has status “Created”, which has not yet been locked (sent). If the payment is locked (any other status), then you will have to use CreditPayment instead to credit the original payment and then create a new correct payment with addPayment. NOTE: For card payment, you cannot update the payment to a higher value than was originally reserved. NOTE: It is not allowed to change payment method of the invoice. To change payment method, original payment has to be cancelled and a new payment has to be created.

Request parameters

Data

Country code for the country where purchase is made (normally store location) according to ISO 3166-1 alpha-2, e.g. SE, DK, NO,GB.

language

true

string

Language code for the language used on the invoice/recipt according to ISO 639-1, Currently supported: sv, da, no, en.

orderid

true

string

A unique order id generated by the shop as a reference.

currency

true

string

Currency code to be used for the payment according to ISO 4217. Currently supported: SEK, DKK, NOK, GBP, EUR, USD. Note: Method=16 (Bank) currently only accepts SEK and Method=4 (Part Payment) currently only accepts SEK.

autoactivate

false

string

Flag showing if the payment should be auto activated, thus if set, payment is finalized and no activatePayment command is required. For invoice, service and partpayment, autoactivation=1 locks invoice, sends it to Billmate. For invoice and service an invoice will be sent to the given customer email. For card/bank payment, autoactivate=1 captures amount immediately. Default=0. You can also enter a date for when the payment should be activated e.g. 2015-02-28.

logo

false

string

Change logo for the payment. You will find the reference to your logo in your billmate online account. You will find it in Settings -> Company details -> Company logo. The reference to be used is the file name e.g. Logo1.jpg. If left empty the standard logo will be used.

paymentplanid

false

int

Paymentplan id of the selected part payment plan. Required if paymentmethod is PartPayment. If you wish to use a different currency for part payment than SEK, please contact us by clicking on this link.

Payment Info

Property

Required

Type

Description

paymentdate

false

date

Payment date in invoice/receipt on format YYYY-MM-DD. Default is current date.

paymentterms

false

int

Payment terms field in invoice/receipt. Given in number of days.

yourreference

false

string

Your reference field in invoice/receipt.

ourreference

false

string

Our reference field in invoice/receipt.

projectname

false

string

Project name field in invoice/receipt.

delivery

false

string

Delivery method. Post, etc.

deliveryterms

false

string

Delivery terms field in invoice/receipt. FOB, etc.

autocredit

false

boolean

If this is set to true, then if the invoice is not paid before the duedate, the invoice will be automatically credited. Default is false.

Customer

Property

Required

Type

Description

nr

false

int

Customer number. If not given, next available customer number in Billmate will be assigned.

pno

false

string

Swedish social security number or swedish organization number. Sent as YYMMDD-XXXX, it can be sent with or without “-” and with or without the two first numbers (19 or 20) in the year. Mandatory field for Factoring and PartPayment methods, but not for receipt, card and bank payments.

Customer Billing

Property

Required

Type

Description

email

true

string

Billing email, required for all methods (except card/bank).

firstname

false

string

Firstname, mandatory if factoring or partpayment.

lastname

false

string

Lastname, mandatory if factoring or partpayment.

company

false

string

Company name if applicable, mandatory if company organisation number is given for factoring or partpayment.

zip

false

string

Zipcode, mandatory if factoring or partpayment.

city

false

string

City, mandatory if factoring or partpayment.

phone

false

string

Phone number.

company

false

string

Company name if applicable.

street

false

string

Street.

street2

false

string

Second row of Street if required.

zip

false

string

Zipcode.

Customer Shipping

Property

Required

Type

Description

firstname

false

string

Firstname, mandatory if factoring or partpayment.

lastname

false

string

Lastname, mandatory if factoring or partpayment.

company

false

string

Company name if applicable, mandatory if company organisation number is given for factoring or partpayment.

zip

false

string

Zipcode, mandatory if factoring or partpayment.

city

false

string

City, mandatory if factoring or partpayment.

phone

false

string

Phone number.

company

false

string

Company name if applicable.

street

false

string

Street.

street2

false

string

Second row of Street if required.

zip

false

string

Zipcode.

Articles

Property

Required

Type

Description

articles[0].taxrate

true

dec

First article tax rate in percent.

articles[0].withouttax

true

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Mandatory since at least one article is required to add up to total.withouttax. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

articles[0].artnr

false

string

First article number.

articles[0].title

false

string

First article description.

articles[0].quantity

false

dec

First article quantity.

articles[0].aprice

false

dec

First article unit price without tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

articles[0].discount

false

dec

First article discount in %.

articles[1].artnr

false

string

Second article number.

articles[1].title

false

string

Second article description.

articles[1].quantity

false

dec

Second article quantity.

articles[1].aprice

false

dec

Second article unit price without tax.

articles[1].taxrate

false

dec

Second article tax rate in percent.

articles[1].discount

false

dec

Second article discount in %.

articles[1].withouttax

false

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

Cart

Property

Required

Type

Description

total.withouttax*

true

int

Total payment excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will be checked against summation of all articles[x].withouttax, handlingcharge.withouttax and shipping.withouttax. If not matching values, an error will be returned.

total.tax

true

int

Total tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

total.withtax

true

int

Total payment including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Note Total Payment with Tax must be equal to Total Payment Excluding Tax + Total Tax + Rounding. This is a double check to make sure no rounding errors are present and payment always will be correct.

handling.withouttax

false

dec

Handling charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

handling.taxrate

false

dec

Handling vat rate in %.

shipping.withouttax

false

dec

Shipping charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

shipping.taxrate

false

dec

Shipping vat rate in %.

total.rounding

false

dec

Rounding in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

Send update Javascript event. Note that no unlock event is required to be sent after the update JS event. The Checkout handles this by itself.

User change shipping method, articles or any other order information on the hosting iframe hosting system. Client should perform the same events as in 4.a if you need to update the Checkout.

User selects a different shipping adress. Hosting system should perform the same events as in 4.a if you need to update the Checkout.

User confirms order, third party application might be needed to confirm the order. Checkout sends JS event to client (browser) to open a specific url (app). Example: BankID or Swish. Note: If user is redirected to a third-party app or website and cancels the order they could be redirected to the provided cancelURL.

Order is confirmed

Accepturl User is redirected to the provided acceptURL using the requested return method. Client should perform necessary actions to fulfill the order.

CallbackClient (server) receives a request from Billmate Checkout API with the order status. Client should perform necessary actions to fulfill the order.

Important notes regarding order is confirmed. Best practice is to perform a getPaymentinfo to validate the order with Billmate API. There is no guarantee that the user will reach the accepturl. Callback could in theory reach the client before the user gets redirected to the accepturl.

Role definitions

Client The complete system who integrates Billmate Checkout.

Client (server) Back-end who communicates with the Billmate Checkout API.

Request

- checkoutdata

Flags that sets if company details are enabled in the checkout. Default is false.

showPhoneOnDelivery

false

boolean

Indicates if phone number for delivery should be requested. Default is false.

- PaymentData

Property

Required

Type

Description

currency

true

string

Currency code to be used for the payment according to ISO 4217. Currently supported: SEK, DKK, NOK, GBP, EUR, USD. Note: Method=16 (Bank) currently only accepts SEK and Method=4 (Part Payment) currently only accepts SEK.

language

true

string

Language code for the language used on the invoice/recipt according to ISO 639-1, Currently supported: sv, da, no, en.

country

true

string

Country code for the country where purchase is made (normally store location) according to ISO 3166-1 alpha-2, e.g. SE, DK, NO, GB.

autoactivate

false

string

Flag showing if the payment should be auto activated, thus if set, payment is finalized and no activatePayment command is required. For invoice, service and partpayment, autoactivation=1 locks invoice, sends it to Billmate. For invoice and service an invoice will be sent to the given customer email. For card/bank payment, autoactivate=1 captures amount immediately. Default=0. You can also enter a date for when the payment should be activated e.g. 2015-02-28.

orderid

true

string

A unique order id generated by the shop as a reference.

logo

false

int

Change logo for the payment. You will find the reference to your logo in your billmate online account. You will find it in Settings -> Company details -> Company logo. The reference to be used is the file name e.g. Logo1.jpg. If left empty the standard logo will be used.

accepturl

false

string

Url to which the customer is redirected after a completed payment. Data returned is same as for initCheckout defined below.

cancelurl

false

string

Url to which the customer is redirected after a failed or cancelled payment. Data returned is error message and code as for initCheckout defined below.

returnmethod

false

string

Http return method to accepturl, cancelurl and callbackurl. Default is ‘POST’, but can be set to ‘GET’ instead.

callbackurl

false

string

Url to which callback data is sent after the customer has succesfully completed chaeckout payment. Data returned is same as for initCheckout defined below and for accepturl. Callback is made same time as accepturl, thus it can’t be assumed that callback data will arrive before accepturl data. No response is required to a callback request, the data just has to be received. If callback data is not received, Billmate server will try to send callback data again once a minute first 10 minutes, once an hour first 10 hours, once a day first 7 days, then finally once a month for next 3 months.

- Paymentinfo

Property

Required

Type

Description

paymentdate

false

date

Payment date in invoice/receipt on format YYYY-MM-DD. Default is current date.

yourreference

false

string

Your reference field in invoice/receipt.

ourreference

false

string

Our reference field in invoice/receipt.

projectname

false

string

Project name field in invoice/receipt.

delivery

false

string

Delivery method. Post, etc.

deliveryterms

false

string

Delivery terms field in invoice/receipt. FOB, etc.

autocredit

false

boolean

If this is set to true, then if the invoice is not paid before the duedate, the invoice will be automatically credited. Default is false.

- Customer

Property

Required

Type

Description

nr

false

int

Customer number. If not given, next available customer number in Billmate will be assigned.

pno

false

string

Swedish social security number or swedish organization number. Sent as YYMMDD-XXXX, it can be sent with or without “-” and with or without the two first numbers (19 or 20) in the year. Mandatory field for Factoring and PartPayment methods, but not for receipt, card and bank payments.

- Customer Billing

Property

Required

Type

Description

email

true

string

Billing email, required for all methods (except card/bank).

firstname

false

string

Firstname, mandatory if factoring or partpayment.

lastname

false

string

Lastname, mandatory if factoring or partpayment.

company

false

string

Company name if applicable, mandatory if company organisation number is given for factoring or partpayment.

zip

false

string

Zipcode, mandatory if factoring or partpayment.

city

false

string

City, mandatory if factoring or partpayment.

phone

false

string

Phone number.

company

false

string

Company name if applicable.

street

false

string

Street.

street2

false

string

Second row of Street if required.

zip

false

string

Zipcode.

- Customer Shipping

Property

Required

Type

Description

firstname

false

string

Firstname, mandatory if factoring or partpayment.

lastname

false

string

Lastname, mandatory if factoring or partpayment.

company

false

string

Company name if applicable, mandatory if company organisation number is given for factoring or partpayment.

zip

false

string

Zipcode, mandatory if factoring or partpayment.

city

false

string

City, mandatory if factoring or partpayment.

phone

false

string

Phone number.

company

false

string

Company name if applicable.

street

false

string

Street.

street2

false

string

Second row of Street if required.

zip

false

string

Zipcode.

- Articles

Discount on total payment/invoice is sent as an article with negative aprice and negative withouttax value. If multiple tax rates are used in the invoice, the discount tax (negative) and discount tax rate (positive) has to be calculated for each standard tax rate and be given as parameters. Thus, discount tax rate has to be fixed to a standard tax rate (i.e. 6%,12%,25%) and can not be given as a decimal value like 12.6%.By using –freetext– (double dashes) as artnr you can send a free text row instead of an additional article for description of the item bought e.g. green color on a t-shirt.

Property

Required

Type

Description

articles[0].taxrate

true

dec

First article tax rate in percent.

articles[0].withouttax

true

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Mandatory since at least one article is required to add up to total.withouttax. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

articles[0].artnr

false

string

First article number.

articles[0].title

false

string

First article description.

articles[0].quantity

false

dec

First article quantity.

articles[0].aprice

false

dec

First article unit price without tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

articles[0].discount

false

dec

First article discount in %.

articles[1].artnr

false

string

Second article number.

articles[1].title

false

string

Second article description.

articles[1].quantity

false

dec

Second article quantity.

articles[1].aprice

false

dec

Second article unit price without tax.

articles[1].taxrate

false

dec

Second article tax rate in percent.

articles[1].discount

false

dec

Second article discount in %.

articles[1].withouttax

false

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

- Cart

Property

Required

Type

Description

total.withouttax

true

int

Total payment excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will be checked against summation of all articles[x].withouttax, handlingcharge.withouttax and shipping.withouttax. If not matching values, an error will be returned.

total.tax

true

int

Total tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

total.withtax

true

int

Total payment including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Note Total Payment with Tax must be equal to Total Payment Excluding Tax + Total Tax + Rounding. This is a double check to make sure no rounding errors are present and payment always will be correct.

handling.withouttax

false

dec

Handling charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

handling.taxrate

false

dec

Handling vat rate in %.

shipping.withouttax

false

dec

Shipping charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

shipping.taxrate

false

dec

Shipping vat rate in %.

total.rounding

false

dec

Rounding in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

Request

- Articles

Discount on total payment/invoice is sent as an article with negative aprice and negative withouttax value. If multiple tax rates are used in the invoice, the discount tax (negative) and discount tax rate (positive) has to be calculated for each standard tax rate and be given as parameters. Thus, discount tax rate has to be fixed to a standard tax rate (i.e. 6%,12%,25%) and can not be given as a decimal value like 12.6%.By using –freetext– (double dashes) as artnr you can send a free text row instead of an additional article for description of the item bought e.g. green color on a t-shirt.

Property

Required

Type

Description

articles[0].taxrate

true

dec

First article tax rate in percent.

articles[0].withouttax

true

dec

Total article row excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will overwrite any errors in rounding of articles row sum. Mandatory since at least one article is required to add up to total.withouttax. Note When a discount is applicable on the article, you have to deduct the discount amount from the withouttax amount.

articles[0].artnr

false

string

First article number.

articles[0].title

false

string

First article description.

articles[0].quantity

false

dec

First article quantity.

articles[0].aprice

false

dec

First article unit price without tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

articles[0].discount

false

dec

First article discount in %.

- Cart

Property

Required

Type

Description

total.withouttax

true

int

Total payment excluding tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Amount given will be checked against summation of all articles[x].withouttax, handlingcharge.withouttax and shipping.withouttax. If not matching values, an error will be returned.

total.tax

true

int

Total tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

total.withtax

true

int

Total payment including tax in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR). Note Total Payment with Tax must be equal to Total Payment Excluding Tax + Total Tax + Rounding. This is a double check to make sure no rounding errors are present and payment always will be correct.

handling.withouttax

false

dec

Handling charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

handling.taxrate

false

dec

Handling vat rate in %.

shipping.withouttax

false

dec

Shipping charge in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

shipping.taxrate

false

dec

Shipping vat rate in %.

total.rounding

false

dec

Rounding in 1/100 of currency (i.e. öre if currency is SEK, cent if currency is EUR).

URL to which callback data is sent after the customer has successfully completed a payment. This is the only guaranteed request from Billmate Checkout regarding competed orders. Data returned is same as initCheckout and for accepturl.

Callback is made at the same time as accepturl, thus it can’t be assumed that callback data will arrive before accepturl data.

No response is required for a callback request, the data just has to be received successfully with an appropriate http status code. If the callback failed:

Billmate will try to send the callback again once a minute the first 10 minutes, once an hour the first 10 hours, once a day the first 7 days, then finally once a month for the next 3 months.

This event is used to send the scroll position of the iframe. JSON data includes a integer of the content_scroll_position that should be used. Note that this should be adapted to your own needs, see example.

checkout_loaded

JS EVENT checkout_loaded FROM CHECKOUT EXAMPLE

Receive from Checkout.

This event is used to send the status that the Checkout is now fully loaded.

show_overlay

No additional data is sent.

Receive from Checkout.

This event is sent from Checkout iframe to parent when Checkout show an overlay and if Client want to do the same.

hide_overlay

No additional data is sent.

Receive from Checkout.

This event is sent from Checkout iframe to parent when Checkout is no longer showing overlay.

Data Types

This section contains the different data types that are related to the API.

string

{
"name": "Test Name"
}

Strings have a maximum character length of 255 characters, otherwise it is noted in the description of the property.

int

{
"topay": "200"
}

Int´s are numeric based values but acts as strings.

dec

{
"topay": "200.20"
}

Dec´s are decimal numeric value, but acts as strings. Note that it uses the point (.) as a separator.

date

{
"paymentdate": "2020-02-12"
}

Dates are using the ISO 8601 standard in format Year, Month and Day (Y-m-d). One example is 2020-02-12 representing the 12th of February 2020.