Skip to main content

Payments

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 (opens in a new tab)

The Payments module creates a payment session for an order, returns the gateway checkout link, and lets you read session history and status.

The SDK reads payment accounts and creates payment sessions. Accounts and statuses are configured in the admin panel (Payments > Accounts), and you can't create payment accounts through the SDK. Reading payment accounts doesn't require a signed-in user. getSessions() requires an authenticated user (see AuthProvider). Access to the other methods also depends on the module permissions of the caller's user group.

Quickstart​

Initialize the module from defineOneEntry:


const {  } = defineOneEntry(
  , {
    
  }
);

Create a payment session for an order and redirect the customer to the gateway (the caller's user group needs permission to create payment sessions):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");
if ('statusCode' in session) throw new Error(session.message);

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

// Hosted checkout (Stripe) returns a link; custom accounts return null.
if (session.paymentUrl) {
  window.location.href = session.paymentUrl;
}

After creating a session, redirect the customer to paymentUrl and handle the gateway's return URLs in your app.

Payment session​

A payment session (ISessionEntity) contains:

  • type: 'session' or 'intent'
  • status: the payment status: waiting, completed, canceled or expired
  • 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

Use session for a hosted payment page: it creates a Stripe Checkout page with a redirect URL. Use intent to integrate a custom payment form directly in your app.

Payment statuses​

A session's status is one of four values:

StatusMeaning
waitingSession created, awaiting payment
completedPayment confirmed by the gateway
canceledSession canceled by the gateway, or automatically when the order is changed or a new payment session is created for it
expiredSession lifetime ran out at the gateway

To confirm a payment, read the session status (or call getSessionByOrderId()) rather than trusting the client.

You can't create or modify payment statuses in the admin panel. You can map them to order storage statuses, though, so the order status updates automatically when the payment status changes: go to Payments > Statuses, select the order storage, map the statuses and save.

Payment lifecycle​

1. Configure a payment account in the admin panel (Stripe, YooKassa, Midtrans, Xendit 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

Payment accounts​

An account's type field reports which payment provider backs it:

typeWhen to UseConfiguration Required
stripeConnect the Stripe payment systemStripe account, URLs
yookassaConnect YooKassaShop id, secret key, URLs
midtransConnect MidtransProvider credentials, URLs
xenditConnect XenditProvider credentials, URLs
customAlternative payment systems or cash paymentsCustom configuration

Provider-specific connection parameters are in the account's settings object; see getAccountById().

Create and edit accounts in the admin panel (Payments > Accounts) with a Name, Type (one of the providers above) and Token. For Stripe accounts, also set the Success URL, Cancel URL and Session lifetime, then call createSession() with type "session" to send customers to Stripe Checkout. Test with Stripe test keys before going to production.

You can create several payment accounts. Each order picks one through its paymentAccountIdentifier.

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​

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

Methods​

MethodDescriptionUse Case
getAccounts()Get all payment accountsList configured payment accounts
getAccountById()Get a payment account by IDFetch specific account details
createSession()Create a payment sessionGenerate a payment link for an order
getSessions() 🔐Get all payment sessions (paginated)View payment session history
getSessionById()Get a payment session by IDCheck a specific session's status
getSessionByOrderId()Get a payment session by order IDFind the payment for an order
getPaymentStagesByOrderId()Get the payment stages of an orderTrack partial payments

🔐 = Requires authorization