Client's billing
Our platform enables partners to create bill 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:
- Partner's Stripe Account:
Partners need a Stripe account to obtain their API Secret key, essential for conducting Client Billing operations. This key is located in the Developers section of the Stripe account.
It's important to disable Test mode to generate a live Secret API key. - Stripe Secret key integration in Partner Panel:
Partners can integrate the Secret key into their Partner Panel. This can typically be done in the Client Billing tab by clicking on the settings icon. - Creating Bills with payment links:
After integrating the Secret key into their Partner Panel, partners gain the ability to create bill 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 partners to perform various operations seamlessly. It allows:
- Operations with Stripe secret key.
- Creating bill with payment links for clients.
- Sending payment link emails to clients.
- Retrieving information about all bills, including their statuses and other details.
With these capabilities, partners can efficiently manage payment processes and track the status of invoices issued to their clients.
Get Stripe secret key
Partners need a Stripe account to obtain their API Secret key, essential for conducting Client Billing operations. This key is located in the Developers section of the Stripe account. It's important to disable Test mode to generate a live Secret API key.
Once the API Secret key is linked to the partner account (Partner Panel account), partners 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.
This endpoint allows to retrieve information about Stripe secret key associated with the Partner Panel account.
GET /billing/secret-key
Required field passed in the request:
app_id - The ID of the application assigned to the client account.
Currently, it is only Forguard (Forguard app_id: b901da51-ce00-4af2-b978-8d0fca8ae1ea).
Request example:
curl -X 'GET' \
'https://api.gps-trace.com/billing/secret-key?app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
200 Response example:
{
"data": {
"id":number,
"stripe_partner": {
"secret_key": "string",
"webhook_id": "string",
"webhook_secret": "string"
}
}
}
- id: Id of partner account (Partner Panel account)
- stripe_partner:
- secret _key - The secret_key is used to authenticate your API requests to Stripe.
- webhook_id - The webhook ID
- webhook_secret - The webhook_secret is a key used to verify the authenticity of webhook events sent by Stripe.
Set Stripe secret key
Partners need a Stripe account to obtain their API Secret key, essential for conducting Client Billing operations. This key is located in the Developers section of the Stripe account.
It's important to disable Test mode to generate a live Secret API key.
Once the API Secret key is linked to the partner account (Partner Panel account), partners 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.
This endpoint enables partners to associate their Stripe account's API Secret key with their Partner Panel account. This key is crucial for performing Client Billing operations.
POST /billing/secret-key
The request body must include the following mandatory fields:
- "app_id": The ID of the application assigned to the client account. Currently, it is only Forguard (Forguard app_id: b901da51-ce00-4af2-b978-8d0fca8ae1ea).
- "secretKey": The Stripe API Secret key.
Request example:
curl -X 'POST' \
'https://api.gps-trace.com/billing/secret-key' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
"secretKey": "string"
}'
201 Body response example:
{
"data": {
"id":number,
"stripe_partner": {
"secret_key": "string",
"webhook_id": "string",
"webhook_secret": "string"
}
}
}
- id: Id of partner account (Partner Panel account)
- stripe_partner:
- secret _key - The secret_key is used to authenticate your API requests to Stripe.
- webhook_id - The webhook ID
- webhook_secret - The webhook_secret is a key used to verify the authenticity of webhook events sent by Stripe.
Get client bills
This endpoint allows partners 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=<begin timestamp>&to=<end timestamp>&account_id=<account id>&fields=' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
200 response example:
{
"data": {
"string": {
"id": "string",
"status": "open",
"payment_status": "string",
"created": number,
"expires_at": number,
"account_id": number,
"url": "<link for payment>",
"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): Partner ID.
Create Client bill
This endpoint allows partners to create a bill with a payment link for the client.
The partner specifies 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 the partner.
Example of the bill issued by the partner, 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: <your token>' \
-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:
{
"data": {
"id": "string",
"status": "string",
"payment_status": "string",
"created": number,
"expires_at": number,
"account_id": number,
"url": "<link for payment>",
"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): Partner 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 the partner, 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/<payment id>/send?app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token> ''
Upon a successful request, the response will include a field "result" set to true.
Expire Client Bill
This endpoint allows 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/<payment_id>/expire' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
"account_id": <client account id>
}'
200 response example:
{
"data": {
"id": "<payment_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): Partner 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/<payment_id>?app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea&account_id=<client account id>' \
-H 'accept: application/json' \
-H 'X-AccessToken: <token>'
200 response example:
{
"data": [
{
"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.