PayEx Developer Portal - Customer-from-swagger

1. Customers

Get customer

1.1 Get specific Customer

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"customerNo": "15615616",
"recurringProducts": "/billing/customer/v1/xxx/customers/15615616/recurring-products",
"subscriptions": "/billing/customer/v1/xxx/customers/15615616/subscriptions",
"operations": [
    {
     "rel": "add-subscription",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/subscriptions"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/recurring-products"
    }
  ]
}

1.2 Create Customer

Adds customer

Request

POST /billing/customer/v1/{ownerNo}/customers HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property	Data type	Format	Required	Description
customerNo	string	MinLength: 1 MaxLength: 15 Regex pattern:"[a-zA-Z0-9äåöÄÅÖ&/_ -.]*"	Yes	Identifier for customer

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"customerNo": "15615616",
"recurringProducts": "/billing/customer/v1/xxx/customers/15615616/recurring-products",
"subscriptions": "/billing/customer/v1/xxx/customers/15615616/subscriptions",
"operations": [
    {
     "rel": "add-subscription",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/subscriptions"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/recurring-products"
    }
  ],
"@id": "/billing/customer/v1/xxx/customers/15615616"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
customerNo	string	Identifier for customer
recurringProducts	dynamic	Uri for selected recurrent lines
subscriptions	dynamic	Uri for selected subscriptios
operations	array	List of operations for this resource. See the documentation for more information. hypermedia part of the response

2. Recurring-products

Lists recurring products on customer level

2.1 Get list of Recurring-products

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of recurring products on customer level

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"items": [
    {
     "recurringProductId": "4444",
     "baseProductCode": "F01",
     "deviantText": "Fakturaavgift",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "29.000",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
    },
    {
     "recurringProductId": "4455",
     "baseProductCode": "P02",
     "deviantText": "Halvförsäkring",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4455"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products/4455"
    }
  ],
"navigation": {
   "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products"
  }
}

Get specific recurring product on customer level

2.2 Get specific Recurring-product

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/recurring-products/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a specific recurring product

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"recurringProductId": "4444",
"baseProductCode": "F01",
"deviantText": "Fakturaavgift",
"startDate": "YYYY-MM-DD",
"endDate": "YYYY-MM-DD",
"deviantPrice": "29.000",
"deviantInterval": "",
"invoicedToDate": "",
"operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
    }
  ]
}

2.3 Create Recurring-product

Add recurring product on customer level

Request

POST /billing/customer/v1/{ownerNo}/customers/{customerNo}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property	Data type	Format	Required	Description
baseProductCode	string	MinLength: 1 MaxLength: 5 Regex pattern:"[a-zA-Z0-9]*"	Yes	Predefined product ín PayEx Billing system
deviantText	string	MinLength: 1 MaxLength: 30 Regex pattern:"[a-zA-Z0-9]*"	No	Product text, default text from base product
startDate	string	Type: ISO 8601	Yes	Product start date
endDate	string	Type: ISO 8601	No	Product end date
deviantPrice	string	Type: N(7),N(2-6)	No	The products price for 1 day
deviantInterval	string	Type: N(1)	No	Deviant Interval determines how often the invoice is sent. Default/empty = 1 1,2,3,6 = every 1,2,3,6 month 8 = every 12 months 9 = Stop, no invoice.

The resource is used to add recurring products on customer level

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"recurringProductId": "4444",
"operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
    }
  ],
"@id": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
recurringProductId	string	Unique identifier for specific recurrent product
baseProductCode	string	Predefined product in PayEx Billing system
deviantText	string	Product text, default from base product
startDate	string	Product start date
endDate	string	Product end date
deviantPrice	string	The price of the product, if price is not specified the base product price is used
deviantInterval	string	Selected invoicing interval
invoicedToDate	string	Date of how long the product has been invoiced (Indicating the date until product has been billed)
operations	array	List of operations for this resource. See the documentation for more information. hypermedia part of the response

2.4 Update recurrent line

Some properties on the recurrent line on customer level can be updated through this API. Properties will only be updated if included in the request.

The following recurrent line properties is possible to update through a patch call

Property
endDate

Update recurrent line end date

Request

PATCH /billing/customer/v1/{ownerNo}/customers/{customerNo}/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"endDate": "YYYY-MM-DD"
}

3. Subscriptions

Lists subscriptions on customer

3.1 Get list of Subscriptions

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"items": [
    {
     "subscriptionId": "10101010",
     "subscriptionNo": "MF1122334455",
     "name": "Lätt lastbilsförsäkring, ABC123",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "invoiceSeparately": true,
     "deviantCollectionProcess": "",
     "defaultPaymentMethod": true,
     "deviantDistributionMethod": "Email",
     "recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products",
     "operations": [
        {
         "rel": "partial-update-subscription",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010"
        },
        {
         "rel": "add-recurring-product",
         "method": "POST",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010"
    },
    {
     "subscriptionId": "22101010",
     "subscriptionNo": "CV9988774455",
     "name": "Fritidshusförsäkring",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "invoiceSeparately": true,
     "deviantCollectionProcess": "",
     "defaultPaymentMethod": true,
     "deviantDistributionMethod": "Email",
     "recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010/recurring-products",
     "operations": [
        {
         "rel": "partial-update-subscription",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010"
        },
        {
         "rel": "add-recurring-product",
         "method": "POST",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010/recurring-products"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010"
    }
  ],
"navigation": {
   "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions"
  }
}

Gets specific subscription

3.2 Get specific Subscription

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"subscriptionId": "10101010",
"subscriptionNo": "MF1122334455",
"name": "Lätt lastbilsförsäkring, ABC123",
"startDate": "YYYY-MM-DD",
"endDate": "YYYY-MM-DD",
"invoiceSeparately": true,
"deviantCollectionProcess": "",
"defaultPaymentMethod": true,
"deviantDistributionMethod": "Email",
"recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products",
"operations": [
    {
     "rel": "partial-update-subscription",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products"
    }
  ]
}

3.3 Create Subscription

Adds subscription

Request

POST /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property	Data type	Format	Required	Description
subscriptionNo	string	MinLength: 1 MaxLength: 34 Regex pattern:"[a-zA-Z0-9]*"	Yes	Identifier for subscription
name	string	MinLength: 1 MaxLength: 100 Regex pattern:"[a-zA-Z0-9]*"	Yes	Subscription text for presentation
startDate	string	Type: ISO 8601	Yes	Subscription start date
endDate	string	Type: ISO 8601	No	Subscription end date
invoiceSeparately	boolean		No	Default False=Invoicing on customer level True=Separate subscription number Invoice
deviantCollectionProcess	string		No	If used, must be configured with PayEx
defaultPaymentMethod	boolean		No	If True = default payment method in AR, overriding for example "customer direct debit consent"
deviantDistributionMethod	string		No	"Postal", "Email", overrides customer default/preferred value

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"subscriptionId": "4444",
"recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444/recurring-products",
"operations": [
    {
     "rel": "partial-update-subscription",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444/recurring-products"
    }
  ],
"@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
subscriptionId	string	Identifier for subscription
subscriptionNo	string	Unique identifier for specific subscription
name	string	Subscription text for presentation
startDate	string	Subscription start date
endDate	string	Subscription end date
invoiceSeparately	boolean	Default False=Invoicing on customer level True=Separate subscription number Invoicen
deviantCollectionProcess	string	Selected collection process
defaultPaymentMethod	boolean	Selected payment method
deviantDistributionMethod	string	Selected distributions method
recurringProducts	dynamic	Uri for selected subscriptions recurrent lines
operations	array	List of operations for this resource. See the documentation for more information. hypermedia part of the response

3.4 Update subscription

Some properties on the subscription can be updated through this API. Properties will only be updated if included in the request.

The following subscription properties is possible to update through a patch call

Property
endDate
invoiceSeparately
deviantCollectionProcess
defaultPaymentMethod
deviantDistributionMethod

Update subscription

Request

PATCH /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId} HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "endDate": "YYYY-MM-DD",
   "invoiceSeparately": "True/False",
   "deviantCollectionProcess": "Predefined value",
   "defaultPaymentMethod": "True/False",
   "deviantDistributionMethod": "Postal/Email"
}

4. Recurring-products

Lists subscription recurring products

4.1 Get list of Recurring-products

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of subscription recurring products

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"items": [
    {
     "recurringProductId": "5544",
     "baseProductCode": "F01",
     "deviantText": "Fakturaavgift",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "29.000",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
    },
    {
     "recurringProductId": "5555",
     "baseProductCode": "P02",
     "deviantText": "Halvforsakring",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5555"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5555"
    }
  ],
"navigation": {
   "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products"
  }
}

Gets specific subscription recurring product

4.2 Get specific Recurring-product

Request

GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a specific subscription recurring product

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"recurringProductId": "5544",
"baseProductCode": "F01",
"deviantText": "Fakturaavgift",
"startDate": "YYYY-MM-DD",
"endDate": "YYYY-MM-DD",
"deviantPrice": "29.000",
"deviantInterval": "",
"invoicedToDate": "",
"operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
    }
  ]
}

4.3 Create Recurring-product

Adds subscription recurring product

Request

POST /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property	Data type	Format	Required	Description
baseProductCode	string	MinLength: 1 MaxLength: 5 Regex pattern:"[a-zA-Z0-9]*"	Yes	Predefined product in PayEx Billing system
deviantText	string	MinLength: 1 MaxLength: 30 Regex pattern:"[a-zA-Z0-9]*"	No	Product text, default text from base product
startDate	string	Type: ISO 8601	Yes	Product start date
endDate	string	Type: ISO 8601	No	Product end date
deviantPrice	string	Type: N(7),N(2-6)	No	The products price for 1 day
deviantInterval	string	Type: N(1)	No	Deviant Interval determines how often the invoice is sent. Default = 1 1,2,3,6 = every 1,2,3,6 month 8 = every 12 months 9 = Stop, no invoice.

The resource is used to add a subscription recurring product

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"recurringProductId": "5544",
"operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
    }
  ],
"@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
recurringProductId	string	Unique identifier for specific recurrent product
baseProductCode	string	Predefined product in PayEx Billing system
deviantText	string	Product text, default from base product
startDate	string	Product start date
endDate	string	Product end date
deviantPrice	string	The price of the product, if price is not specified the base product price is used
deviantInterval	string	Selected invoicing interval
invoicedToDate	string	Date of how long the product has been invoiced (Indicating the date until product has been billed)
operations	array	List of operations for this resource. See the documentation for more information. hypermedia part of the response

4.4 Update recurrent line

Some properties on the recurrent line can be updated through this API. Properties will only be updated if included in the request.

The following recurrent line properties is possible to update through a patch call

Property
endDate

Update recurrent line end date

Request

PATCH /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"endDate": "YYYY-MM-DD"
}

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation

Example

Response

HTTP/1.1 400 Error
Content-Type: application/problem+json

{
  "Type" : "ledger/{domain}/v1/problems/validation",
  "Title" : "A validation error occurred",
  "Status" : 400,
  "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
  "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
  "Problems" :
      {
        "amount" : [
           "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
         ]
      }
}

Ledger and Factoring

Customer-from-swagger

1. Customers

1.1 Get specific Customer

1.2 Create Customer

2. Recurring-products

2.1 Get list of Recurring-products

2.2 Get specific Recurring-product

2.3 Create Recurring-product

2.4 Update recurrent line

3. Subscriptions

3.1 Get list of Subscriptions

3.2 Get specific Subscription

3.3 Create Subscription

3.4 Update subscription

4. Recurring-products

4.1 Get list of Recurring-products

4.2 Get specific Recurring-product

4.3 Create Recurring-product

4.4 Update recurrent line

Problems

Example