Business - Payments
The Admin interface handles web service calls from the Admin web gui. The base url for this is at:
/api/business-admin
A JSON file with OpenAPI data about all business-related admin APIs can be downloaded here.
Get single payment data
Gets the data of a specified payment
- GET /v1/payments/{id}
Retrieves data on a single payment
- Parameters
id (integer) – The payment ID
- Status Codes
200 OK – Success
The API responds with a plain error, or with the following format:
{
ID: 1, // Int
Type: 0, // Int
Status: 0, // Int
Amount: 12.3, // Decimal
CreatedDate: "2021-01-01T05:00:00Z", // Date
LastExecutionAttempt: "2021-01-01 06:00:00", // Date (nullable)
LastExecutedBy: "Administrator", // String (nullable)
Note: "Notes on the payment", // String
ExtUserGuid: "1414dec6-31a1-403d-a426-446147e807b2", // Guid
ExtUser: "User Name", // String
TripGuid: "be9896c4-8feb-4daa-aa3a-0170a8702b18", // Guid (nullable)
StartLocationName: "Milan", // String (nullable)
StartTimestamp: "2021-01-01 06:00:00:", // Date (nullable)
EndLocationName: "Milan", // String (nullable)
EndTimestamp: "2021-01+01 06:00:00", // Date (nullable)
CostType: 0, // Int (nullable)
CostLabel: "{"en":"Speed Fine", ... }", // String (nullable)
ArticleID: 3, // Int (nullable)
ArticleQuantity: 1, // Int (nullable)
ArticleLabels: "{"en":"Article Name", ...}" // String (nullable)
}
The property Type can assume values among the one defined in the PaymentTypes enumeration.
The property Status can assume values among the one defined in the PaymentStatuses enumeration.
The property CostType can assume values among the one defined in the AdditionalCostTypes enumeration.
The trip related properties (guid, location names and timestamp) are valorized only if the Type property is either
TripPayment, Fine or AdditionalCost.
The cost related properties (type and label) are valorized only if the Type property is either Fine or AdditionalCost.
The article related properties (ID, quantity and labels) are valorized only if if the Type property is ArticlePurchase.
Get payments to be payed
Gets the paged list (see Paged List APIs) of the payments still to be payed
- GET /v1/payments/to-pay
Gets a list of payments to be payed
- Query Parameters
types (string) – An optional list of payments type
- Status Codes
200 OK – Success
The API accepts the following filters in the query params: * types (comma separated list of payment types, as int value, to be extracted)
and responds with a plain error, or with the following format:
[
{
ID: 1, // Int
Type: 0, // Int
Status: 0, // Int
Amount: 12.3, // Decimal
CreatedDate: "2021-01-01T05:00:00Z", // Date
LastExecutionAttempt: "2021-01-01 06:00:00", // Date (nullable)
LastExecutedBy: "Administrator", // String (nullable)
Note: "Notes on the payment", // String
ExtUserGuid: "1414dec6-31a1-403d-a426-446147e807b2", // Guid
ExtUser: "User Name", // String
TripGuid: "be9896c4-8feb-4daa-aa3a-0170a8702b18", // Guid (nullable)
StartLocationName: "Milan", // String (nullable)
StartTimestamp: "2021-01-01 06:00:00:", // Date (nullable)
EndLocationName: "Milan", // String (nullable)
EndTimestamp: "2021-01+01 06:00:00", // Date (nullable)
CostType: 0, // Int (nullable)
CostLabel: "{"en":"Speed Fine", ... }," // String (nullable)
ArticleID: 3, // Int (nullable)
ArticleQuantity: 1, // Int (nullable)
ArticleLabels: "{"en":"Article Name", ...}" // String (nullable)
},
{ ... }
]
The property Type can assume values among the one defined in the PaymentTypes enumeration.
The property Status can assume values among the one defined in the PaymentStatuses enumeration, and is always either
to be payed or failed.
The property CostType can assume values among the one defined in the AdditionalCostTypes enumeration.
The trip related properties (guid, location names and timestamp) are valorized only if the Type property is either
TripPayment, Fine or AdditionalCost.
The cost related properties (type and label) are valorized only if the Type property is either Fine or AdditionalCost.
The article related properties (ID, quantity and labels) are valorized only if if the Type property is ArticlePurchase.
Execute payment
Allows the user to request the execution of a payment without waiting for the nightly payment execution
- POST /v1/payments/pay/{paymentId}
Executes real-time the selected payment
- Parameters
paymentId (integer) – The payment to be executed
- Status Codes
200 OK – Success
No request body or specific answer is expected.
The API will return OK if the transaction was correctly executed or one of the following errors:
err_CannotExecuteValidation errors occurred in the Movens platform or in the payment gateway platform
Get payments on hold
Gets the paged list (see Paged List APIs) of the suspended payments
- GET /v1/payments/on-hold
Gets a list of already payments on hold
- Query Parameters
types (string) – An optional list of payments type
- Status Codes
200 OK – Success
The API accepts the following filters in the query params: * types (comma separated list of payment types, as int value, to be extracted)
and responds with a plain error, or with the following format:
[
{
ID: 1, // Int
Type: 0, // Int
Status: 4, // Int
Amount: 12.3, // Decimal
CreatedDate: "2021-01-01T05:00:00Z", // Date
LastExecutionAttempt: "2021-01-01 06:00:00", // Date (nullable)
LastExecutedBy: "Administrator", // String (nullable)
Note: "Notes on the payment", // String
ExtUserGuid: "1414dec6-31a1-403d-a426-446147e807b2", // Guid
ExtUser: "User Name", // String
TripGuid: "be9896c4-8feb-4daa-aa3a-0170a8702b18", // Guid (nullable)
StartLocationName: "Milan", // String (nullable)
StartTimestamp: "2021-01-01 06:00:00:", // Date (nullable)
EndLocationName: "Milan", // String (nullable)
EndTimestamp: "2021-01+01 06:00:00", // Date (nullable)
CostType: 0, // Int (nullable)
CostLabel: "{"en":"Speed Fine", ... }," // String (nullable)
ArticleID: 3, // Int (nullable)
ArticleQuantity: 1, // Int (nullable)
ArticleLabels: "{"en":"Article Name", ...}" // String (nullable)
},
{ ... }
]
The property Type can assume values among the one defined in the PaymentTypes enumeration.
The property Status can assume values among the one defined in the PaymentStatuses enumeration, and is always either
on hold by system or on hold by operator.
The property CostType can assume values among the one defined in the AdditionalCostTypes enumeration.
The trip related properties (guid, location names and timestamp) are valorized only if the Type property is either
TripPayment, Fine or AdditionalCost.
The cost related properties (type and label) are valorized only if the Type property is either Fine or AdditionalCost.
The article related properties (ID, quantity and labels) are valorized only if if the Type property is ArticlePurchase.
Get expired payments
Gets the paged list (see Paged List APIs) of the expired payments
- GET /v1/payments/expired
Gets a list of already executed payments for a user
- Query Parameters
types (string) – An optional list of payments type
- Status Codes
200 OK – Success
The API accepts the following filters in the query params: * types (comma separated list of payment types, as int value, to be extracted)
and responds with a plain error, or with the following format:
[
{
ID: 1, // Int
Type: 0, // Int
Status: 6, // Int
Amount: 12.3, // Decimal
CreatedDate: "2021-01-01T05:00:00Z", // Date
LastExecutionAttempt: "2021-01-01 06:00:00", // Date (nullable)
LastExecutedBy: "Administrator", // String (nullable)
Note: "Notes on the payment", // String
ExtUserGuid: "1414dec6-31a1-403d-a426-446147e807b2", // Guid
ExtUser: "User Name", // String
TripGuid: "be9896c4-8feb-4daa-aa3a-0170a8702b18", // Guid (nullable)
StartLocationName: "Milan", // String (nullable)
StartTimestamp: "2021-01-01 06:00:00:", // Date (nullable)
EndLocationName: "Milan", // String (nullable)
EndTimestamp: "2021-01+01 06:00:00", // Date (nullable)
CostType: 0, // Int (nullable)
CostLabel: "{"en":"Speed Fine", ... }," // String (nullable)
ArticleID: 3, // Int (nullable)
ArticleQuantity: 1, // Int (nullable)
ArticleLabels: "{"en":"Article Name", ...}" // String (nullable)
},
{ ... }
]
The property Type can assume values among the one defined in the PaymentTypes enumeration.
The property Status can assume only the value Expired fromthe PaymentStatuses enumeration.
The property CostType can assume values among the one defined in the AdditionalCostTypes enumeration.
The trip related properties (guid, location names and timestamp) are valorized only if the Type property is either
TripPayment, Fine or AdditionalCost.
The cost related properties (type and label) are valorized only if the Type property is either Fine or AdditionalCost.
The article related properties (ID, quantity and labels) are valorized only if if the Type property is ArticlePurchase.
Get payments not to be payed
Gets the paged list (see Paged List APIs) of the payments not to be payed
- GET /v1/payments/not-payable
Gets a list of payments not to be payed
- Query Parameters
types (string) – An optional list of payments type
- Status Codes
200 OK – Success
The API accepts the following filters in the query params: * types (comma separated list of payment types, as int value, to be extracted)
and responds with a plain error, or with the following format:
[
{
ID: 1, // Int
Type: 1, // Int
Status: 6, // Int
Amount: 12.3, // Decimal
CreatedDate: "2021-01-01T05:00:00Z", // Date
LastExecutionAttempt: "2021-01-01 06:00:00", // Date (nullable)
LastExecutedBy: "Administrator", // String (nullable)
Note: "Notes on the payment", // String
ExtUserGuid: "1414dec6-31a1-403d-a426-446147e807b2", // Guid
ExtUser: "User Name", // String
TripGuid: "be9896c4-8feb-4daa-aa3a-0170a8702b18", // Guid (nullable)
StartLocationName: "Milan", // String (nullable)
StartTimestamp: "2021-01-01 06:00:00:", // Date (nullable)
EndLocationName: "Milan", // String (nullable)
EndTimestamp: "2021-01+01 06:00:00", // Date (nullable)
CostType: 0, // Int (nullable)
CostLabel: "{"en":"Speed Fine", ... }," // String (nullable)
ArticleID: 3, // Int (nullable)
ArticleQuantity: 1, // Int (nullable)
ArticleLabels: "{"en":"Article Name", ...}" // String (nullable)
},
{ ... }
]
The property Type can assume values among the one defined in the PaymentTypes enumeration.
The property Status can assume only the value Not to be payed fromthe PaymentStatuses enumeration.
The property CostType can assume values among the one defined in the AdditionalCostTypes enumeration.
The trip related properties (guid, location names and timestamp) are valorized only if the Type property is either
TripPayment, Fine or AdditionalCost.
The cost related properties (type and label) are valorized only if the Type property is either Fine or AdditionalCost.
The article related properties (ID, quantity and labels) are valorized only if if the Type property is ArticlePurchase.
Edit an existing payment
Persists edits aan existing payment:
The API accepts a JsonBody with the following format:
{
ID: 1, // Int
Amount: 12.3, // Decimal
Status: 0, // Int
NoteS: "Some notes" // String (nullable)
}
where the Status property can assume only the values To be payed or Not to be payed fromthe PaymentStatuses enumeration.
The API will respond with a plain OK response, or with one of the following errors:
err_InvalidElementEither the amount is not provided or in an invalid format, or the status is not one of the accepted values
err_NoPaymentFoundThe provided ID does not map to an existing payment
err_CannotEditThe payment is neither in the “To be payed” status nor the “Not to be payed” status
Get a payment’s transaction attempts
Gets the paged list (see Paged List APIs) of a payment’s transaction attempts
- GET /v1/payments/{id}/attempts
Retrieves every payment attempt for a single payment
- Parameters
id (integer) – The payment ID
- Status Codes
200 OK – Success
The API responds with a plain error, or with the following format:
[
{
LastExecutionAttempt: "2021-01-01 06:00:00", // Date
LastExecutionAttemptResult: true, // Boolean
ExecutedBy: "Administrator", // String
PaymentType: 0, // Int
TransactionType: 0, // Int
PaymentDescription: "...", // String (nullable)
PayedAmount: 12.3 // Decimal
},
{ ... }
]
The property PaymentType can assume values among the one defined in the PaymentTypes enumeration.
The property TransactionType can assume values among the one defined in the TransactionType enumeration.
Get paid cost details
Gets the list of trip cost details payed in the specified payment (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/payments/{id}/cost-details
Returns the list of cost details related to the payment
- Parameters
id (integer) – The payment ID
- Status Codes
200 OK – Success
Returns a Json positive response and the list of all the cost details payed in the provided payment:
[
{
"OriginatorKey": "bl-cost", // String
"CreatedDate": "2020-09-03T06:48:13Z", // DateTime
"Labels": "{\"en\":\"Total trip cost:\",\"it\":\"Costo totale della corsa:\"}", // String
"ValueLabels": null, // String (nullable)
"Value": "2ddc0f63-e924-4fba-8e31-fa5803bf1e39", // String
"ValueType": 4, // Int
"ID": 2613 // Int
},
...
]
The value of the OriginatorKey property can be one of the value described in Trip Details.
The ValueType field can be one of the AdditionalValueTypes enumeration.
The type of the contents of the Value field depends on the value specified in ValueType field
Returns a plain Json negative response if the trip guid does not correspond to any existing record.