Reference

API reference

The hosted surface of the PayLumia Partner API v1. Samples below use the sandbox base URL https://api.sandbox.paylumia.com (plm_test_, mock). Swap to https://api.sandbox.paylumia.com (plm_live_) for production. See environments. Download the OpenAPI 3.1 file for your tooling.

POST/oauth2/token

Get an access token

OAuth 2.0 client credentials. Form-encoded body. The token lasts one hour.

Parameters

grant_typestringrequired: client_credentials
client_idstringrequired: plm_test_… (sandbox) · plm_live_… (production)
client_secretstringrequired: Shown once when the environment is created.

curl https://api.sandbox.paylumia.com/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=$PAYLUMIA_CLIENT_ID \
  -d client_secret=$PAYLUMIA_CLIENT_SECRET

Response

{
  "access_token": "eyJ0eXAiOi…",
  "token_type": "bearer",
  "expires_in": 3600
}

GET/v1/capabilities

List capabilities

What is available for a country, and optionally an operator: modes, consent methods and instruments.

Parameters

countryCodequery · ISO 3166-1required: For example TN.
operatorquery · string: Narrows the answer to one operator.

cURL

curl "https://api.sandbox.paylumia.com/v1/capabilities?countryCode=TN&operator=ORANGE_TN" \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"

200 OK

{
  "success": true,
  "data": {
    "countryCode": "TN",
    "operator": "ORANGE_TN",
    "modes": ["HOSTED", "API"],
    "consentMethods": ["PIN", "HEADER_ENRICHMENT", "MO_SMS"],
    "operatorConsentPage": false,
    "instruments": ["DCB"]
  }
}

POST/v1/payments

Create a payment

Creates a hosted payment session and returns its checkoutUrl. Requires an Idempotency-Key header.

Parameters

modeenumrequired: HOSTED
offerUidstringrequired: Offer to sell.
returnUrlurirequired: Browser return, UX only.
presentationenum: redirect (default) · embedded
prefillobject: msisdn (E.164), msisdnEditable (boolean, default true)
operatorstring: Operator hint.
metadataobject ≤ 20 keys: Echoed on reads and webhooks.

curl https://api.sandbox.paylumia.com/v1/payments \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN" \
  -H "Idempotency-Key: order-8891" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "HOSTED",
    "offerUid": "premium_daily",
    "returnUrl": "https://app.example.tn/return",
    "presentation": "redirect",
    "prefill": { "msisdn": "+21620123456", "msisdnEditable": true },
    "metadata": { "orderRef": "order-8891" }
  }'

201 Created

{
  "success": true,
  "data": {
    "object": "payment",
    "paymentUid": "pay_4mK9pQeRw2Ns6TfXb1Zy0a",
    "mode": "HOSTED",
    "status": "REQUIRES_ACTION",
    "checkoutUrl": "https://pay.sandbox.paylumia.com/c/pay_4mK9pQeRw2Ns6TfXb1Zy0a",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "expiresAt": "2026-09-20T15:30:00Z",
    "metadata": { "orderRef": "order-8891" }
  }
}

GET/v1/payments/{paymentUid}

Retrieve a payment

Returns the payment object. Use it to confirm status server-side.

Parameters

paymentUidpathrequired: For example pay_4mK9pQeRw2Ns6TfXb1Zy0a.

curl https://api.sandbox.paylumia.com/v1/payments/pay_4mK9pQeRw2Ns6TfXb1Zy0a \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"

200 OK

{
  "success": true,
  "data": {
    "object": "payment",
    "paymentUid": "pay_4mK9pQeRw2Ns6TfXb1Zy0a",
    "mode": "HOSTED",
    "status": "SUCCEEDED",
    "orderId": "0b8f3f5e-3f55-4c1a-9a44-2f0c7f0b9d61",
    "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "expiresAt": "2026-09-20T15:30:00Z",
    "metadata": { "orderRef": "order-8891" }
  }
}

POST/v1/payments/{paymentUid}/cancel

Cancel a payment

Cancels a payment still waiting on the customer. Not allowed after SUCCEEDED.

Parameters

paymentUidpathrequired: The payment to cancel.

cURL

curl -X POST https://api.sandbox.paylumia.com/v1/payments/pay_4mK9pQeRw2Ns6TfXb1Zy0a/cancel \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"

200 OK

{ "success": true, "data": { "object": "payment", "paymentUid": "pay_4mK9pQeRw2Ns6TfXb1Zy0a", "status": "CANCELED" } }

GET/v1/subscriptions/{subscriptionUid}

Retrieve a subscription

Status, product, offer, subscriber, current period end and scheduled cancellation.

Parameters

subscriptionUidpathrequired: From the payment of a SUBSCRIPTION offer.

cURL

curl https://api.sandbox.paylumia.com/v1/subscriptions/sub_2Rt8xVq0LmN4pK7a \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"

200 OK

{
  "success": true,
  "data": {
    "subscriptionUid": "sub_2Rt8xVq0LmN4pK7a",
    "status": "PRE_CANCELED",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
    "currentPeriodEnd": "2026-09-21T15:12:44Z",
    "cancelAt": "2026-09-21T15:12:44Z"
  }
}

POST/v1/subscriptions/{subscriptionUid}/cancel

Cancel a subscription

Ends access now, or at the end of the last paid period.

Parameters

whenenumrequired: NOW · PERIOD_END

cURL

curl -X POST https://api.sandbox.paylumia.com/v1/subscriptions/sub_2Rt8xVq0LmN4pK7a/cancel \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "when": "PERIOD_END" }'

200 OK

{
  "success": true,
  "data": {
    "subscriptionUid": "sub_2Rt8xVq0LmN4pK7a",
    "status": "PRE_CANCELED",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
    "currentPeriodEnd": "2026-09-21T15:12:44Z",
    "cancelAt": "2026-09-21T15:12:44Z"
  }
}

POST/v1/subscriptions/{subscriptionUid}/resume

Resume a subscription

Withdraws a scheduled PERIOD_END cancellation. No body.

Parameters

subscriptionUidpathrequired: A PRE_CANCELED subscription.

cURL

curl -X POST https://api.sandbox.paylumia.com/v1/subscriptions/sub_2Rt8xVq0LmN4pK7a/resume \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"

200 OK

{
  "success": true,
  "data": {
    "subscriptionUid": "sub_2Rt8xVq0LmN4pK7a",
    "status": "ACTIVE",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
    "currentPeriodEnd": "2026-09-21T15:12:44Z",
    "cancelAt": null
  }
}

POST{your webhook URL}

Webhook event

Sent by PayLumia to your environment’s webhook URL, signed in PayLumia-Signature. Respond 2xx.

Parameters

PayLumia-Signatureheaderrequired: t={unix},v1={hmac} over {t}.{rawBody}
eventstringrequired: payment.*, entitlement.*, subscription.*

payment.succeeded

{
  "event": "payment.succeeded",
  "paymentUid": "pay_4mK9pQeRw2Ns6TfXb1Zy0a",
  "status": "SUCCEEDED",
  "orderId": "0b8f3f5e-3f55-4c1a-9a44-2f0c7f0b9d61",
  "productUid": "premium",
  "offerUid": "premium_daily",
  "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
  "metadata": { "orderRef": "order-8891" },
  "occurredAt": "2026-09-20T15:12:44Z"
}