Payins Overview
How Payment Labs collects money from buyers: the objects involved, the three ways to present a checkout, and the order of calls every payin integration follows.
Read this page first. It names the objects every payin guide uses, helps you choose how the buyer pays, and shows the order of calls that every integration follows.
Before you start
- You need a Payment Labs account with payins enabled and an API credential with a payin role. Merchants use the same login as payors: Create Access Token returns one token for every Payment Labs API. See Environments and Authentication for base URLs, tokens and roles.
- Call Get Merchant to see which currencies and payment method types your account accepts, and whether settlement reporting is enabled.
- Every example in the payin guides uses the sandbox base URL,
https://api-sandbox.paymentlabs.io.
Objects
| Object | ID prefix | What it is |
|---|---|---|
| Merchant | C- | Your account. It is the merchantId on every checkout. |
| Buyer | U- | The person who pays you. Payment Labs keeps one buyer per merchant and email address, and creates it the first time you send that email in a checkout or plan offer. Read its ID from buyerId on the checkout, or find it with Search Buyers. |
| Checkout | S- | One request for money: an amount, a currency, a buyer and an expiry date. The buyer pays it once. |
| Checkout transaction | ST- | One attempt to charge a checkout. A checkout that failed and was charged again has several. |
| Checkout instrument | SI- | A card, bank account or wallet token the buyer used or saved. |
| Refund | RF- | Money returned to the buyer from a succeeded checkout transaction. |
| Subscription plan, plan offer, subscription | RD-, RO-, R- | Recurring billing. See Subscriptions. |
| Subscription payment | RP- | One billing cycle of a subscription. |
| Terminal | TL- | A card reader registered to your account. See POS Terminals. |
| Settlement | E- | The money paid out to you for one settlement date. See Settlements and Reconciliation. |
A charge is a sale. There is no separate authorization and capture, and you cannot void or cancel a charge. To return money, create a refund.
How a payin works
Every one-off payment follows the same three steps. Subscriptions follow the same pattern with a plan offer in place of the checkout.
- Your server creates the checkout. Call Create Checkout with the amount, the currency and the buyer's email. Creating it on your server keeps the amount out of the buyer's reach.
- The buyer completes it in the browser. Send them to the hosted page, embed it in an iframe, or render it with the Payin SDK. Payment Labs collects the card or bank details, runs 3D Secure when the issuer asks for it, and charges the instrument.
- Your server confirms the result. Wait for the
checkout-status-changedwebhook, or call Get Checkout, and fulfil the order only when the status isPAID.
Browser events, iframe messages and redirects tell you what the buyer saw. They are not proof of payment: a buyer can close the tab before they fire, and anyone can send them to your page. Always confirm
PAIDfrom your server before you ship goods or grant access.
You can also charge a buyer without them being present, using an instrument they saved earlier, or take a payment in person by sending the checkout to a card reader in your store. See Saved Cards and Merchant-Initiated Charges and POS Terminals.
Choose how the buyer pays
| Option | What you build | Use it when |
|---|---|---|
Hosted link (links.checkout) | Nothing. Send the URL by email, chat or a button. | You want the fastest integration, or you invoice buyers who pay later. |
Iframe (links.embeddable) | One <iframe> and a message listener. | You want the payment form inside your page without adding a JavaScript library. |
Payin SDK (@paymentlabs/paymentlabs-js) | A container element and a few event handlers. | You want full control of the page around the form, typed events, theming, and your own Pay button. |
All three use the same checkout, collect the same payment methods, and end in the same statuses and webhooks. The hosted link and the iframe are covered in Hosted Checkout Page and Iframe. The SDK is covered in Payin SDK.
Statuses at a glance
A checkout starts PENDING, moves to PROCESSING while a charge is in flight, and ends PAID, FAILED, EXPIRED or UNKNOWN. The full table, what each failure reason means, and when a checkout can be charged again are on Checkout Statuses and Failure Reasons.
Webhooks
Register these events to learn about changes without polling. Registration and signature checks are explained in Webhooks.
| Event | Fires when |
|---|---|
checkout-status-changed | A checkout you created changes status. Checkouts created by a subscription do not send it. |
refund-status-changed | A refund changes status. |
subscription-status-changed | A subscription changes status. |
subscription-payment-status-changed | A subscription billing cycle changes status. |
Each delivery carries the object as it is when the event is sent, not the change itself. Treat it as the current state, and expect the same event more than once.
Permissions
Permission names are the ones on the Roles screen of your dashboard. Reading needs Merchant Read. Creating and charging checkouts needs Merchant Write, refunds need Merchant Approver, and managing plans, offers and subscription cancellations needs Merchant User Config (the Administrator role). A call without the permission returns 403 FORBIDDEN_INSUFFICIENT_TAGS. The full table is in Permissions. Registering webhooks needs the payout Administrator role, even for payin events; see Webhooks.
Next steps
- Hosted Checkout Page and Iframe with the hosted link or an iframe.
- Payin SDK to render the form yourself.
- Credit Card Payin Test Values to test approvals and declines in sandbox.
Updated about 24 hours ago