Client's billing

Our platform enables service providers to create bills with payment links for their clients and send them to the email addresses associated with their Forguard accounts. This process is facilitated through Stripe. Here's how it works:

• Provider's Stripe Account:

  Service providers need a Stripe account to connect it to GPS-Trace Console.

  • Go to GPS-Trace Console → Clients Billing → Settings
  • Click the Stripe Account Connect icon
  • Enter email, set up two-step authentication if required, then select an existing Stripe account or create a new one. If Stripe asks for additional verification details, complete the required information.
  • After the setup is completed, Stripe will redirect service provider back to GPS-Trace Console with a successful connection message.
  • Click on the Clients Billing button to go to the client billing management page.
• Creating Bills with payment links:

  After connecting Stripe account to GPS-Trace Console, service providers gain the ability to create bills with payment links for their clients. They can specify the currency, describe products, assign quantities and prices, which will be reflected in the bill received by their client.

Client Billing API enables service providers to perform various operations seamlessly. It allows:

1. Creating bills with payment links for clients.
2. Sending payment link emails to clients.
3. Retrieving information about all bills, including their statuses and other details.

With these capabilities, service providers can manage payment processes and track the status of invoices issued to their clients.

Get client bills

This endpoint allows you to retrieve bill information about Forguard client accounts within a specified time frame. This method is crucial for tracking and managing client billing activities for accounts billed using the Stripe API Secret key.

GET /billing/stripe-payments

Mandatory request fields:

• app_id: The ID of the application assigned to the client account.

Forguard app_id: b901da51-ce00-4af2-b978-8d0fca8ae1ea

• from: Begin timestamp.
• to: End timestamp.

Note: Results are returned for a maximum duration of 31 days from the begin timestamp.

Request example:

curl -X 'GET' \
'https://api.gps-trace.com/billing/stripe-payments?
app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea&from=&to=&account_id=&fields=' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

200 response example:

{
  "string": {
    "id": "string",
    "status": "open",
    "payment_status": "string",
    "created": number,
    "expires_at": number,
    "account_id": number,
    "url": "",
    "metadata": {
      "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
      "cid": "string",
      "email": "string",
      "lang": "string",
      "name": "string",
      "td_cid": "string"
    },
    "amount_total": number
  },
  "string": {
    "id": "string",
    "status": "string",
    "payment_status": "string",
    "created": number,
    "expires_at": number,
    "account_id": number,
    "url": null,
    "metadata": {
      "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
      "cid": "number",
      "email": "<string@iliken.com>",
      "lang": "string",
      "name": "string",
      "td_cid": "string"
    },
    "amount_total": number
  }
}

The response returns a list with the payment ID as the key and the payment information as the value.

• id (string): Unique identifier for the client bill.
• status (string): Status of the client bill
  • Open
  • Expired
  • Complete
• payment_status (string): Payment status of the client bill (paid, unpaid)
• created (number): Date of creation of the bill.
• expires_at (number): Date of bill expiration.
• account_id (number): ID of the client's account.
• url (string): Link for payment.
• amount_total (number): Total amount of the bill.

Total amount of the bill represented in the smallest currency unit (e.g., for EUR, the amount is in cents. So, 25 EUR is represented as 2500).

• metadata (object): Contains additional information about the payment:
  • app_id (string): Application ID to which the bill belongs (currently, it is Forguard: b901da51-ce00-4af2-b978-8d0fca8ae1ea).
  • cid (number): Client account ID.
  • email (string): Client account email.
  • lang (string): Client account language.
  • name (string): Payment name.
  • td_cid (string): Service provider ID.

Create Client bill

This endpoint allows you to create a bill with a payment link for the client. You specify the amount, product, currency, and other information to generate the bill. The response includes the bill details and a payment link. Clients can use this link to pay the bill created by you.

Example of the bill issued by the service provider, viewed by the client through the payment link:

POST /billing/stripe-payments

Mandatory request fields:

• app_id: The application ID. Currently, this applies only to Forguard.

Forguard app_id: b901da51-ce00-4af2-b978-8d0fca8ae1ea

• account_id: The ID of the client's account.
• prices: An array of price objects, each containing:
  • quantity: The quantity of the product.
  • currency: The currency in which the amount is specified.

For example - "eur"

• • unit_amount: The unit cost of the product or service.

Total amount must convert to at least 50 cents

• • name: The name of the product.

Request example:

curl -X 'POST' \
'https://api.gps-trace.com/billing/stripe-payments' \
-H 'accept: application/json' \
-H 'X-AccessToken: ' \
-H 'Content-Type: application/json' \
-d '{
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
  "account_id": number,
  "prices": [
    {
      "quantity": number,
      "currency": "string",
      "unit_amount": number,
      "name": "string"
    },
    {
      "quantity": number,
      "currency": "string",
      "unit_amount": number,
      "name": "string"
    }
  ],
  "name": "string"
}'

201 response example:

{
  "id": "string",
  "status": "string",
  "payment_status": "string",
  "created": number,
  "expires_at": number,
  "account_id": number,
  "url": "",
  "metadata": {
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "cid": "string",
    "email": "string",
    "lang": "string",
    "td_cid": "string"
  },
  "amount_total": number
}

The response returns a list with the payment ID as the key and the payment information as the value.

• id (string): Unique identifier for the client payment bill.
• status (string): Status of the client payment bill
  • Open
  • Expired
  • Complete
• payment_status (string): Payment status of the client payment bill (paid, unpaid)
• created (number): Date of creation of the bill.
• expires_at (number): Date of bill expiration.
• account_id (number): ID of the client's account.
• url (string): Link for payment.
• amount_total (number): Total amount of the bill.

Total amount of the bill represented in the smallest currency unit (e.g., for EUR, the amount is in cents. So, 25 EUR is represented as 2500).

• metadata (object): Contains additional information about the payment:
  • app_id (string): Application ID to which the bill belongs (currently, it is Forguard: b901da51-ce00-4af2-b978-8d0fca8ae1ea).
  • cid (number): Client account ID.
  • email (string): Client account email.
  • lang (string): Client account language.
  • name (string): Payment name.
  • td_cid (string): Service provider ID.

Send Payment link by email

This method sends a payment notification via email to the client associated with the specified payment ID. The email is sent to the email address linked to the Forguard account on which the bill is issued. The email contains a payment link. When the client clicks on this link, they are directed to a page where they can view the bill issued by you, along with its description and all the necessary tools for making the payment.

POST /billing/stripe-payments/{payment_id}/send

Mandatory request fields:

• payment_id (string): Unique identifier for the client payment bill.
• app_id (string): Application ID to which the bill belongs.

Currently, this is set to "Forguard" with the ID b901da51-ce00-4af2-b978-8d0fca8ae1ea.

Request example:

curl -X 'POST' \
'https://api.gps-trace.com/billing/stripe-payments//send?app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

Upon a successful request, the response will include a field "result" set to true.

Expire Client Bill

This endpoint allows you to forcibly change the status of a client's bill to "expired". This method is useful for expiring bills that are no longer relevant or were generated by mistake, without having to wait for the auto-expire process.

POST /billing/stripe-payments/{payment_id}/expire

Mandatory request fields:

• payment_id (string): Unique identifier for the client payment bill.
• app_id (string): Application ID to which the bill belongs.

Currently, this is set to "Forguard" with the ID b901da51-ce00-4af2-b978-8d0fca8ae1ea.

• account_id (number): ID of the client's account where the bill is issued.

Request example:

curl -X 'POST' \
'https://api.gps-trace.com/billing/stripe-payments//expire' \
-H 'accept: application/json' \
-H 'X-AccessToken: ' \
-H 'Content-Type: application/json' \
-d '{
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
  "account_id": 
}'

200 response example:

{
  "id": "",
  "status": "expired",
  "payment_status": "string",
  "created": number,
  "expires_at": number,
  "account_id": number,
  "url": null,
  "metadata": {
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "cid": "string",
    "email": "string",
    "lang": "string",
    "name": "string",
    "td_cid": "string"
  },
  "amount_total": number
}

• id (string): Unique identifier for the client payment bill.
• status (string): Status of the client payment bill
  • Open
  • Expired
  • Complete
• payment_status (string): Payment status of the client payment bill.

Expected value: expired

• created (number): Date of creation of the bill.
• expires_at (number): Date of bill expiration.
• account_id (number): ID of the client's account.
• url (string): Link for payment.
• amount_total (number): Total amount of the bill.

Total amount of the bill represented in the smallest currency unit (e.g., for EUR, the amount is in cents. So, 25 EUR is represented as 2500).

• metadata (object): Contains additional information about the payment:
  • app_id (string): Application ID to which the bill belongs (currently, it is Forguard: b901da51-ce00-4af2-b978-8d0fca8ae1ea).
  • cid (number): Client account ID.
  • email (string): Client account email.
  • lang (string): Client account language.
  • name (string): Payment name.
  • td_cid (string): Service provider ID.

Get bill items

This endpoint allows you to retrieve all information about a specific issued bill, including its items.

GET /billing/stripe-payments/{payment_id}/items

Request Parameters:

• payment_id (string): Unique identifier for the client payment bill.
• app_id (string): Application ID to which the bill belongs.

Currently, this is set to "Forguard" with the ID b901da51-ce00-4af2-b978-8d0fca8ae1ea.

• account_id (number): ID of the client's account where the bill is issued.

Request example:

curl -X 'GET' \
'https://api.gps-trace.com/billing/stripe-payments/?app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea&account_id=' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

200 response example:

{
  "id": "string",
  "object": "string",
  "amount_discount": number,
  "amount_subtotal": number,
  "amount_tax": number,
  "amount_total": number,
  "currency": "string",
  "description": "string",
  "price": {
    "id": "string",
    "object": "string",
    "active": false,
    "billing_scheme": "string",
    "created": number,
    "currency": "string",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "string",
    "recurring": null,
    "tax_behavior": "string",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "string",
    "unit_amount": number,
    "unit_amount_decimal": "string"
  },
  "quantity": number
}

The response contains an array of data objects. Each object represents an item in the bill with detailed information about the item. Here are the fields included in each item:

• id (string): Unique identifier for the product.
• object (string): String representing the object's type. In this case, it is "item". Objects of the same type share the same value. Always has the value list
• amount_discount (integer): Amount of discount applied to the item (in the specified currency). If no discounts were applied, defaults to 0.
• amount_subtotal (integer): Subtotal amount for the item before tax (in the specified currency).
• amount_tax (integer): Amount of tax applied to the item (in the specified currency). If no tax was applied, defaults to 0
• amount_total (integer): Total amount for the item after discounts and tax (in the specified currency).
• currency (string): Three-letter ISO currency code, in lowercase.
• description (string): Description of the item, useful for displaying to users.
• price (object): Details about the price of the item, which includes:
  • id (string): Unique identifier for the price object.
  • object (string): String representing the object's type. In this case, it is "price".
  • active (boolean): Indicates if the price object is active.
  • billing_scheme (string): Billing scheme used. It can be "per_unit" or other supported schemes.
  • created (integer): Timestamp of when the price object was created.
  • currency (string): Three-letter ISO currency code, in lowercase.
  • custom_unit_amount (nullable): Custom unit amount if applicable.
  • livemode (boolean): Indicates if the object exists in live mode (true) or test mode (false).
  • lookup_key (nullable string): Lookup key for the price object.
  • metadata (object): Set of key-value pairs attached to the price object.
  • nickname (nullable string): Nickname for the price object.
  • product (string): The ID of the product associated with this price.
  • recurring (nullable): Details about recurring pricing, if applicable.
  • tax_behavior (string): Tax behavior, can be "inclusive", "exclusive", or "unspecified".
  • tiers_mode (nullable): Tiers mode if applicable.
  • transform_quantity (nullable): Transform quantity details if applicable.
  • type (string): Type of pricing, e.g., "one_time".
  • unit_amount (integer): Unit amount (in the specified currency).
  • unit_amount_decimal (string): Same as unit_amount, but contains a decimal value with at most 12 decimal places.
• quantity (integer): Quantity of the item.