Developer Documentation
Lebaneeds Payments API
A versioned REST API for creating and managing payments across every connected method. This page is the working reference for integration partners; sandbox credentials are issued during onboarding.
Authentication
Every request is authenticated with a secret API key sent as a bearer token. Keys are scoped per environment: sk_test_… for sandbox, sk_live_… for production. Keys can be rotated and revoked instantly from the dashboard. OAuth 2.0 client-credentials flows are available for platform partners with delegated access needs.
curl https://api.lebaneeds.com/v1/payments \
-H "Authorization: Bearer sk_test_…"Idempotency
All mutating requests accept an Idempotency-Key header. Retrying a request with the same key returns the original result instead of creating a duplicate — network retries can never double-charge.
-H "Idempotency-Key: 4f7c2e9a-order-8412"Payments
POST/v1/payments
Creates a payment. The routing engine selects a connected, licensed provider based on method, currency and availability, and returns a hosted checkout_url where the customer completes payment.
{
"amount": 150000,
"currency": "LBP",
"method": "wallet",
"customer": { "email": "customer@example.com" },
"metadata": { "order_id": "8412" }
}| Field | Type | Description |
|---|---|---|
amount | integer | Amount in the currency's smallest unit. Required. |
currency | string | ISO 4217 code, e.g. LBP, USD. Required. |
method | string | wallet, card, bank_transfer, cash, qr — or omit to let the customer choose at checkout. |
customer | object | Optional customer details for receipts and risk checks. |
metadata | object | Up to 20 key–value pairs echoed back on every event. |
GET/v1/payments/{id}
Retrieves a payment. Status is one of pending, processing, succeeded, failed, refunded.
Webhooks
POST/v1/webhooks
Registers an endpoint to receive events. Every delivery is signed with HMAC-SHA256 in the Lebaneeds-Signature header; verify it before acting. Failed deliveries are retried with exponential backoff for 24 hours, and events carry a monotonically increasing sequence per payment so out-of-order deliveries are detectable.
| Event | Fired when |
|---|---|
payment.succeeded | Funds confirmed by the provider. |
payment.failed | The provider declined or the customer abandoned checkout. |
payment.refunded | A refund completed on the original payment. |
settlement.completed | The licensed partner executed settlement for a period. |
Errors
Errors use conventional HTTP status codes with a machine-readable body.
{
"error": {
"type": "invalid_request",
"code": "currency_not_supported",
"message": "Currency 'XYZ' is not supported for method 'wallet'."
}
}| Status | Meaning |
|---|---|
400 | Invalid request — a field is missing or malformed. |
401 | Missing or invalid API key. |
402 | The payment could not be completed. |
404 | The resource does not exist in this environment. |
409 | Idempotency conflict — same key, different payload. |
429 | Rate limit exceeded — retry after the interval in Retry-After. |
5xx | Something failed on our side; safe to retry with the same idempotency key. |
Rate limits
Limits are applied per key and scale with your integration tier; responses include RateLimit-Remaining headers, and 429 responses include Retry-After. Bursts from retries with idempotency keys are always safe.
Versioning
The API version is part of the path (/v1/). Backwards-incompatible changes ship as a new version; existing versions receive advance deprecation notice to every integration partner. Additive changes (new fields, new event types) are not considered breaking — parse defensively.
Sandbox access
The sandbox mirrors production behavior with test keys and simulated provider responses for every payment method. Sandbox credentials are currently issued to integration partners during onboarding rather than by self-service signup.