Payment Links
A payment link lets the guest pay for an order you sent us unpaid, on a Stream-hosted page that charges the card through the merchant's own POS processor. You do not need to know which POS the location runs.
Payment links are not enabled by default and only work for locations whose POS supports them. Contact Stream before you start using them.
Flow
- Send the order with
unpaid: true. See Payment State. - Request a payment link for the order and give the URL to the guest.
- The guest opens the link and pays. The page takes payment once the order has reached the merchant's POS (after
location.order.accept); until then it tells the guest the order is not ready to pay. - We send you a
location.order.paidevent.
Requesting a Link
Authenticate with a partner API token, then send your location ID and order ID — the same IDs you sent on the order.
curl --location --request POST 'https://<STREAM_API_URL>/payment-links' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"location_id": "store_123",
"order_id": "order_456"
}'
{
"order_id": "order_456",
"payment_url": "https://<PAYMENT_PAGE_URL>/..."
}
Requesting a link again for the same order returns the same URL. Treat the URL as opaque.
A link has no fixed lifetime. It can be paid while the order is open and unpaid. Once the order is paid, completed, canceled or failed, the page shows that end state and takes no charge.
| Status | Reason |
|---|---|
404 | The order was not found for your platform at that location. |
409 | The order is completed, canceled or failed; it was not sent with unpaid: true; the guest has already paid (Order is already paid); or the location is connected to more than one Stream integration. |
422 | The location's POS does not support payment links. |
503 | Payment links are not enabled. |
Payment Event
When the guest pays, we notify you via the New Webhook Event (Stream -> DSP) endpoint with an event type of location.order.paid. It is sent once per order.
We do not retry this event. If your endpoint does not accept it, the event is lost. To check an order you have not heard back on, request its payment link again: a 409 with Order is already paid means the guest has paid, even if the order has since completed.
{
"type": "location.order.paid",
"location_id": "store_123",
"order_id": "order_456",
"amount": 1250,
"payment_status": "paid"
}
amount— the amount the guest paid, in minor currency units (cents).payment_status—paidwhen the payment was captured, orauthorizedwhen the card was authorized and is captured when the POS closes the order.
A declined card does not send an event; the guest can try another card on the same link. After 5 declined cards, the link stops taking cards until 15 minutes pass without a decline.