Payment links and hosted pages
Choose the link that matches your customer's task. Create links on your server; never put an API key in a link or browser bundle.
| Task | API | What to send the customer |
|---|---|---|
| Reusable payment button/link | POST /api/v1/hosted/button | The hosted URL returned for the button |
| One checkout/order | POST /api/v1/checkout/sessions | The returned checkoutUrl (/c/{sessionId}) |
| Request payment from an existing contact | POST /api/v1/customer-contacts/{contactId}/payment-request | The returned payment-request link or configured delivery |
| Save or replace a card, without a payment | POST /api/v1/setup-intents/issue-link | The returned hostedUrl or email delivery |
Reusable payment link
A hosted button request identifies merchantId, locationId, currency, successUrl and cancelUrl. Configure the price/line items and openAmount behavior using the reference. displayName, description and expiresAt control presentation and expiry. A reusable link can lead to multiple separate payments; do not treat the button ID as one transaction.
Single checkout
Create a checkout session with the order amount or line items, currency and approved location. Persist its Idempotency-Key and exact request before sending. After a lost response, recover the session with GET /api/v1/checkout/sessions/by-key using the original key and location rather than create a second payable session. Redirect to the returned checkoutUrl, keeping all authorization parameters intact.
A success redirect alone is not proof of payment. Read the session or verify a webhook before fulfilling an order. ACH needs settlement-aware handling even after checkout acceptance.
Card-update links
Use deliveryMode: "EMAIL" to ask Peak to send a hosted setup link. Bind customerId and the authorized location; include replacementPaymentMethodId when replacing an existing method. Inspect sent and deliveryUnconfirmed rather than assuming the email arrived. deliveryMode: "IFRAME" returns a context suitable for secure card fields.
A card-update link does not charge the customer or switch existing subscriptions to the resulting card. A successful bound replacement changes the customer's saved method/default and can disable the old active card. For an existing subscription with an open dunning case, use the subscription-bound hosted recovery flow instead. See retries and card updates before issuing a replacement.