Integrate to PayEx Billing Usage API 

Changelog

VersionDateDescriptionCreated by
1.02024-06-10

Created document

Anders Göthberg
1.12024-10-04API in productionAnders 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

1713272482006-508.png

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 segmentDescription
subdomainIn this part of the API it will be "billing"
ownerNoThe ledger identifier/number at PayEx
resource1IdIdentifier of resource1 (invoices or customers)
resource2Ididentifier of resource2, subresource to resource1 (subscriptions)
resource3Ididentifier of resource3, subresource to resource2

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

ResourceIdentifier
ownerNoThe ledger identifier/number at PayEx
invoiceNoInvoice number
customerNo

Customer number

subscriptionNoSubscription 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 typeFormatDescription
@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 typeFormatDescription
@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 typeFormatDescription
@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 typeFormatDescription
@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 typeFormatDescription
@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 typeFormatDescription
@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
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 typeFormatDescription
@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
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 typeFormatDescription
@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 statusDescription
validation400occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
invoice-not-found404

Invoice number not found in Usage

customer-not-found404Customer not found in Usage for unbilled usage.
invoice-has-no-usage404Invoice has no usage
subscription-not found404Subscription not found on selected invoice (billed) or customer (unbilled)
Created by Anders Göthberg on 2024/03/20 14:57