Core concepts

jetpay is built around a small set of foundational objects understanding how these objects relate to one another will make your integration feel more intuitive at a high level, jetpay manages people of business (contacts) how they pay or get paid (payment methods) the movement of funds (transactions) state changes and notifications (events and webhooks) everything in the api builds on these primitives contact a contact represents an individual or business in your system in most integrations, a contact maps directly to a user, customer, vendor, or merchant in your own database jetpay does not dictate how you model your users, it provides a secure payment identity you can associate them with once created, a contact can store one or more payment methods initiate payments receive funds you create a contact once and reuse it across transactions this allows payment methods and transaction history to remain attached to a stable entity payment method a payment method represents how funds move to or from a contact jetpay supports tokenized credit cards and bank accounts (eft/ach) sensitive payment data is never stored in your system unless you explicitly choose to save it we recommend letting us store this information on your behalf, which keeps your integration secure and pci scope minimal a payment method may be attached to a contact for reuse used once in a single use flow collected through a hosted experience (payment link or iframe) transaction a transaction represents the movement of funds transactions are directional they either collect funds (customer > platform or merchant), or disburse funds (platform > vendor, contractor, or customer) every transaction moves through a lifecycle for example graph lr requested >paid paid >completed the exact timing and transitions depend on payment method type and account configuration a transaction does not immediately imply settled funds settlement time varies between card and eft/ach payments for precise funding timelines, consult your jetpay representative events and webhooks transactions are asynchronous by nature jetpay communicates state changes through events you can retreive transaction status by polling the api or you can subscribe to webhook events (recommended) in a typical webhook enabled integration graph lr; a\[platform initiates transaction] >b\[jetpay processes payment]; b >c\[jetpay sends webhook event]; c >d\[platform updates internal state]; webhooks allow your system to react automatically to payment success, failure, or settlement without continuously polling for updates how the objects work together most jetpay integrations follow this conceptual flow graph lr; a\[create contact] >b\[attach or collect payment method]; b >c\[initiate transaction]; c >d\[receive webhook event]; everything else, like payment links, iframes, saved methods, and payouts, builds on this foundation once these core concepts are clear, the individual integration guides become straightforward combinations of these same primitives