Integrate to PayEx Billing Usage API

Changelog

Version	Date	Description	Created by
1.0	2024-06-10	Created document	Anders Göthberg
1.1	2024-10-04	API in production	Anders Göthberg

Introduction

Link to the general step-by-step implementations guide that guides you through setting up a REST API integration towards PayEx Invoice Service can be found here

Billing Usage API presents calls to customers' billed and unbilled usage calls. This can be used for presentation on the company's various applications such as "my pages" or customer service users in the company's own CRM.

Usage API

Route description

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parent resources in the route.
lf-api.payex.com/billing/{subdomain}/v1/{ownerNo}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Route segment	Description
subdomain	In this part of the API it will be "billing"
ownerNo	The ledger identifier/number at PayEx
resource1Id	Identifier of resource1 (invoices or customers)
resource2Id	identifier of resource2, subresource to resource1 (subscriptions)
resource3Id	identifier of resource3, subresource to resource2

Routes that occurs in examples of this documentation will use the following identifiers

Resource	Identifier
ownerNo	The ledger identifier/number at PayEx
invoiceNo	Invoice number
customerNo	Customer number
subscriptionNo	Subscription number (mobile or fixed telephone number or other identifier)

1. Invoices

"Invoices" presents billed usage

1.1 Get specific Invoice

Request

GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Check if usage is billed and the invoice number is avalible in Usage

Response

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

{
"invoiceNo": "123456",
"subscriptions": "/billing/usage/v1/xxx/invoices/123456/subscriptions"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
invoiceNo	string	Invoice number
subscriptions	dynamic	Subscription/Phone -number

2. Subscriptions

"Subscriptions" presents a list of subscription number with billed usage included on selected invoice

2.1 Get list of Subscriptions

Request

GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of "Subscriptions" included on selected invoice

Response

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

{
"items": [
    {
     "subscriptionNo": "12345680",
     "usageDetails": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-details",
     "usageSummaries": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-summaries",
     "@id": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680"
    },
    {
     "subscriptionNo": "12345690",
     "usageDetails": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345690/usage-details",
     "usageSummaries": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345690/usage-summaries",
     "@id": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345690"
    }
  ],
"navigation": {
   "@id": "/billing/usage/v1/xxx/invoices/123456/subscriptions"
  }
}

"Subscription" -details for each subscription number included on selected invoice

2.2 Get specific Subscription

Request

GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions/{subscriptionNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present details for each "Subscriptions" included on selected invoice

Response

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

{
"subscriptionNo": "12345680",
"usageDetails": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-details",
"usageSummaries": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-summaries"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
subscriptionNo	string	Subscription/Phone -number
usageDetails	dynamic	Detailed list of all usage
usageSummaries	dynamic	Aggregated usage per usage type

3. Usage-details

"Usage-details" presents a detailed list of usage for each subscription number related to selected invoice

3.1 Get list of Usage-details

Request

GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions/{subscriptionNo}/usage-details HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present a detailed list of usage for selected "subscriptionNo" included on related invoice nr

Response

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

{
"items": [
    {
     "type": 250,
     "typeName": "Surf i hogkostnadszon",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "ROAM, SERVICES.COMPANY.COM",
     "destinationName": "APN Resterande",
     "subscriptionNo": "4671000000223344",
     "totalAmount": 2.50,
     "volume": 4257793,
     "volumeUnit": "B",
     "chargeDetails": {
       "vatRate": 25.00,
       "price": 107.61,
       "priceUnit": "MB",
       "interval": 50000,
       "intervalUnit": "B",
       "startPrice": 0.00
      },
     "roamingDetails": {
       "countryCode": "NO",
       "operator": "Vodafone"
      }
    },
    {
     "type": 255,
     "typeName": "Styckpris, Betalformedling, Mobil",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "Bingolotto fargfemman",
     "destinationName": "Innehallstjanst, samtal",
     "subscriptionNo": "4671000000223344",
     "totalAmount": 13,
     "volume": 1,
     "volumeUnit": "E",
     "chargeDetails": {
       "vatRate": 0.00,
       "price": 107.61,
       "priceUnit": "E",
       "interval": 1,
       "intervalUnit": "E",
       "startPrice": 0.00
      },
     "providerDetails": {
       "name": "Folkspel",
       "service": "Bingolotto fargfemman",
       "serviceName": "Bingolotto",
       "contact": "020-3334455, googleplay-support@google.com, play.google.com"
      }
    }
  ]
}

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
type	number	Type: int32	Usage type Id in PayEx Billing system
typeName	string		Usage type name in PayEx Billing system
startDateTime	string		Start time for CDR
destination	string		"B-Nr" in CDR or if "Context" then "text"
destinationName	string		Subscription Nr/Phone Nr
subscriptionNo	string		Subscription Nr/Phone Nr
totalAmount	number	Type: double	Total cost for CDR
volume	number	Type: int64	Volume/count of Usage
volumeUnit	string		Unit for volume (S, MIN, E, B, KB, MB, GB)
chargeDetails	object
vatRate	number	Type: double	Vat rate for CDR
price	number	Type: double	Price per unit (Price per Event/MB/S/…)
priceUnit	string		Priced unit (S, MIN, E, B, KB, MB, GB)
interval	number	Type: int32	Charge interval
intervalUnit	string		Start price for CDR
startPrice	number	Type: double	Start price for CDR
providerDetails	object
name	string		Content provider name
service	string		Content provider service
serviceName	string		Content provider service name
contact	string		Content provider contact details (phone, mail, web page)
roamingDetails	object
countryCode	string		Country code, (SE, NO,…)
operator	string		Name of operator for CDR/Usage

4. Usage-summaries

"Usage-summaries" presents a list of summarized usage per usage types for each subscription number related to selected invoice

4.1 Get list of Usage-summaries

Request

GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions/{subscriptionNo}/usage-summaries HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present a summarized list of usage per usage types for selected "subscriptionNo" included on related invoice nr

Response

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

{
"items": [
    {
     "type": 310,
     "typeName": "Description for 250",
     "usageCount": 3,
     "firstUsageDate": "2023-10-08T10:40:52",
     "lastUsageDate": "2023-10-19T12:20:52",
     "totalAmount": 299.50,
     "volume": 634,
     "volumeUnit": "S",
     "vatRate": 0.000
    },
    {
     "type": 330,
     "typeName": "Description for 330",
     "usageCount": 56,
     "firstUsageDate": "2023-10-02T12:19:52",
     "lastUsageDate": "2023-10-12T12:20:52",
     "totalAmount": 299.50,
     "volume": 634,
     "volumeUnit": "S",
     "vatRate": 0.000
    }
  ]
}

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
type	number	Type: int32	Usage type Id in PayEx Billing system
typeName	string		Usage type name in PayEx Billing system
usageCount	number	Type: int32	CDR -count
firstUsageDate	string		"First" day for Usage type
lastUsageDate	string		"Last" day for Usage type
totalAmount	number	Type: double	Total cost for aggregated CDRs
volume	number	Type: int64	Summarized volume for aggregated CDRs
volumeUnit	string		Unit for volume (S, MIN, E, B, KB, MB, GB)
vatRate	number	Type: double	Vat rate

5. Customers

"Customers" presents unbilled usage

5.1 Get specific Customer

Request

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

Check if customer has any unbilled usage

Response

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

{
"customerNo": "224455",
"subscriptions": "/billing/usage/v1/xxx/customers/224455/subscriptions"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
customerNo	string	Customer number
subscriptions	dynamic	Subscription/Phone -number

6. Subscriptions

"Subscriptions" presents a list of subscription numbers with unbilled usage for selected customer

6.1 Get list of Subscriptions

Request

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

The resource is used to get a list of "Subscriptions" with unbilled usage for selected customer

Response

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

{
"items": [
    {
     "subscriptionNo": "12345680",
     "unbilledUsageDetails": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-details",
     "unbilledUsageSummaries": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-summaries",
     "@id": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680"
    },
    {
     "subscriptionNo": "12345690",
     "unbilledUsageDetails": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345690/unbilled-usage-details",
     "unbilledUsageSummaries": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345690/unbilled-usage-summaries",
     "@id": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345690"
    }
  ],
"navigation": {
   "@id": "/billing/usage/v1/xxx/customers/224455/subscriptions"
  }
}

"Subscription" -details for each subscription number with unbilled usage on selected customer nr

6.2 Get specific Subscription

Request

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

The resource is used to get a list of "Subscriptions" with unbilled usage for selected customerThe resource is used to present details for each "Subscriptions" with unbilled usage on selected customer

Response

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

{
"subscriptionNo": "12345680",
"unbilledUsageDetails": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-details",
"unbilledUsageSummaries": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-summaries"
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
subscriptionNo	string	Subscription/Phone -number
unbilledUsageDetails	dynamic	Detailed list of all unbilled usage
unbilledUsageSummaries	dynamic	Aggregated unbilled usage per usage type

7. Unbilled-usage-details

"Unbilled-usage-details" presents a detailed list of unbilled usage for each subscription number related to selected customer

7.1 Get list of Unbilled-usage-details

Request

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

The resource is used to present a detailed list of unbilled usage for selected "subscriptionNo" included on related customer

Response

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
type	number	Type: int32	Usage type Id in PayEx Billing system
typeName	string		Usage type name in PayEx Billing system
startDateTime	string		Start time for CDR
destination	string		Called number ("B-Nr") in CDR or if "Context" then "text"
destinationName	string		Subscription Nr/Phone Nr
subscriptionNo	string		Subscription Nr/Phone Nr
totalAmount	number	Type: double	Total cost for CDR
volume	number	Type: int64	Volume/count of Usage
volumeUnit	string		Unit for volume (S, MIN, E, B, KB, MB, GB)
chargeDetails	object
vatRate	number	Type: double	Vat rate for CDR
price	number	Type: double	Price per unit (Price per Event/MB/S/…)
priceUnit	string		Priced unit (S, MIN, E, B, KB, MB, GB)
interval	number	Type: int32	Charge interval
intervalUnit	string		Start price for CDR
startPrice	number	Type: double	Start price for CDR
providerDetails	object
name	string		Content provider name
service	string		Content provider service
serviceName	string		Content provider service name
contact	string		Content provider contact details (phone, mail, web page)
roamingDetails	object
countryCode	string		Country code, (SE, NO,…)
operator	string		Name of operator for CDR/Usage

8. Unbilled-usage-summaries

"Unbilled-usage-summaries" presents a list of summarized unbilled usage per usage types for each subscription number related to selected customer

8.1 Get list of Unbilled-usage-summaries

Request

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

The resource is used to present a summarized list of unbilled usage per usage types for selected "subscriptionNo" related to selected customer

Response

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
type	number	Type: int32	Usage type Id in PayEx Billing system
typeName	string		Usage type name in PayEx Billing system
usageCount	number	Type: int32	CDR -count
firstUsageDate	string		Date of "first" day for Usage type
lastUsageDate	string		Date of "last" day for Usage type
totalAmount	number	Type: double	Total cost for aggregated CDRs
volume	number	Type: int64	Summarized volume for aggregated CDRs
volumeUnit	string		Unit for volume (S, MIN, E, B, KB, MB, GB)
vatRate	number	Type: double	Vat rate

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

Problem types

Note, each problem typecode is preceded by "billing/usage/service" in this API, e.g. the error "validation" in the table below will appear as typecode "billing/usage/problems/validation".

Problem type (code)	Http status	Description
validation	400	occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
invoice-not-found	404	Invoice number not found in Usage
customer-not-found	404	Customer not found in Usage for unbilled usage.
invoice-has-no-usage	404	Invoice has no usage
subscription-not found	404	Subscription not found on selected invoice (billed) or customer (unbilled)

Ledger and Factoring

Usage

Changelog

Introduction

Usage API

Route description

1. Invoices

1.1 Get specific Invoice

2. Subscriptions

2.1 Get list of Subscriptions

2.2 Get specific Subscription

3. Usage-details

3.1 Get list of Usage-details

4. Usage-summaries

4.1 Get list of Usage-summaries

5. Customers

5.1 Get specific Customer

6. Subscriptions

6.1 Get list of Subscriptions

6.2 Get specific Subscription

7. Unbilled-usage-details

7.1 Get list of Unbilled-usage-details

8. Unbilled-usage-summaries

8.1 Get list of Unbilled-usage-summaries

Problems

Example

Problem types