Processing transactions
Our payment processing guide covering checkout sessions and payment links with code examples.
lomi. offers two primary ways to process transactions and accept payments via its API: Checkout sessions and Payment links.
- Checkout sessions: Ideal for single-use transactions where you dynamically generate a secure, hosted payment page for a specific customer order. Checkout Sessions expire after 60 minutes by default.
- Payment links: Best for creating reusable links tied to specific products, subscription plans, or for collecting instant, fixed-amount payments. These links can be shared easily and can be configured to expire at a specific date.
This section guides you through the basics of both methods. For detailed API specifications, please refer to the API Reference section.
Creating a checkout session
To initiate a single payment for a dynamic product or service (like a specific shopping cart), create a Checkout Session. This generates a time-sensitive, secure, hosted payment page pre-filled with the details you provide.
import { LomiSDK } from '@lomi./sdk';
const lomi = new LomiSDK({
apiKey: process.env.LOMI_SECRET_KEY!,
environment: 'live',
});
async function createCheckout() {
const session = await lomi.checkoutSessions.create({
amount: 10000, // 10,000 F CFA
currency_code: 'XOF',
success_url: 'https://your-store.com/success',
cancel_url: 'https://your-store.com/cancel',
title: 'Your Order - #ORD-12345',
description: 'Payment for items in cart',
customer_email: 'customer@email.com',
metadata: {
cart_id: 'cart_abc123',
internal_user_id: 'user_xyz789',
},
});
console.log('Checkout URL:', session.checkout_url);
}import os
from lomi import LomiClient, LomiError
# Initialize client
client = LomiClient(
api_key=os.environ["LOMI_SECRET_KEY"],
environment="test"
)
try:
session = client.checkout_sessions.create({
"amount": 10000, # 10,000 F CFA
"currency_code": "XOF",
"success_url": "https://your-store.com/success",
"cancel_url": "https://your-store.com/cancel",
"title": "Your Order - #ORD-12345",
"description": "Payment for items in cart",
"customer_email": "customer@email.com",
"metadata": {
"cart_id": "cart_abc123",
"internal_user_id": "user_xyz789"
}
})
print(f"Checkout URL: {session['checkout_url']}")
except LomiError as e:
print(f"Error: {e}")sessionData := lomi.CheckoutSessionsCreate{
Amount: lomi.PtrInt32(10000),
CurrencyCode: lomi.PtrString("XOF"),
SuccessUrl: lomi.PtrString("https://your-store.com/success"),
CancelUrl: lomi.PtrString("https://your-store.com/cancel"),
Title: lomi.PtrString("Your Order - #ORD-12345"),
Description: lomi.PtrString("Payment for items in cart"),
CustomerEmail: lomi.PtrString("customer@email.com"),
Metadata: &map[string]interface{}{
"cart_id": "cart_abc123",
},
}
session, \_, err := client.CheckoutSessionsAPI.CreateCheckoutSession(auth).
CheckoutSessionsCreate(sessionData).
Execute()
if err != nil {
// Handle error
return
}
fmt.Printf("Checkout URL: %s\n", \*session.CheckoutUrl)use Lomi\Api\CheckoutSessionsApi;
use Lomi\Model\CheckoutSessionsCreate;
$checkoutApi = new CheckoutSessionsApi(null, $config);
$session = $checkoutApi->createCheckoutSession(
new CheckoutSessionsCreate([
'amount' => 10000,
'currency_code' => 'XOF',
'success_url' => 'https://your-store.com/success',
'cancel_url' => 'https://your-store.com/cancel',
'title' => 'Your Order - #ORD-12345',
'description' => 'Payment for items in cart',
'customer_email' => 'customer@email.com',
'metadata' => [
'cart_id' => 'cart_abc123'
]
])
);
header('Location: ' . $session->getCheckoutUrl());After creating the session, redirect your customer to the checkout_url provided in the response object. lomi. handles the payment process securely on that page.
Why provide optional customer details?
- Convenience: Pre-fills fields to save your customer time.
- Optionality: If omitted, the customer will simply enter them during checkout.
Creating a payment link
Payment Links are ideal for reusable links tied to a specific product or service.
const paymentLink = await lomi.paymentLinks.create({
link_type: 'product',
product_id: 'prod_xxxxxxxxxxxxxxxxxxxx',
description: 'Special offer',
allow_coupon_code: true,
success_url: 'https://your-store.com/success',
metadata: { campaign: 'q4_special_offer' },
});
console.log('Payment Link URL:', paymentLink.url);# Initialize client as shown above
link = client.payment_links.create({
"link_type": "product",
"product_id": "prod_xxxxxxxxxxxxxxxxxxxx",
"description": "Special offer",
"allow_coupon_code": True,
"success_url": "https://your-store.com/success",
"metadata": {"campaign": "q4_special_offer"}
})
print(f"Payment Link URL: {link['url']}")linkData := lomi.PaymentLinksCreate{
LinkType: lomi.PtrString("product"),
ProductId: lomi.PtrString("prod_xxxxxxxxxxxxxxxxxxxx"),
Description: lomi.PtrString("Special offer"),
AllowCouponCode: lomi.PtrBool(true),
SuccessUrl: lomi.PtrString("https://your-store.com/success"),
}
link, \_, err := client.PaymentLinksAPI.CreatePaymentLink(auth).
PaymentLinksCreate(linkData).
Execute()
fmt.Printf("Payment Link URL: %s\n", \*link.Url)$link = $linksApi->createPaymentLink(
new PaymentLinksCreate([
'link_type' => 'product',
'product_id' => 'prod_xxxxxxxxxxxxxxxxxxxx',
'description' => 'Special offer',
'allow_coupon_code' => true,
'success_url' => 'https://your-store.com/success'
])
);
echo 'Share this: ' . $link->getUrl();Once created, you can share the URL via email, social media, or embed it on your website.
Important Note on Fees: Checkout Sessions do not automatically apply pre-configured organization fees, as the amount you specify is the final amount charged. Product-based Payment Links, however, will respect any fee configurations tied to the product/organization.
Setting up webhooks
Webhooks allow your application to receive real-time notifications about events happening within your lomi. account, such as successful payments, new subscriptions, or failed transactions.
Advanced guides
Deep dive into error handling, webhooks, security best practices, testing strategies, and CI/CD integration for production-ready payments.