Skip to main content

Introduction

Create payment sessions and track transactions through the gateways configured in your project.

More information about payments in the OneEntry admin panel: https://doc.oneentry.cloud/docs/category/payments

🎯 What does this module do?​

The Payments module lets you create payment sessions and track transactions for your store. You configure payment accounts in the admin panel (Payments > Accounts) — Stripe or custom — and this module creates a payment session for an order, returns the gateway checkout link, and lets you read session history and status.

The SDK fetches payment accounts and creates payment sessions; accounts and statuses are configured in the admin panel.

🚀 Quickstart​

Initialize the module from defineOneEntry:


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Create a payment session for an order and redirect the customer to the gateway (auth required):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

✨ Key Concepts​

What is a Payment session?​

A Payment session (ISessionEntity) is a record containing:

  • type — 'session' or 'intent'
  • status — free-form payment status string (e.g. "waiting", "completed")
  • paymentAccountId — the configured account used
  • orderId — the associated order
  • paymentUrl — gateway checkout link (or null)
  • createdDate / updatedDate — timestamps

Session types​

TypeDescription
sessionCreates a Stripe Checkout page with a redirect payment link
intentCreates a payment intent for direct/custom payment processing

Account types​

TypeWhen to UseConfiguration Required
StripeConnect the Stripe payment systemStripe account, URLs
CustomAlternative payment systems or cash paymentsCustom configuration

Payment statuses​

A session's status is a free-form string set from the gateway result, not a fixed enum. Common values:

StatusMeaning
waitingSession created, awaiting payment
completedPayment confirmed by the gateway

You cannot create or modify payment statuses in the admin panel. You can, however, map payment statuses to order storage statuses so the order status updates automatically when a payment status changes.

Payment lifecycle​

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

📋 What You Need to Know​

Payment accounts are created in the admin panel​

You cannot create payment accounts via the SDK — create and edit them in the OneEntry admin panel (Payments > Accounts), providing Name, Type (Stripe or Custom), and Token. For Stripe accounts you also configure Success URL, Cancel URL, and Session lifetime. The SDK is for fetching accounts and creating sessions.

Status synchronization​

Payment statuses are mapped to order storage statuses in the admin panel (Payments > Statuses → select order storage → map statuses → save). This enables automatic order status updates when a payment status changes.

Never store raw card data​

Never store credit card numbers, CVV, or full expiry dates. Payment is handled by the gateway (Stripe), which keeps you out of scope for storing card data; OneEntry never stores raw card details.

Refunds live in the Orders module​

The Payments module has no refund methods. Refunds are handled by the Orders module via createRefundRequest(), cancelRefundRequest(), and getRefunds().

📊 Quick Reference Table​

MethodDescriptionUse Case
getAccounts() 🔐Get all payment accountsList configured payment accounts
getAccountById() 🔐Get payment account by IDFetch specific account details
createSession() 🔐Create payment sessionGenerate payment link for order
getSessions() 🔐Get all payment sessions (paginated)View payment session history
getSessionById() 🔐Get payment session by IDCheck specific session status
getSessionByOrderId() 🔐Get payment session by order IDFind payment for specific order

🔐 = Requires authorization

❓ Common Questions (FAQ)​

How do I set up Stripe payments?​

Create a payment account in the admin panel with type "Stripe", then configure Success URL, Cancel URL, and Session lifetime. Use createSession() with type "session" to generate a link that redirects customers to Stripe Checkout.

What's the difference between session and intent payment types?​

A session creates a Stripe Checkout page with a redirect URL, ideal for hosted payment pages. An intent creates a payment intent for custom payment form integration directly in your app.

Can I support multiple payment accounts?​

Yes. Create multiple payment accounts (Stripe or custom) in the admin panel. Each order can use a different account via its paymentAccountIdentifier.

In the admin panel, go to Payments > Statuses, select your order storage, and map payment statuses to order statuses. This enables automatic synchronization.

How do I issue a refund?​

Refunds are not part of the Payments module. Use the Orders module: createRefundRequest() to request a refund, cancelRefundRequest() to cancel a request, and getRefunds() to list them.

🎓 Best Practices​

  • Authenticate first — every Payments method requires an authorized user (see AuthProvider).
  • Redirect to paymentUrl after creating a session, and handle the gateway's return URLs in your app.
  • Read status from the session, not the client — check the session status (or getSessionByOrderId()) to confirm payment.
  • Map payment statuses to order statuses so order state stays in sync automatically.
  • Test with Stripe test keys before going to production.

🔗 Related Documentation​