Create payment link
Create payment link
Overview
Create payment link
Creates a shareable link: product-backed links pull catalog amounts; instant links collect a fixed amount you specify.
When to use this
Use for invoices, social selling, or lightweight payment pages without building full checkout.
See also
List payment links · Checkout sessions
Authentication
Merchant routes require an API key in the X-API-KEY header (see Integration overview). Use a test key against https://sandbox.api.lomi.africa and a live key against https://api.lomi.africa.
Endpoint
POST /payment-links
Base URLs:
https://sandbox.api.lomi.africahttps://api.lomi.africa
Request
Path parameters
No path parameters beyond the URL pattern.
Query parameters
No query parameters.
Request body
JSON request payload.
Schema: object
| Field | Required | Type | Description |
|---|---|---|---|
link_type | Yes | enum ("product", "instant") | - |
title | Yes | string | - |
currency_code | Yes | enum ("XOF", "USD", "EUR") | - |
description | No | string | - |
amount | No | number | - |
product_id | No | string | - |
price_id | No | string | - |
allow_coupon_code | No | boolean | - |
allow_quantity | No | boolean | - |
require_billing_address | No | boolean | When true, show and require billing address on checkout. Default when unset follows org settings, then false. See Checkout form fields. |
require_name | No | boolean | When true, show and require customer name. When false, hide the name field (display name falls back to email or phone). Default when unset: true. See Checkout form fields. |
require_email | No | boolean | When true, show and require email. When false, hide email. Default when unset: true. See Checkout form fields. |
require_phone | No | boolean | When true, show and require phone. When false, phone is optional if email is visible, or hidden if email is hidden. Default when unset: false. See Checkout form fields. |
fields | No | array<object> | Optional ordered checkout field schema. When provided, overrides require_* booleans. |
expires_at | No | string | - |
success_url | No | string | - |
cancel_url | No | string | - |
metadata | No | object | - |
Example body:
{
"link_type": "product",
"title": "string",
"currency_code": "XOF"
}Responses
| Status | Description |
|---|---|
201 | Created successfully |
400 | Bad request, invalid or missing parameters |
401 | Invalid or missing API key |
Errors
Errors follow the standard JSON error format (status code and machine-readable message). Validate inputs before calling; 401 indicates a missing/invalid key, 404 a missing resource for this organization, 429 rate limiting. For safe retries on create-style calls, send an idempotency key when your flow supports it.
Example
curl -sS -X POST "https://sandbox.api.lomi.africa/payment-links" \
-H "X-API-KEY: $LOMI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"link_type":"product","title":"string","currency_code":"XOF"}'OpenAPI
- operationId:
PaymentLinksController_create - Operation:
POST /payment-links
Full schemas and Try it: API reference. Machine-readable contract: repo apps/docs/openapi.json.