Reference

Customer

When creating a Customer, the “Customer Creatable” datatype is used. In the response from the endpoint, an object of the Customer data type will be returned.

Creatable

If you do not specify a currency when creating a customer, it will default to swedish crowns "SEK".

Property	Type	Description	Optional
id	string	Unique 16-letter identifier in our system	Yes
number	string	Customer number in your system	Yes
contact	Contact		Yes
method	Method.Creatable[]	See Method data type, may include an empty array
currency	Currency	3-letter currency code, e.g. "SEK"	Yes
schedule	Schedule or Frequency	see Schedule data type	Yes
limit	number	Credit limit in the specified currency for the customer	Yes
order	Order | Order[]	Order or Orders (without the fields payment and customer) to be created simultaneously as the customer	Yes
subscription	Subscription | Subscription[]	Subscription or Subscriptions to be created simultaneously as the customer.	Yes

Customer

Responses from the Customer endpoint will contain a Customer object, which includes an "id" and may include a "status", subscriptions and "link" fields in addition to the ones in the Creatable type.

Property	Type	Description	Optional
id	string
number	string		Yes
contact	Contact		Yes
method	CustomerMethod
link	CustomerLink		Yes
status	string	"active", "created", "inactive", "pending" or "suspended"	Yes
subscription	Subscription[]		Yes
currency	Currency

CustomerMethod

For automatic payment with a customer, a payment method has to be created first. This can be done either with already tokenized cards or through the Registration Process.

Creatable

Property	Type	Description
type	"token"	Indicator for method type
card	string	Tokenized payment information

CustomerMethod

Property	Type	Description	Optional
type	string	"card" or "token"
created	DateTime
token	authly.Token
scheme	Scheme
iin	string	First 6 digits on card
last4	string	Last 4 digits on card
expires	[number, number]	[month, year] where month is 1 to 12 and year is 0 to 99
acquirer	string	"intergiro" or "clearhaus"	Yes

Example:

{
    "type": "card",
    "created": "2020-03-13T13:37:13.123Z",
    "token": "abc.def.ghi",
    "scheme": "visa",
    "iin": "411111",
    "last4": "1111",
    "expires": [ 2, 22 ],
}

CustomerLink

Information associated to single use login links for the customer page.

Property	Type	Description	Optional
url	string
created	DateTime
expires	DateTime
key	authly.Token		Yes
contact	string		Yes

Example:

{
    "url": "http://localhost:7071/customer/1234567890abcdef/link/0987654321098765",
    "id": "0987654321098765",
    "created": "2020-12-08T09:19:42.835Z",
    "expires": "2020-12-11T09:19:42.835Z",
    "key": "abc.def.ghi",
    "contact": "m.exampleperson@example.net",
    "used": false
}

Customer Payment

Customer Payment Creatable

Property	Type	Description	Optional
type	"customer"
schedule	number[]	Time in days for which this payment is supposed to be retried.	Yes
charge	"auto"	On success, this order will be immediately charged.	Yes
scheduled	true	Indicates that this is a scheduled payment.	Yes

Customer Payment

Property	Type	Description	Optional
type	"customer"
schedule	number[]	Time in days for which this payment is supposed to be retried.	Yes
charge	"auto"	On success, this order will be immediately charged.	Yes
due	DateTime	Date specifying when this order is due.	Yes

Subscription

When creating a subscription, the Creatable Subscription datatype will be used.

When calling the subscription endpoint to add a subscription to a customer, add a Creatable Subscription Object. The schedule and items field allow both for very specific and complex structures as well as simple payment models. If no start date is specified, the start date will be set as the current date.

Creatable

Property	Type	Description	Optional
number	string	Number specified by integrator (must be unique)	Yes
items	number or Item or Item[]
currency	Currency
schedule	Schedule or Frequency
start	Date		Yes
end	Date		Yes
callback	string		Yes

Simple Example:

{
    "number": "standard",
    "items": 25,
    "currency": "SEK",
    "schedule": "monthly",
}

Complex Example:

{
    "number": "aaa-001",
    "items": [
        {
            "name": "Basic Access",
            "price": 42.00,
            "vat": 25.00,
            "quantity": 1
        },
        {
            "name": "Premium Access",
            "price": 100.00,
            "vat": 25.00,
            "quantity": 2
        }
    ],
    "currency": "SEK",
    "schedule": { 
      "frequency":"quarterly",
      "offset": [ 2,-1 ]
    },
    "start": "2021-07-03",
    "callback":"your.callback.com/subscription"
}

Responses from the Subscription endpoint will be of the completed Subscription type, which always includes a start date as well as a 4-letter identifier, which is unique per customer. The "due" field contains the date in ISO format at which the next order charging the subscription will be placed into the system. At this point the system automatically calculates the next "due" date as long as it is not past the "end" date of the subscription.

Subscription

Property	Type	Description	Optional
id	string	Intergiro's internal 4-letter generated unique ID number
number	string	Number specified by integrator (must be unique)	Yes
items	number or Item or Item[]
currency	Currency
schedule	Schedule or Frequency
start	Date		Yes
end	Date		Yes
due	Date		Yes
callback	string		Yes

Example:

{
    "id":"test",
    "number": "aaa-001",
    "items": [
        {
            "name": "Basic Access",
            "price": 50.00,
            "vat": 12.50,
            "quantity": 1
        },
        {
            "name": "Premium Access",
            "price": 100.00,
            "vat": 25.00,
            "quantity": 2
        }
    ],
    "currency": "SEK",
    "schedule": { 
      "frequency":"quarterly",
      "offset": [ 2,-1 ]
    },
    "start": "2021-07-03",
    "due": "2021-09-30",
    "callback":"your.callback.com/subscription"
}

Schedule

When specifying a Schedule for payment, either use the full datatype or a string containing the Frequency as defined in the "frequency" field. Examples for the Divisor, the Offset and multiple Schedules are defined below.

Property	Type	Description	Optional
frequency	Frequency	Frequency of the payment
divisor	number or [number,number]	How often to apply the payment	Yes
offset	number or [number,number]	Specifying offset inside the frequency	Yes

Frequency

Defined as string that is either "daily","weekly","monthly", "quarterly" or"yearly"

Divisor

The divisor defines how often to apply the payment. Thus, a payment on every even (Iso)week would specify frequency: "weekly" and divisor: 2.

If the billing is supposed to happen at a specific time inside of the payment period, this can be done using a more complex divisor. For example to bill every 10 days, but always on the third day of the period, specify frequency: "daily" and divisor: [3,10].

All numbers in the divisor have to be positive and in case of a tuple, the second number of the tuple has to be larger than the first number. It should also be considered that divisors use the modulo division and divisors that are not dividends of the timeframe that they divide can lead to much larger effective payment intervals.

For example, with frequency: "monthly" and divisor:7 there will only be a single payment a year, which will happen in August (month is specified with number 0-11). When using the divisor with "weekly" frequencies also consider that an ISO year has either 53 or 52 weeks. The "daily" frequency uses the day of the month for the divisor.

Schedule Examples:

Every month:
{
    "frequency": "monthly"
}
The first day of every other month (February, April, ..., December):
{
    "frequency": "monthly",
    "divisor": 2,
    "offset": 1
}
The last day of every quarter:
{
    "frequency": "quarterly",
    "offset": [2,-1]
}
Payment period of every third (Iso)week of the year, paying on wednesday in the middle week:
{
    "frequency": "weekly",
    "divisor": [1,3],
    "offset": 3
}
Every other year on the 13th of december:
{
    "frequency": "yearly",
    "divisor": 2,
    "offset": [11,13]
}