Skip to main content
Every Ionic payment follows one lifecycle, whether the buyer pays on a hosted page, in Ionic Blocks, or at a terminal. Learn it once and every product works the same way.

​
The lifecycle of a payment

Every payment moves through the same five stages.
1

Create

Your server creates the payment and sets the amount: a checkout session for a hosted page, or a PaymentIntent for Ionic Blocks and terminals.
2

Collect the card

The buyer enters a card on Ionic’s hosted page, in the secure inputs of Ionic Blocks, or on a terminal. Card numbers stay with Ionic, and your server works with IDs such as pi_… and pm_…. Ionic Blocks uses a publishable key and the intent’s client secret, which authorizes that one intent.
3

Authorize

Ionic sends the payment to the card issuer for approval, and records each attempt as a Charge. A decline records a decline code on the Charge, such as insufficient_funds, and returns the PaymentIntent to requires_payment_method so the buyer can try another card. See Decline codes.
4

Capture

With automatic capture, an approved payment completes at once and the PaymentIntent becomes succeeded. With manual capture, it waits in requires_capture until you capture the funds or cancel to release the hold. Terminal payments always capture automatically.
5

Notify

Ionic sends signed events, such as checkout.session.completed and payment_intent.succeeded, to your webhook endpoint. Fulfill the order from a verified event; the browser redirect only updates the buyer’s screen. Events arrive at least once and in no guaranteed order, so deduplicate on the event id. See Webhooks.
After the payment, a Refund returns all or part of a succeeded Charge.

​
How the objects connect

Amounts are integers in the currency’s minor unit, so an amount of 2500 in usd is $25.00.

​
How payment status changes

A PaymentIntent in requires_payment_method or requires_confirmation can also be canceled, which ends it in canceled. A confirmation that returns 502 GATEWAY_ERROR was not processed, so no money moved. The PaymentIntent returns to requires_confirmation, or to requires_payment_method when the card must be entered again. Ionic does not run 3-D Secure today, so PaymentIntents do not enter requires_action. A Refund is pending while it is processed, then succeeded or failed, or uncertain until its outcome is known. A checkout session stays open until the buyer pays and it becomes complete, or until it expires and becomes expired. Its payment_intent_id is set when the session is confirmed. Fulfill a session when its status is complete and its payment_status is paid. See Payment flow for each collection path.

​
Test mode and live mode

Every key belongs to one mode, shown in its prefix: sk_v1_test_ or sk_v1_live_. Test and live data are fully isolated, so customers, webhook endpoints, and object IDs exist in one mode only. Objects and events carry livemode. Test mode moves no money. Test cards return simulated results, and every test account includes simulated terminals. See Test cards.

​
Keys and permissions

Secret keys authenticate requests from your server. Restricted secret keys limit a key to the permissions you select, and publishable keys run in the browser. A key without the permission an operation needs receives 403. See Authentication.

​
Safe retries

Send an Idempotency-Key with each create and money-moving POST. A retry with the same key and body returns the original result instead of repeating the operation, so a timeout or a double click does not charge twice. The same key with a different body or endpoint returns 422. When a request times out, retrieve the object before creating it again. See Reliable API requests and Idempotency.

​
Platforms and connected accounts

With Connect, a platform acts for the businesses that connect to it. The platform authenticates with its own key and names one connected account per request with the Ionic-Account header. That account owns everything the request creates. Each request needs its permission on the platform key, on the account’s connection, and within the Platform Program. Platform webhook events carry an account field that names the connected account. See How Connect works.

​
In-person payments

A location holds terminals, and a terminal payment records each attempt to process a PaymentIntent at the counter. Each terminal reports its setup, connection, and capability states independently. See The Terminal object.

​
What’s next

Payment flow

Choose a collection flow and see what your server does at each step.

Reliable API requests

Retry safely and recover when a response does not arrive.

Test cards

See the card numbers and behaviors that test mode supports.