- Metronome immediately triggers a payment attempt based on the invoice amount of the commit.
- If the payment succeeds, Metronome releases the commit and the customer is granted access to the associated balance.
- If the payment fails, Metronome voids the resource and sends a webhook notification.
- 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_typetoSTRIPE, 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_idcustom field on the Metronome product entity, set its value to the corresponding Stripe Product ID, and add a Stripe integration mapping rule fromstripe_product_idtoinvoiceitem.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.Manage notifications
Two types of webhook notifications are emitted when creating a payment-gated commit:payment_gate.payment_statusafter payment has been attempted. The status of that payment,paidorfailed, is denoted in thepayment_statusfield.payment_gate.payment_pending_action_requiredif intervention is required to process payment.
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).