Skip to main content
Seamless Payment lets a Consumer pay for an order without leaving the environment they already trust. Paylead initiates the payment; your Program executes it with its own payment method and returns the result. Fewer checkout steps means a higher completion rate. This page is for the product and engineering teams of a Program integrating as the payment delegation provider. It covers the Consumer experience, what you must build, and how the flow works both in the Paylead WebApp and via API integration.
In progress. Seamless Payment is being implemented on API version 2.0.0. The contract below may still be adjusted through the API. Contact your Paylead operations manager for more details.

​
Roles

  • Paylead owns the order, generates the payment_id, initiates the payment when the purchase is confirmed, completes the order on success, and handles any refunds (partial or total).
  • You (the Program) receive the payment request on your endpoints, execute it with your payment method, return the result, and reconcile against your banking system.
Identifiers.
  • payment_id: a UUID generated by Paylead, matching the internal order (the generic term that covers both a WebApp purchase and a one-click API purchase). It is your idempotency key; echo it on every callback and, critically, in the wire reference (see Reconciliation).
  • consumer_id: Paylead’s identifier for the user.
  • account_id: the account external_id provided through the PM hub integration.

​
Two purchase modes, one payment contract

The delegated payment contract below is identical in both cases:
  • WebApp: the Consumer completes a purchase inside the Paylead WebApp opened from your app.
  • API integration (coming): your app triggers a purchase through the Paylead API (one-click), without the WebApp.

​
Consumer experience (WebApp)

  1. The Consumer opens the WebApp from your app.
  2. The Consumer selects what to buy and an amount, then confirms.
  3. Paylead sends the payment request to your endpoint.
  4. You authorize or reject the payment, synchronously or asynchronously.
  5. On success, Paylead completes the order and redirects the Consumer to it.
  6. On failure, Paylead shows an error and lets the Consumer retry.

​
Authentication

Both directions must be authenticated before go-live.
  • Paylead to your endpoints: Paylead authenticates its requests with the mechanism agreed for your Program (e.g. mTLS or a signed token). Reject unauthenticated calls.
  • You to Paylead callbacks: authenticate with the credentials Paylead issues for your Program. A payment_id alone must never be enough to trigger order completion.

​
Delegated payment flow

A two-step process, plus an optional status endpoint.

​
Step 1: Payment authorization (required)

When the purchase is confirmed, Paylead sends a POST to your authorization endpoint (URL configured per Program):
amount is in minor units (1000 = 10.00). Respond with one of: failure_reason values (on 400 and in Step 2 failures):
  • INSUFFICIENT_FUNDS
  • PAYMENT_LIMIT_EXCEEDED
  • TECHNICAL_ISSUE
  • USER_NOT_FOUND

​
Step 2: Payment result callback (asynchronous only)

If Step 1 returned 202, notify Paylead once validation completes. Paylead provides the callback base URL for your Program. payment_status is a path segment: success or failure. Success, empty JSON body:
Failure:
Resolve async payments in time. With no callback within the finalization window, Paylead treats the payment as failed (TECHNICAL_ISSUE) and releases the order.
Idempotency. Paylead accepts one final result per payment_id; later callbacks on an already-resolved payment are rejected, and the callback is validated against the owning consumer_id.

​
Step 3: Status check (optional)

Expose an endpoint so Paylead can check a payment’s outcome, for incident recovery and audit (URL to be confirmed per Program):
status is success, failure, or pending. failure_reason is null unless status is failure.

​
Refunds

An order may be refunded, partially or in full. Paylead handles refunds.

​
Reconciliation

Paylead reconciles each order with the payin it receives.
You MUST include the payment_id in the wire reference of every bank transfer used to fund a purchase. It is the only key linking the order, the payment execution, the payin received, and any later refund. Without it, reconciliation and refunds are impossible.

​
Error handling shown to the Consumer

On failure at Step 1 or Step 2, the WebApp shows:
The payment could not be completed. No charge was made. You may try again with a different amount.

​
Sequence diagram

​
Your responsibilities

You must:
  • Authenticate Paylead’s requests, and your own callbacks to Paylead.
  • Expose the Step 1 authorization endpoint; respond 201/400 synchronously, or 202 then call Step 2.
  • Resolve every 202 before the finalization window closes.
  • Include payment_id in the wire reference of every funding transfer.
  • Return documented, uppercase failure_reason values.
You must not:
  • Approve or resolve the same payment_id more than once.
  • Leave asynchronous transactions unresolved.

​
What’s next

WebApp authentication

The SSO flow the Consumer goes through before reaching the purchase.

Manage Consumers

How you create Consumers and get the consumer_id and account_id used in the payment request.