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.