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
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Check if usage is billed and the invoice number is avalible in Usage
Content-Type: application/json
{
"invoiceNo": "123456",
"subscriptions": "/billing/usage/v1/xxx/invoices/123456/subscriptions"
}
Response object specification
Property | Data type | Format | 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
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
The resource is used to get a list of "Subscriptions" included on selected invoice
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
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
The resource is used to present details for each "Subscriptions" included on selected invoice
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 | Format | 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
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
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
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
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
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Check if customer has any unbilled usage
Content-Type: application/json
{
"customerNo": "224455",
"subscriptions": "/billing/usage/v1/xxx/customers/224455/subscriptions"
}
Response object specification
Property | Data type | Format | 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
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
The resource is used to get a list of "Subscriptions" with unbilled usage for selected customer
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
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
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 | Format | 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
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
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 | 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
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
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 | 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
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
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) |