Skip to main content

Introduction

🎯 What does this module do?​

The Payments module lets you manage payment processing and transactions for your e-commerce store. Working with payments and transactions is an important part of any e-commerce project. It integrates with payment gateways like Stripe to handle payment sessions, transaction tracking, and payment status management.

Think of it as your payment management system - you configure payment accounts in OneEntry admin panel (Payments > Accounts), create multiple accounts for different types of payments such as connecting a payment system or adding cash payments, and this module handles payment session creation, status tracking, and transaction management.

📖 Simple Explanation​

Every e-commerce application needs secure payment processing:

  • 💳 Accept Payments - Credit cards, debit cards, digital wallets
  • 🔒 Secure Processing - PCI-compliant payment handling
  • 🔄 Payment Status - Track pending, completed, failed, refunded
  • 💰 Refunds - Process full or partial refunds
  • 📊 Payment History - View all transactions
  • 🔗 Gateway Integration - Stripe, PayPal, custom gateways

The problem with manual payment handling:

Issues:

  • 🔒 Security risk - Storing sensitive card data
  • 📋 PCI compliance - Expensive certification required
  • 💸 No refund tracking - Manual refund management
  • 🔄 No payment history - Hard to track transactions

The Payments solution:

Benefits:

  • 🔒 PCI compliant - Secure tokenized payments
  • 📊 Payment tracking - Complete transaction history
  • 🔄 Automated refunds - Easy refund processing
  • 💸 Multiple gateways - Stripe, PayPal, custom

✨ Key Concepts​

What is a Payment?​

A Payment is a financial transaction record containing:

  • Payment Method - Card, PayPal, bank transfer
  • Amount - Transaction amount and currency
  • Order Reference - Associated order ID
  • Payment Status - Pending, completed, failed, refunded
  • Gateway Details - Stripe transaction ID, PayPal reference
  • Customer Info - Billing details
  • Timestamps - Created, processed, completed dates

Available Account Types​

TypeWhen to UseConfiguration Required
StripeConnect Stripe payment system to your projectStripe account, URLs
CustomAlternative payment systems or cash paymentsCustom configuration

Payment Lifecycle​

1. Create payment account in admin panel
   (Configure Stripe or custom account)
   ↓
2. Customer places order
   (Order created in Orders module)
   ↓
3. Create payment session
   (Payments.createSession(orderId, type))
   ↓
4. Customer redirected to payment URL
   (Stripe checkout or custom payment page)
   ↓
5. Customer completes payment
   (Payment processed by gateway)
   ↓
6. Payment status updated
   (waiting → pending → paid/canceled/expired)
   ↓
7. Webhook notification received
   ↓
8. Order status synchronized
   (Payment status linked to order status)

Payment Statuses​

The system includes four preset payment statuses that indicate the state of the transaction being processed:

StatusMeaningWhen It Occurs
PendingInitial transaction statePayment session just created
PaidSuccessfully completed transactionPayment confirmed by gateway
CanceledTransaction was canceledCustomer canceled payment
ExpiredTransaction validity period endedSession timeout exceeded

Important: In the payment settings, you cannot create or modify statuses. However, you can link these preset payment statuses to order storage statuses to enable automatic synchronization between payment and order systems.

Payment Methods​

MethodDescriptionGateway Support
credit_cardVisa, Mastercard, AmexStripe, PayPal
debit_cardDebit cardsStripe, PayPal
paypalPayPal accountPayPal
bank_transferWire transfer, ACHCustom
apple_payApple Pay walletStripe
google_payGoogle Pay walletStripe
cash_on_deliveryPay on deliveryN/A

Why Use Payments Module?​

BenefitDescription
PCI ComplianceSecure tokenized payment processing
Gateway IntegrationStripe, PayPal built-in
Payment TrackingComplete transaction history
Refund ManagementEasy full/partial refunds
Fraud ProtectionBuilt-in fraud detection
3D SecureSCA authentication support
Multi-CurrencySupport for multiple currencies

📋 What You Need to Know​

Payment Accounts are Created in Admin Panel​

You cannot create payment accounts via the SDK - they're created in the OneEntry admin panel:

OneEntry Admin Panel → Payments → Accounts → Create Account → Fill Form → Click "Add"

Creation Process:

  • Fill out the form with three required fields:
    • Name - Non-unique string identifier
    • Type - Selected from dropdown: "Stripe" or "Custom"
    • Token - Unique string identifier
  • Click "Add" to create the account

Account Management:

  • Editing - Select account, click edit icon, modify name/type/token/Stripe parameters
  • Hiding - Click eye icon to hide accounts from order storage setup selections
  • Deletion - Select account, click delete icon, confirm removal

The SDK is for fetching payment accounts and creating payment sessions, not managing accounts.

Payment Account Types​

Two payment account types are available:

TypeDescription
StripeChoose this type to connect the Stripe payment system
CustomFor alternative payment systems or cash payments

Stripe-specific configuration:

  • Success URL - Redirect URL after successful payment
  • Cancel URL - Redirect URL if payment is canceled
  • Session lifetime - Session timeout in minutes

Payment Status Synchronization​

Payment statuses can be linked to order storage statuses:

OneEntry Admin Panel → Payments → Statuses → Select Order Storage → Map Statuses → Save

Status mapping workflow:

  1. Navigate to Statuses subsection within Payments
  2. Select the desired order storage system
  3. Map each preset payment status to corresponding order storage status value
  4. Verify all mappings are accurate
  5. Click Save to apply changes

This enables automatic status updates in order records when payment statuses change.

Never Store Raw Card Data​

CRITICAL: Never store credit card numbers, CVV, or full expiry dates.

Why?

  • PCI DSS compliance requires secure handling
  • Storing card data exposes you to liability
  • OneEntry never stores raw card details

💡 Important Notes​

Payment Accounts are Created in Admin Panel​

Remember: The SDK is for fetching payment accounts and creating sessions, not creating accounts.

To create/edit payment accounts: Use OneEntry Admin Panel.

Payment Account Management​

Creating accounts in admin panel:

  1. Navigate to Payments > Accounts
  2. Fill out the form with Name, Type, and Token
  3. For Stripe accounts, configure Success URL, Cancel URL, and Session Lifetime
  4. Click "Add" to create

Managing accounts:

  • Edit - Modify name, type, token, or Stripe-specific parameters
  • Hide - Click eye icon to hide from order storage setup (doesn't delete)
  • Delete - Remove unused accounts entirely

Important: Only unused accounts can be deleted.

Payment Status Configuration​

Important: You cannot create or modify payment statuses in the admin panel. The system has four preset statuses: Pending, Paid, Canceled, Expired.

Status synchronization workflow:

  1. Navigate to Payments > Statuses
  2. Select order storage system
  3. Map preset payment statuses to order storage statuses
  4. Click Save to apply changes

This enables automatic order status updates when payment statuses change.

Session Types​

Two session types are available:

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

Security First​

🔒 Critical security rules:

  • Never store raw card data - Use tokenization
  • Use HTTPS only - All payment pages must be SSL
  • Validate on server - Never trust client-side data
  • Log transactions - Keep audit trail
  • Handle PII carefully - Protect customer data

PCI Compliance​

✅ OneEntry handles PCI compliance for you:

  • Tokenized payment processing
  • Secure gateway integration
  • No raw card data storage
  • Encrypted transmission

Your responsibility:

  • Use HTTPS on payment pages
  • Don't log sensitive data
  • Follow security best practices

Payment Status Polling​

For async payments, poll for status updates:

Refund Limitations​

Important refund rules:

  • Can only refund completed payments
  • Partial refunds must not exceed original amount
  • Some gateways have time limits (e.g., 180 days)
  • Refunds are asynchronous (may take days)

📊 Quick Reference Table​

MethodDescriptionUse Case
getAccounts()Get all payment accountsList available payment methods
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() to generate payment links that redirect 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 methods?​

Yes! Create multiple payment accounts (Stripe, custom, cash on delivery) in the admin panel. Each order can use a different payment account based on customer selection.

In the admin panel, go to Payments > Statuses, select your order storage, and map the four preset payment statuses (Pending, Paid, Canceled, Expired) to corresponding order statuses. This enables automatic synchronization.

What happens if a payment session expires?​

Payment sessions have a configurable lifetime (set in account settings). If a customer doesn't complete payment within this time, the session status changes to "Expired" and they'll need to create a new payment session.

🎓 Best Practices​

  • Use tokenization - Always tokenize cards with Stripe.js
  • Validate amounts - Check totals on server, not just client
  • Handle errors gracefully - Clear error messages for users
  • Log transactions - Keep audit trail of all payments
  • Use webhooks - Listen for payment status updates
  • Test with test keys - Use Stripe test mode before production
  • Handle 3D Secure - Implement SCA authentication flow
  • Store transaction IDs - Keep gateway references for disputes

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

Definition of the Payments module​

The Payments module manages payment processing and transactions. It provides tools for working with payment accounts, creating payment sessions, and tracking payment statuses.


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

🔗 Related Documentation​