Concepts
Get to know the core concepts of the Ivy API.
Core Concepts
Get familiar with the main concepts that power Ivy’s payment infrastructure.
Checkout Session
A Checkout Session represents your user’s interaction while making a one-time payment through Checkout or Payment Links. You can configure the Session with different modes based on your use case.
Key aspects of Checkout Sessions:
- Each payment attempt should use a new Session
- Configure guest mode when users don’t need an email
- Session status changes to
closedafter successful authorization - Creates an associated Order with the
checkoutSessionIdreference
Order
An Order represents a one-time user payment in the Ivy system. Ivy creates exactly one Order for each user deposit or payment attempt.
Key characteristics:
- Tracks the current status of payment attempts
- Progresses through multiple statuses during its lifecycle
- Status changes reflect user actions during payment/deposit flow
Webhook Subscription
Webhooks provide real-time updates about your Ivy merchant account. By creating a webhook subscription, your integration can automatically react to events.
Configuration options:
- Register webhook endpoints to receive events
- Configure a single endpoint for multiple event types
- Set up dedicated endpoints for specific events
Webhooks are essential for maintaining data consistency between your system and Ivy. We recommend implementing webhook handling for all critical payment flows.
Refund
A Refund reverses a user’s payment. The money is sent back directly to the user’s bank account as quickly as possible.
Key features:
- Uses instant bank rails for immediate settlement
- Sends funds directly to user’s bank account
- Supports full and partial refunds
Ensure you have sufficient balance in your Ivy account before initiating refunds.
Mandate
A Mandate represents an authorization granted by a customer to a merchant. This authorization permits the merchant to initiate direct debits from the customer’s bank account.
Benefits:
- Enables recurring charges without additional authorization
- Streamlines payment collection for subscriptions
- Provides reliable payment mechanism for regular billing
Mandates are ideal for subscription-based businesses or services requiring regular payments.
Payout Report
Payout Reports help you reconcile all incoming and outgoing payments from your bank account.
Access and content:
- Available through API or Ivy Dashboard
- Shows associated Orders and Refunds
- Includes amounts and dates for each payout
- Processes payouts from balance regularly
Regular review of Payout Reports helps maintain accurate financial records and timely reconciliation of transactions.