Integrate invoicing
Configure API access, create products and customers, issue invoices, process payments, and handle webhook events to integrate Solidgate invoicing
Solidgate invoicing handles one-time charges from creation to settlement in Billing 2.0. Configure products, prices, and customers once, then issue invoices. Set up webhook handling to track every status change.
Step 1. Get API credentials
To use the Solidgate API, you need API keys. Get your keys before proceeding with the integration:
- SolidgateAPI v1 keys: for products and prices
- SolidgateAPI v2 keys: for customers and invoices
To generate API keys
- Go to Developers.
Select the API version.
- For API v1: select the channel you need, then on the Channel details page find the API keys.
- For API v2: go to Keys, click on Create API key, name your key and optionally select a channel or multiple channels, then click on Create.
- Copy your API key.
Step 2. Create product
A product represents the goods or services you offer. Create a product before issuing an invoice. Products are shared across Billing 1.0 and Billing 2.0. You can create and manage products in the Hub or through the SolidgateAPI v1.
Step 3. Create price
A price defines the cost of a product. Create a price before issuing an invoice. Prices are shared across Billing 1.0 and Billing 2.0. You can create and manage prices in the Hub or through the SolidgateAPI v1.
Step 4. Create customer
An invoice requires a customer record to identify who is being charged.
A customer can be an existing record or created specifically for the invoice. You can create and manage customers in the Hub or through the SolidgateAPI v2.
Step 5. Create invoice
Create an invoice in draft status, update it with checkout data, then finalize it to prepare for payment.
Send a request to the create invoiceAPI v2 endpoint with a customer ID, a merchant reference, and at least one line item.
Pass the customer_id and merchant_reference values, and at least one line_items entry with a product_price_id and quantity. Optionally, include a channel_id, discounts to apply a coupon, and notes for internal reference.
The merchant_reference value is required, must be unique within the channel, and can contain only letters, numbers, hyphens, and underscores, up to 100 characters. A duplicate value returns a MERCHANT_REFERENCE_DUPLICATE error.
The response returns the full invoice object, including the calculated price breakdown with subtotal, discount, tax, and total amounts. To retrieve invoice details later, use the get invoiceAPI v2 endpoint.
The customer, product, and product price must already exist in the system before creating an invoice. You select them from dropdowns during the creation flow.
To create an invoice
- Go to Billing > Billing 2.0 > Invoices.
- Click on Create invoice.
- Select a Customer from the dropdown.
- Set the Due date for invoice payment.
- Optionally, select a Coupon to apply a discount.
- Select a Channel.
- Optionally, add a Note.
- Select a Currency value from the dropdown.
- In the line item section, select a Product, its Price, and set the Quantity.
- Click on Save to add the line item.
- Click on Create invoice.
The invoice is created in the draft status. You can view it in the invoice list and open the details page to edit, void, or delete it.
Key information
- An invoice can include one or more one-time product line items. Set the quantity on each item to match the number of units purchased.
- All monetary values are in minor units (cents). For example,
20000represents $200.00. - Tax is zero at creation if no address is present. Tax is calculated when you add an address to the invoice.
- Only draft invoices can be modified. After finalization, the invoice cannot be edited.
- Each invoice requires a unique
merchant_referencewithin the channel. Use it to match invoices to records in your own system.
Update invoice
Update a draft invoice when checkout data changes, such as the customer address, coupon, quantity, or identity fields.
Send a request to the update invoiceAPI v2 endpoint with the invoice ID and the fields to modify. Only the fields you include in the request are updated.
You can update line items, discounts, notes, due date, and customer details. When you include a customer address, Solidgate recalculates tax and returns updated totals.
When updating the customer object, include only the fields you want to change. Omitted fields are not updated.
To update an invoice in a draft status
- Go to Billing > Billing 2.0 > Invoices.
- Click on the invoice ID to open the details page.
- Use the Edit buttons next to Customer, Billing address, or Items to modify the relevant fields and save changes as you make them.
Changes to the billing address trigger automatic tax recalculation.
Customer details
Customer data is captured at finalization. If you update a customer record after an invoice is created, the change does not affect that invoice. You can update customer data through the invoice update endpoint. This changes only the data on that invoice and does not modify the customer object.
For finalization to succeed, the customer details on the invoice must include email, first name, last name, IP address, and at least a country in the address.
Step 6. Pay invoice
Before payment, finalize the invoice to move it from DRAFT to OPEN. Send a request to the finalize invoiceAPI v2 endpoint with the invoice ID.
Once the invoice is open, send a request to the pay invoiceAPI v2 endpoint with the id of the invoice and the payment_instrument_id.
The payment result arrives asynchronously through a webhook event. Listen for the INVOICE_PAID event to confirm the charge.
Payment Form
To collect payment through the Solidgate Payment Form, generate a payment intent with a checkout object. Set mode to invoice and pass the customer_id, a merchant_reference, and one line_items entry with a product_price_id and quantity.
You do not need to create or finalize an invoice through the API first. The Payment Form creates the invoice, collects the customer’s address, finalizes it, and processes the charge when the customer pays.
After the form is initialized, replace line items or the coupon with
The form reports the calculated invoice through the
The payment result arrives asynchronously through a webhook event. Listen for the INVOICE_PAID event to confirm the charge.
Payment Page
To collect payment through a Solidgate Payment Page, finalize the invoice first to move it to OPEN status. Pass the invoice_id when creating the page, then redirect the customer to the payment page URL.
Payment Link
To collect payment through a Solidgate Payment Link, finalize the invoice first to move it to OPEN status. Pass the invoice_id when creating the link, then share it with the customer. For example, send it to their email.
Handle events
To track the invoice lifecycle and get updates about its status, subscribe to invoice-related webhook events. Solidgate sends an INVOICE_PAID event when payment completes. Listen for this event to trigger fulfillment.
Send a request to the create webhookAPI v2 endpoint with a name, URL, and the list of events you want to receive.
Pass the name to identify the endpoint, url where Solidgate should send events, and events as an array of event types to subscribe to. Optionally include channel_id to scope the endpoint to a specific channel.
Manage webhooks with the full set of webhook management operationsAPI v2.
To set up a webhook endpoint
- Go to Developers and select API v2.
- Go to Webhook endpoints.
- Click on Create webhook endpoint.
- Enter a name, the endpoint URL, and select the events to subscribe to.
- Optionally, select a channel to filter events by channel.
- Save the endpoint and copy the signing secret (
wsec_…) issued for your endpoint.
Billing 2.0 uses a single signing secret per endpoint, not a public and secret key pair as in Billing 1.0 webhooks.
Invoice events
| Event | Description |
|---|---|
INVOICE_CREATED | An invoice was created. Invoice createdWebhook |
INVOICE_UPDATED | An invoice was modified. Invoice updatedWebhook |
INVOICE_FINALIZED | An invoice moved from draft to open. Invoice finalizedWebhook |
INVOICE_PAID | Payment was authorized and the purchase can be activated. Invoice paidWebhook |
INVOICE_PAYMENT_FAILED | A payment attempt was declined. Invoice payment failedWebhook |
INVOICE_DUNNING_STARTED | Dunning started. Invoice dunning startedWebhook |
INVOICE_UNPAID | The invoice was unpaid. Invoice unpaidWebhook |
INVOICE_VOIDED | The invoice was canceled or expired. Invoice voidedWebhook |
INVOICE_DELETED | The invoice was deleted. Invoice deletedWebhook |
INVOICE_FINALIZATION_FAILED | Finalization was rejected due to missing required data. Invoice finalization failedWebhook |
Every successful charge, whether it is the subscription’s first payment or a later renewal, triggers INVOICE_PAID. Use the billing_reason field in the event payload to identify the charge reason:
billing_reasonissubscription_createfor a subscription’s first (activation) invoice.billing_reasonissubscription_cyclefor a renewal invoice.billing_reasonismanualfor a manually created invoice.
Invoice status transitions
Each action on an invoice triggers a status change and a corresponding webhook event. Your integration receives the outcome through the webhook with the corresponding status.
| Status | API endpoint | Webhook | Resulting status |
|---|---|---|---|
DRAFT | Delete invoiceAPI v2 | Invoice deletedWebhook | (Deleted) |
DRAFT | Finalize invoiceAPI v2 | Invoice finalization failedWebhook | DRAFT |
DRAFT | Finalize invoiceAPI v2 | Invoice finalizedWebhook | OPEN |
OPEN | Pay invoiceAPI v2 | Invoice payment failedWebhook | OPEN |
OPEN | Pay invoiceAPI v2 | Invoice paidWebhook | PAID |
OPEN | Void invoiceAPI v2 | Invoice voidedWebhook | VOIDED |
OPEN | Part of dunning process | Invoice dunning startedWebhook | DUNNING |
DUNNING | Part of dunning process | Invoice paidWebhook | PAID |
DUNNING | Void invoiceAPI v2 | Invoice voidedWebhook | VOIDED |
DUNNING | Part of dunning process | Invoice unpaidWebhook | UNPAID |
Finalization moves an invoice from draft to open. This transition is permanent.