Skip to main content
Use a deposit link to collect money up front, before work starts or goods ship, when there’s no invoice to pay yet. You send the customer a link, they pay by card or bank debit, and the money waits as an unapplied payment until you apply it to an invoice. A deposit has two separate questions, and the API answers each one: paid with applied: false is normal. It’s where a deposit sits between the customer paying and you issuing the invoice.

​
The lifecycle

paid isn’t always final:
  • If a bank debit is returned, you get deposit_link.payment_failed, and the link goes back to open so the customer can try again on the same URL. If its expiry has passed, it becomes expired instead.
  • If a payment attached to the link by hand is taken off again, usually because it was the wrong one, you get deposit_link.payment_removed and the link is open again.
Act on paid, and undo what you did if one of these follows.
Send the customer short_url, or url if short_url is null. Send an Idempotency-Key so a retried request returns the same link instead of a second one. See Create deposit link.

​
2. Hear when it’s paid

Register a webhook endpoint for deposit_link.paid and the other deposit events. Each event carries the link as Retrieve deposit link returns it, so you can read status, paid_at and payment straight from it. Money can also arrive outside the link, as a wire, ACH credit, or check. When it’s matched to the link, the link turns paid the same way. payment.attached_by tells you how: null if the customer paid through the link, merchant if someone on your team attached it, or auto_match if Streamlined matched it. payment.amount is what actually arrived, which can differ from what you asked for.
auto_match is an inference from the amount, customer, and currency, and it can be wrong. Before you ship goods or start work on an auto_match payment, confirm it with your team or wait for merchant.

​
3. Apply it to the invoice

Once you’ve issued the invoice, put the deposit against it:
The invoice must be for the same customer, in the same currency, and not voided.
  • paid: the money is applied now. You get 200 with applied: true, and payment.invoice_identifier names the invoice.
  • processing: the deposit is queued. You get 202 with apply_to_invoice_uuid set, and it’s applied when the bank debit settles. Until then the invoice shows it as a payment on its way, so automatic charges don’t take the same money twice.
Applying is safe to retry. To take a queued deposit back off the invoice, call Unqueue deposit from invoice. Moving a deposit that’s already applied is done in the Streamlined app. A deposit larger than the invoice is applied in full, and the rest stays on the invoice as credit, so the invoice shows Has Credit. See Invoice status and aging. Cancel deposit link stops an open link from taking money. The link is kept, with status: canceled, so you can still look it up.