Register Sign in
Docs menu and search API payment flow

API payment flow

Use an API-triggered payment flow when your own system owns the customer journey, but Periode should handle payment and notify you when the purchase is complete.

This guide explains the flow conceptually. Use the Integrations guide, Booking API guide, and the machine-readable GET /llms endpoint for exact endpoint names, request fields, and response shapes.

When to use this flow

Use this flow when:

  • Your own website or application collects the customer details.
  • Your system decides what the customer should buy.
  • Periode should create the payment.
  • The customer should complete payment on a Periode payment URL.
  • Your system should be notified by webhook after payment.
  • You need to connect the Periode payment back to a customer or order in your own system.

For ordinary merchant-managed bookings, memberships, gift cards, or punch passes, use the standard product links instead.

Flow overview

1. Create the product

Create the product in the Backoffice or through the Merchant API.

If your own system collects customer details, avoid requiring the same details again in the Periode product. Keep the Periode product focused on the payment and product rules, and let your own system remain the source for the customer/order context you collect.

2. Configure redirect and webhook URLs

Set the URL where Periode should send the customer after completed payment.

Also configure the webhook URL where Periode should notify your system. The webhook is what lets your system mark the external order or customer record as paid.

3. Store the product ID

Retrieve the product ID from the Backoffice or API and store it in your system.

Your system will use that ID when creating or triggering the payment flow for a customer.

4. Create or trigger the payment

Call the relevant endpoint described in the Integrations guide, Booking API guide, or the machine-readable GET /llms docs.

Include the customer or order reference your system needs to recognize the payment later. If the flow supports merchantCustomerID or another merchant-side reference, use it consistently so the webhook can be matched back to your own customer or order.

5. Redirect the customer

The API response returns a payment URL or equivalent next step. Redirect the customer to that URL so they can complete payment.

Do not mark the order as paid when you create the payment URL. Wait for the successful payment result or webhook.

6. Receive the webhook

When payment completes, Periode sends a webhook to the configured URL.

Your webhook handler should:

  • Verify the request came from Periode.
  • Parse the payload.
  • Match the payment to your local customer or order reference.
  • Mark the order as paid only once.
  • Store the Periode payment/order identifiers for later support and reconciliation.
  • Return a successful HTTP status after processing.

Idempotency and duplicate webhooks

Webhook handlers should be idempotent. The same event may be sent more than once if delivery is retried.

Use a stable Periode payment/order ID, booking ID, subscription ID, or merchant reference to detect duplicates. If your system has already processed the payment, return success without creating a second order or granting access twice.

Customer identity

Decide which system owns customer identity before launch.

If your system owns the customer profile, keep a local customer ID and pass it through the Periode flow when supported. If the customer also needs a Periode account, make sure the email/login method expectations are clear.

Testing

Before launch, test the whole flow:

  • Create or choose a test product.
  • Trigger the payment from your system.
  • Confirm the customer is redirected to Periode.
  • Complete payment.
  • Confirm the customer returns to the redirect URL.
  • Confirm your webhook receives the event.
  • Confirm your system matches the event to the correct customer/order.
  • Confirm duplicate webhook delivery does not create duplicate access.
  • Confirm the payment appears in Periode reports.

For webhook details, see Webhooks. For product fields and API conventions, see Getting started and Integrations guide.