A payment instrument is a tokenized representation of a customer’s payment method, such as a card or PayPal account. Solidgate creates payment instruments automatically after a successful payment. You can then reuse them to charge the customer for future purchases without requiring them to re-enter payment details.
How payment instruments work
When a customer completes a payment, Solidgate tokenizes the payment details and creates a payment instrument linked to the customer. The first successful payment also sets the instrument as the customer’s default.
Payment instruments store only non-sensitive metadata. No PAN, CVC, or full card numbers are stored in the billing system.
Supported payment methods
| Payment method | Stored details |
|---|---|
| Card | Last four digits, BIN, brand (for example, Visa, Mastercard), card type (debit, credit), issuing bank, expiry month and year. |
| PayPal | PayPal account email address. |
Payment instrument lifecycle
- A customer pays an invoice through a supported payment method.
- Solidgate processes the payment and tokenizes the payment details.
- The system creates a payment instrument and links it to the customer.
- If this is the customer's first payment, the instrument becomes the default.
- The instrument can be reused for future charges through the API.
Payment instrument statuses
| Status | Description |
|---|---|
| ACTIVE | Can be used for new payments. |
| REVOKED | Permanently unusable. Revocation can be triggered by the merchant, by the customer through customer support, or by a system event such as a card block or PayPal billing token revocation. |
| EXPIRED | Cannot be used because the card or instrument has expired. Solidgate monitors expiration dates and sends a notification when an instrument expires, so you can reach out to the customer to update their payment details. |
Status transitions are one-way: an active instrument can move to revoked or expired, but cannot return to active.
Manage payment instruments
View payment instruments
A customer can have multiple payment instruments. View them through the API or on the customer details page in the Hub.
- Go to Billing > Billing 2.0 > Customers.
- Click on the customer ID to open the details page.
- Scroll to the Payment instruments section.
Revoke payment instrument
Revoke an active payment instrument to prevent it from being used for future charges. This action is permanent and cannot be undone.
- Go to Billing > Billing 2.0 > Customers.
- Click on the customer ID to open the details page.
- In the Payment instruments section, expand the instrument you want to revoke.
- Select Revoke.
Default payment instrument
The first successful payment sets the instrument as the customer’s default. The default is stored on the customer record in the configuration.default_payment_instrument_id field, not on the instrument itself.
To check which instrument is the default, retrieve the customer through the get customer API v2 endpoint. In the Hub, the default instrument is marked with a Default badge on the customer details page.
Charge with saved instrument
You can charge a saved payment instrument to pay an invoice without customer interaction. This is common for repeat purchases, upsells, or add-ons.
- Create an invoice for the product.
- Update the invoice with customer details, including IP address.
- Finalize the invoice.
- Send a request to the pay invoice API v2 endpoint with the invoice ID and payment instrument ID.
The payment result arrives asynchronously. Listen for the INVOICE_PAID webhook event to confirm the charge.
Common tasks
Display saved payment methods at checkout
You can retrieve a customer’s saved payment instruments and display them at checkout, so the customer can select a saved method without re-entering payment details.
To retrieve a single instrument, send a request to the get payment instrument API v2 endpoint with the payment instrument ID.
To retrieve all active instruments for a customer, send a request to the list payment instruments API v2 endpoint with the customer_id and filter by ACTIVE status.
Payment instrument events
Solidgate sends webhook notifications for payment instrument changes. Configure webhook endpoints through the Webhooks API v2 or in the Solidgate Hub under Developers > Webhooks.
| Event | Description |
|---|---|
| PAYMENT_INSTRUMENT_CREATED | A payment instrument was created after a successful payment. Instrument created Webhook |
| PAYMENT_INSTRUMENT_REVOKED | A payment instrument was revoked. Instrument revoked Webhook |
| PAYMENT_INSTRUMENT_EXPIRED | A payment instrument expired. Instrument expired Webhook |