# Solidgate API Reference Solidgate API v2 follows a consistent, predictable endpoint structure across all operations.

OpenAPI specification

Full schema for programmatic integration: endpoint paths, request/response shapes, and field definitions.

YA ML YAML JSON

Frontend SDK

These are the primary frontend libraries. Use them to embed payment forms directly in your client-side application

React Vue Angular

Backend SDK

Multiple backend libraries to manage server-side processing, advanced integrations, form resign flows, and reconciling orders.

php PHP JS Node.js Go Kotlin Python

Enhance understanding with our payment guide.
For help, write to support@solidgate.com.

Version: 2.0.0 License: Terms and policies ## Servers Solidgate API ``` https://api.solidgate.com/v2 ``` ## Security ### bearerAuth Secret value sent in the `Authorization` header using the `Bearer` scheme. Type: http Scheme: bearer Bearer Format: SECRET ### signatureAuth Base64-encoded HMAC-SHA256 of the raw request body, computed with the webhook endpoint's secret key. Type: apiKey In: header Name: Signature ## Download OpenAPI description [Solidgate API Reference](https://api-docs.solidgate.com/_bundle/api/@v2/index.yaml) ## API keys Create, list, retrieve, and rotate API keys so you can securely authenticate requests and control access to the API. ### Create API key - [POST /api-keys/create](https://api-docs.solidgate.com/api/v2/api-keys/create-api-key.md): Creates a new API key for authentication and authorization. This endpoint requires an account-level API key. ### List API keys - [POST /api-keys/list](https://api-docs.solidgate.com/api/v2/api-keys/list-api-key.md): Retrieves a paginated list of API keys for the specified account. This endpoint requires an account-level API key. ### Get API key - [POST /api-keys/get](https://api-docs.solidgate.com/api/v2/api-keys/get-api-key.md): Returns details and permissions for the specified API key. This endpoint requires an account-level API key. ### Rotate API key - [POST /api-keys/rotate](https://api-docs.solidgate.com/api/v2/api-keys/rotate-api-key.md): Rotates the secret key for the specified API key. Returns a new secret in the rotate_secret field, which becomes valid within a few seconds. The previous secret remains valid during the rotation period and expires once the period ends. This endpoint requires an account-level API key. ## Channels List the channels available to your account so you can use them in API operations, such as configuring API keys. ### List channels - [POST /channels/list](https://api-docs.solidgate.com/api/v2/channels/list-channel.md): Retrieves a paginated list of channels for the specified account. This endpoint requires an account-level API key. ## Webhooks Create, list, patch, delete, and retrieve webhook endpoints, manage secret keys, and receive events when customer or invoice records change. ### Create webhook - [POST /webhooks/create](https://api-docs.solidgate.com/api/v2/webhooks/create-webhook.md): Creates a new webhook endpoint to receive payment and order events. Webhook endpoints are inactive until activated by calling the patch endpoint with the status set to ACTIVE. ### List webhooks - [POST /webhooks/list](https://api-docs.solidgate.com/api/v2/webhooks/list-webhook.md): Retrieves a paginated list of webhook endpoints. ### Get webhook - [POST /webhooks/get](https://api-docs.solidgate.com/api/v2/webhooks/get-webhook.md): Retrieves webhook endpoint details by ID. ### Patch webhook - [POST /webhooks/patch](https://api-docs.solidgate.com/api/v2/webhooks/patch-webhook.md): Updates an existing webhook endpoint configuration. ### Delete webhook - [POST /webhooks/delete](https://api-docs.solidgate.com/api/v2/webhooks/delete-webhook.md): Deletes a webhook endpoint. ### Rotate webhook key - [POST /webhooks/rotate-key](https://api-docs.solidgate.com/api/v2/webhooks/rotate-webhook-key.md): Rotates the secret for the specified webhook key. Returns a new secret in the rotate_secret field, which becomes valid within a few seconds. The previous secret remains valid during the rotation period and expires once the period ends. ## Customers Create, update, and retrieve customer records to keep data consistent across payments and billing. ### Create customer - [POST /customers/create](https://api-docs.solidgate.com/api/v2/customers/create-customer.md): Creates a new customer. ### Update customer - [POST /customers/update](https://api-docs.solidgate.com/api/v2/customers/update-customer.md): Updates specified customer fields. ### Get customer - [POST /customers/get](https://api-docs.solidgate.com/api/v2/customers/get-customer.md): Returns the customer for the provided identifier. ### List customers - [POST /customers/list](https://api-docs.solidgate.com/api/v2/customers/list-customers.md): Returns a paginated list of customers. ### Customer created - [POST CustomerCreated](https://api-docs.solidgate.com/api/v2/customers/on-customer-created.md): Webhook sent when a new customer is created. ### Customer updated - [POST CustomerUpdated](https://api-docs.solidgate.com/api/v2/customers/on-customer-updated.md): Webhook sent when a customer is updated. ## Payment instruments List, retrieve, and revoke customer payment instruments and receive events when payment instruments change. ### Get payment instrument - [POST /payment-instruments/get](https://api-docs.solidgate.com/api/v2/payment-instruments/get-payment-instrument.md): Returns the payment instrument for the provided identifier. ### List payment instruments - [POST /payment-instruments/list](https://api-docs.solidgate.com/api/v2/payment-instruments/list-payment-instruments.md): Returns a paginated list of payment instruments for the specified customer. ### Revoke payment instrument - [POST /payment-instruments/revoke](https://api-docs.solidgate.com/api/v2/payment-instruments/revoke-payment-instrument.md): Revokes an active payment instrument and prevents it from being used for future payments. ### Payment instrument created - [POST PaymentInstrumentCreated](https://api-docs.solidgate.com/api/v2/payment-instruments/on-payment-instrument-created.md): Webhook sent when a new payment instrument is created. ### Payment instrument revoked - [POST PaymentInstrumentRevoked](https://api-docs.solidgate.com/api/v2/payment-instruments/on-payment-instrument-revoked.md): Webhook sent when a payment instrument is revoked. ### Payment instrument expired - [POST PaymentInstrumentExpired](https://api-docs.solidgate.com/api/v2/payment-instruments/on-payment-instrument-expired.md): Webhook sent when a payment instrument expires. ## Invoices Create, update, finalize, void, pay using a saved payment instrument, and retrieve invoices to issue and track billing for your customers. ### Create invoice - [POST /invoices/create](https://api-docs.solidgate.com/api/v2/invoices/create-invoice.md): Creates a new invoice. ### Update invoice - [POST /invoices/update](https://api-docs.solidgate.com/api/v2/invoices/update-invoice.md): Updates specified fields of a draft invoice. ### Finalize invoice - [POST /invoices/finalize](https://api-docs.solidgate.com/api/v2/invoices/finalize-invoice.md): Finalizes a draft invoice. ### Void invoice - [POST /invoices/void](https://api-docs.solidgate.com/api/v2/invoices/void-invoice.md): Voids an unpaid invoice. ### Delete invoice - [POST /invoices/delete](https://api-docs.solidgate.com/api/v2/invoices/delete-invoice.md): Deletes a draft invoice. ### Get invoice - [POST /invoices/get](https://api-docs.solidgate.com/api/v2/invoices/get-invoice.md): Returns the invoice for the provided identifier. ### List invoices - [POST /invoices/list](https://api-docs.solidgate.com/api/v2/invoices/list-invoices.md): Returns a paginated list of invoices. ### Pay invoice - [POST /invoices/pay](https://api-docs.solidgate.com/api/v2/invoices/pay-invoice.md): Pays a finalized invoice using a saved payment instrument. ### Invoice created - [POST InvoiceCreated](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-created.md): Webhook sent when a new invoice is created. ### Invoice updated - [POST InvoiceUpdated](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-updated.md): Webhook sent when an invoice is updated. ### Invoice finalized - [POST InvoiceFinalized](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-finalized.md): Webhook sent when an invoice is finalized. ### Invoice finalization failed - [POST InvoiceFinalizationFailed](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-finalization-failed.md): Webhook sent when an invoice finalization fails. ### Invoice paid - [POST InvoicePaid](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-paid.md): Webhook sent when an invoice is paid. ### Invoice voided - [POST InvoiceVoided](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-voided.md): Webhook sent when an invoice is voided. ### Invoice deleted - [POST InvoiceDeleted](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-deleted.md): Webhook sent when an invoice is deleted. ### Invoice payment failed - [POST InvoicePaymentFailed](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-payment-failed.md): Webhook sent when an invoice payment fails. ### Invoice payment refunded - [POST InvoicePaymentRefunded](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-payment-refunded.md): Webhook sent when an invoice payment is refunded. ### Invoice dunning started - [POST InvoiceDunningStarted](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-dunning-started.md): Webhook sent when an invoice enters the dunning process. ### Invoice unpaid - [POST InvoiceUnpaid](https://api-docs.solidgate.com/api/v2/invoices/on-invoice-unpaid.md): Webhook sent when an invoice becomes unpaid. ## Subscriptions Create subscriptions and retrieve them to view status, line items, and recurring billing details for your customers. ### Create subscription - [POST /subscriptions/create](https://api-docs.solidgate.com/api/v2/subscriptions/create-subscription.md): Creates a new subscription. ### Get subscription - [POST /subscriptions/get](https://api-docs.solidgate.com/api/v2/subscriptions/get-subscription.md): Returns the subscription for the provided identifier. ### List subscriptions - [POST /subscriptions/list](https://api-docs.solidgate.com/api/v2/subscriptions/list-subscriptions.md): Returns a paginated list of subscriptions. ### Cancel subscription - [POST /subscriptions/cancel](https://api-docs.solidgate.com/api/v2/subscriptions/cancel-subscription.md): Cancels the subscription immediately or schedules cancellation for the end of the current billing period. ### Delete subscription cancellation - [POST /subscriptions/delete-cancellation](https://api-docs.solidgate.com/api/v2/subscriptions/delete-subscription-cancellation.md): Removes the cancellation scheduled for the end of the current billing period by the subscription cancel operation with mode PERIOD_END, keeping the subscription active. ### Update subscription - [POST /subscriptions/update](https://api-docs.solidgate.com/api/v2/subscriptions/update-subscription.md): Applies targeted updates to an active subscription, including updating the payment instrument, discount, description, and metadata, ending a trial period, and managing line items. For example, trial end uses an explicit mode, and line items are managed by adding, updating, and removing entries instead of full replacement. Each update is applied only when its corresponding field is present in the request. ### Subscription created - [POST SubscriptionCreated](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-created.md): Webhook sent when a new subscription is created. ### Subscription updated - [POST SubscriptionUpdated](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-updated.md): Webhook sent when a subscription is updated. ### Subscription scheduled for cancellation - [POST SubscriptionScheduledForCancellation](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-scheduled-for-cancellation.md): Webhook sent when a subscription is scheduled for cancellation. ### Subscription cancelled - [POST SubscriptionCancelled](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-cancelled.md): Webhook sent when a subscription is cancelled. ### Subscription trial activated - [POST SubscriptionTrialActivated](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-trial-activated.md): Webhook sent when a subscription trial is activated. ### Subscription activated - [POST SubscriptionActivated](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-activated.md): Webhook sent when a subscription is activated. ### Subscription expired - [POST SubscriptionExpired](https://api-docs.solidgate.com/api/v2/subscriptions/on-subscription-expired.md): Webhook sent when a subscription expires. ## Antifraud lists Manage lists and items to allow or block transactions and reduce chargebacks and fraud. ### Create antifraud list - [POST /antifraud-lists/create](https://api-docs.solidgate.com/api/v2/antifraud-lists/create-antifraud-list.md): Creates a new antifraud list. ### Update antifraud list - [POST /antifraud-lists/update](https://api-docs.solidgate.com/api/v2/antifraud-lists/update-antifraud-list.md): Updates the antifraud list. ### List antifraud lists - [POST /antifraud-lists/list](https://api-docs.solidgate.com/api/v2/antifraud-lists/list-antifraud-list.md): Retrieves a paginated list of antifraud lists. ### Get antifraud list - [POST /antifraud-lists/get](https://api-docs.solidgate.com/api/v2/antifraud-lists/get-antifraud-list.md): Returns the antifraud list for the provided identifier. ### Create antifraud list item - [POST /antifraud-lists/create-item](https://api-docs.solidgate.com/api/v2/antifraud-lists/create-item-antifraud-list.md): Creates a new antifraud list item. ### Delete antifraud list item - [POST /antifraud-lists/delete-item](https://api-docs.solidgate.com/api/v2/antifraud-lists/delete-item-antifraud-list.md): Deletes the antifraud list item for the provided identifier. ### List antifraud list items - [POST /antifraud-lists/list-item](https://api-docs.solidgate.com/api/v2/antifraud-lists/list-item-antifraud-list.md): Retrieves a paginated list of antifraud list items. ## Fraud alerts Receive events when fraud alerts are reported for payments. ### Fraud alert received - [POST FraudAlertReceived](https://api-docs.solidgate.com/api/v2/fraud-alerts/on-fraud-alert-received.md): Webhook sent when a fraud alert is received for a payment. ## Prevention alerts Receive events when prevention alerts are reported for payments. ### Prevention alert received - [POST PreventionAlertReceived](https://api-docs.solidgate.com/api/v2/prevention-alerts/on-prevention-alert-received.md): Webhook sent when a prevention alert is received for a payment. ## Routing Retrieve routing configurations and their versions to inspect how transactions are routed across payment providers, and receive events when routing configuration versions are published. ### Get routing configuration - [POST /routing-configs/get](https://api-docs.solidgate.com/api/v2/routing/get-routing-config.md): Returns the routing configuration for the provided identifier. ### Get routing configuration version - [POST /routing-configs/get-version](https://api-docs.solidgate.com/api/v2/routing/get-routing-config-version.md): Returns the routing configuration version with the full route tree for the provided identifier. ### Routing configuration version published - [POST RoutingConfigVersionPublished](https://api-docs.solidgate.com/api/v2/routing/on-routing-config-version-published.md): Webhook sent when a new routing configuration version is published. ## Reports Reports export your account data in bulk as a CSV file. Each report covers one `report_type` and one date range. Records are selected by their creation date, where `date_from` is inclusive and `date_to` is exclusive. Reports contain only the account and channels the API key can access. Reports expire 30 days after creation. Column layout of each report file, by report type.
INVOICES
Invoices created in the date range, with one row per invoice line item. Deleted invoices are excluded.
| Column | Type | Description | | --- | --- | --- | | id | string | Unique invoice identifier. | | status | string | Current invoice status: `DRAFT`, `OPEN`, `PAID`, `VOIDED`, `DUNNING`, `UNPAID`. | | currency | string | Three-letter ISO-4217 currency code. | | total_amount | integer | Total invoice amount in minor units. | | notes | string | Additional notes for the invoice. | | merchant_reference | string | Merchant-defined reference for the invoice. | | pdf_url | string | URL to download the invoice PDF. | | created_at | datetime | Date and time when the invoice was created. | | updated_at | datetime | Date and time when the invoice was updated. | | due_at | datetime | Date and time when the invoice is due. | | customer_id | string | Unique customer identifier. | | customer_first_name | string | Customer first name. | | customer_last_name | string | Customer last name. | | customer_email | string | Customer email. | | customer_phone | string | Customer phone number. | | customer_address_city | string | Customer city. | | customer_address_country | string | Customer country. | | customer_address_line1 | string | Customer address line 1. | | customer_address_line2 | string | Customer address line 2. | | customer_address_state | string | Customer state. | | customer_address_postal_code | string | Customer postal code. | | customer_tax_taxability | string | Customer taxability: `EXEMPT`, `TAXABLE`. | | amount_details_subtotal | integer | Subtotal amount in minor units before discounts and taxes. | | amount_details_discount | integer | Discount amount in minor units. | | amount_details_taxable | integer | Taxable amount in minor units. | | amount_details_tax | integer | Tax amount in minor units. | | discounts | json | Discounts applied to the invoice, each with `coupon_id` and `coupon_code`. | | line_item_product_price_id | string | Identifier of the associated product price. | | line_item_description | string | Line item description. | | line_item_amount | integer | Line item amount in minor units. | | line_item_currency | string | Three-letter ISO-4217 currency code. | | line_item_quantity | integer | Number of product units. | | line_item_amount_details_subtotal | integer | Line item subtotal in minor units before discounts and taxes. | | line_item_amount_details_discount | integer | Line item discount amount in minor units. | | line_item_amount_details_taxable | integer | Line item taxable amount in minor units. | | line_item_amount_details_tax | integer | Line item tax amount in minor units. | | line_item_tax_category_id | string | Identifier of the tax category. | | line_item_tax_mode | string | Tax calculation mode: `EXCLUSIVE`, `INCLUSIVE`. | | line_item_tax_rate | number | Tax rate as a percentage. |
SUBSCRIPTIONS
Subscriptions created in the date range, with one row per subscription line item, matching Subscriptions.
| Column | Type | Description | | --- | --- | --- | | id | string | Unique subscription identifier. | | customer_id | string | Unique customer identifier. | | status | string | Subscription status: `CREATED`, `PENDING`, `TRIALING`, `ACTIVE`, `REDEMPTION`, `UNPAID`, `CANCELLED`, `EXPIRED`. | | currency | string | Three-letter ISO-4217 currency code. | | description | string | Additional description for the subscription. | | payment_instrument_id | string | Identifier of the payment instrument used for billing. | | latest_invoice_id | string | Identifier of the most recent invoice. | | merchant_reference | string | Merchant-defined reference for the subscription. | | created_at | datetime | Date and time when the subscription was created. | | updated_at | datetime | Date and time when the subscription was updated. | | started_at | datetime | Date and time when the subscription started. | | next_billing_at | datetime | Date and time when the next billing occurs. | | anchor_at | datetime | Date and time used to anchor billing cycles. | | trial_info_type | string | Trial type: `FREE`, `PAID`. | | trial_info_amount | integer | Trial amount in minor units. | | trial_info_period_start_at | datetime | Date and time when the trial period starts. | | trial_info_period_end_at | datetime | Date and time when the trial period ends. | | trial_info_period_config_value | integer | Number of units in the trial period. | | trial_info_period_config_unit | string | Trial period unit: `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`. | | cancellation_info_cancel_at | datetime | Date and time when the subscription is scheduled to be cancelled or was cancelled. | | cancellation_info_requested_at | datetime | Date and time when cancellation was requested. | | cancellation_info_reason | string | Cancellation reason: `DUNNING_EXHAUSTED`, `CANCELLATION_REQUESTED`. | | cancellation_info_comment | string | Additional cancellation comment. | | discounts | json | Discounts applied to the subscription, each with `coupon_id` and `coupon_code`. | | metadata | json | Set of key-value pairs attached to the subscription. | | line_item_id | string | Unique line item identifier. | | line_item_product_id | string | Identifier of the associated product. | | line_item_product_price_id | string | Identifier of the associated product price. | | line_item_billing_type | string | Line item billing type: `RECURRING`, `ONE_TIME`. | | line_item_currency | string | Three-letter ISO-4217 currency code. | | line_item_amount | integer | Line item amount in minor units. | | line_item_quantity | integer | Number of product units. | | line_item_started_at | datetime | Date and time when the line item started. | | line_item_period_start_at | datetime | Date and time when the billing period starts. | | line_item_period_end_at | datetime | Date and time when the billing period ends. | | line_item_billing_period_config_value | integer | Number of units in the billing period. | | line_item_billing_period_config_unit | string | Billing period unit: `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`. | | line_item_product_info_name | string | Product name. | | line_item_product_info_description | string | Product description. | | line_item_created_at | datetime | Date and time when the line item was created. | | line_item_updated_at | datetime | Date and time when the line item was updated. |
### Create report - [POST /reports/create](https://api-docs.solidgate.com/api/v2/reports/create-report.md): Creates a report for the specified date range. The report is processed asynchronously. Once processing completes, use the returned id to download it. ### Download report - [POST /reports/download](https://api-docs.solidgate.com/api/v2/reports/download-report.md): Returns a 303 redirect to a short-lived download URL. ### List reports - [POST /reports/list](https://api-docs.solidgate.com/api/v2/reports/list-reports.md): Returns reports available to the current API key, sorted by creation date (newest first). The response includes only report types the API key has access to. Supports cursor-based pagination.