Skip to main content
If you have your own purchase interface, or you already create payment-gated commits with the Metronome API, you can continue to use this integration path. To build a new on-session credit purchase flow, use Checkout instead. When a payment-gated commit is created, Metronome facilitates the following:
  1. Metronome immediately triggers a payment attempt based on the invoice amount of the commit.
  2. If the payment succeeds, Metronome releases the commit and the customer is granted access to the associated balance.
  3. If the payment fails, Metronome voids the resource and sends a webhook notification.
  4. If further action is required (e.g. for 2F authentication), Metronome sends a webhook notification.
IMMEDIATELYMetronome initiates payment with your configured billing provider and monitors for completion. In most success cases, payment is completed and credits are released within seconds, but actual timing depends on the payment provider, payment method, and potential authentication challenges.

Before you begin

  • If you use Stripe as the payment provider, make sure the customer has a default payment method in Stripe. Otherwise, the payment fails and Metronome does not create the commit.
  • If you use an external payment provider, make sure that system stores all the information it needs to take the payment.
  • If you set tax_type to STRIPE, also:
    • Store a valid address for the customer in Stripe. Stripe Tax needs the address to calculate tax.
    • Map the Metronome commit product to the associated Stripe product. Without this mapping, the payment attempt fails. To configure this mapping, create a stripe_product_id custom field on the Metronome product entity, set its value to the corresponding Stripe Product ID, and add a Stripe integration mapping rule from stripe_product_id to invoiceitem.price. See Assign line items to Stripe products in the Stripe invoicing guide for step-by-step instructions.

Add a payment-gated commit to an existing contract

Payment gated commits can only be added to existing contracts. You can create a payment-gated commit by editing the user’s contract. Make sure the contract has a valid billing configuration. Each payment-gated commit must meet these limits:
  • The invoice schedule must have exactly one item.
  • The item’s amount must be more than 0 and at least the Stripe minimum charge for the currency (for example, 0.50 USD).
  • By default, each customer can have at most 5 payment-gated commits waiting for payment, across all contracts. More requests fail with Too many pending payments.
SET TIMESTAMP TO NOWGiven payment is attempted immediately, you must set the invoice_schedule.schedule_items.timestamp to the time of or before the request.
See below for an example API call:

Manage notifications

Two types of webhook notifications are emitted when creating a payment-gated commit:
  • payment_gate.payment_status after payment has been attempted. The status of that payment, paid or failed , is denoted in the payment_status field.
  • payment_gate.payment_pending_action_required if intervention is required to process payment.
See our full set of our webhook notifications here.

Handle failed payments

If payment fails, the associated invoice in Metronome and Stripe is voided and no commit is created. To retry the payment, send a new API request with the relevant commit information.
NO AUTOMATIC RETRIESMetronome does not automatically retry failed payments (as any automatic retries would likely fail, too).