Intergiro developer portal

# 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 Optional
type "token" Indicator for method type
card string Tokenized payment information
client Client Yes
# Client
Property Type Description Optional
ip "string" Yes
browser Browser Yes
callback "string" URL to receive the result from Challenge 3DS Yes

# CustomerMethod

Property Type Description Optional
type string "card" or "token"
created DateTime
token string Tokenized payment information
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 ],
}

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

← Postman Examples →