Skip to content
PayplugPayplug Elements

How it works

The whole picture in one diagram — what happens during a split payment, the four things you build, and everything the components handle for you.

Payplug Elements let a customer settle one order with several payment tranches — card now, another method next — until the total is covered. Each tranche is held as an authorization, and nothing is actually charged until the whole order is paid for. A customer never pays for half an order.

Your work comes down to four tasks, and this page shows where each one lands before you write any of them.

A split payment from end to end: what you build, and what happens betweenYour customer places an order on your page. Your server authenticates, creates a payment session, and receives an elements token, which it hands to the page along with the components. The customer then pays the order in one or more tranches: each one is authorized with a processing API, whose verdict comes back out of band. Once the total is covered the capture goes out on its own, your customer sees the confirmation, and a notification tells your server the order is paid. Four arrows carry a dot: they are the four tasks you implement.until the total is coveredyour customer placesthe order1. authenticate2. create the sessionelementsToken3. show the elements,with that tokenyour customer pays a trancheauthorizationthe verdict, out of bandcapture, once the totalis coveredthe order is confirmed4. the notification:the order is paidYour page(your customer)Your serverPayplug Elements APIProcessing APIsThe dots are yours to build — everything else happens on its own.

Your four tasks

Section titled “Your four tasks”
  1. Authenticate. Your server exchanges your credentials for a short-lived access token. One call, and you keep the token until it expires.
  2. Create the session. Still on your server: you declare the order — its total, its currency, the methods you accept — and receive an opaque token for the page.
  3. Show the elements. Your page loads one script, composes the components where you want them, and hands them that token. From there the checkout runs itself.
  4. Handle the notification. When the session ends, we call an address you declared. That is how your own system learns the order is paid.

Tasks 1 and 2 live together on Create a session, task 3 on Show the elements, and task 4 has its own page: webhooks.

What you do not build

Section titled “What you do not build”

Everything between the dots is already handled, and it is the larger half of a checkout:

  • The payment journey: the amount choice, the authorized/remaining progress, the banner after each tranche, the single waiting screen while a verdict is pending, the per-tranche cancel, the way out with its confirmation, and the final screens — confirmed, abandoned, expired.
  • The money rules: each tranche is an authorization, the capture only goes out once the total is covered, a refusal charges nothing and leaves the earlier tranches valid, and abandoning or letting the session expire releases every hold.
  • The waiting: a verdict always arrives out of band, even when the customer never leaves your page. The components show the right screen in the meantime, and it is handled for you.

Sandbox and production

Section titled “Sandbox and production”

There is no separate sandbox surface: the calls you are about to write are the production calls, run with test credentials. What changes between the two is the credentials and the address you call — nothing structural, which is why this documentation only ever shows one way of doing each thing.

Want to see it before writing anything? The playground runs these very components on a live sandbox session, right here in the documentation.