Reference
FAQ
Short answers to the questions integrators ask most.
Questions
Can I send the amount in the request?
No. In hosted mode the price, currency and period come from the offer configured in the console. Sending amount is rejected with VAL-006.
Is the return URL enough to grant access?
No. It is a hint for your UI. Grant from the signed webhook or from GET /v1/payments/{paymentUid} on your server.
Can I choose PIN or network recognition?
No. The consent method depends on the operator, the offer and your consent policy. Read GET /v1/capabilities to know what is available.
What happens if I retry a create after a timeout?
Send the same Idempotency-Key. Within 24 hours you get the original result back, never a second payment. PAY-104 means the first request is still in progress: wait and retry with the same key.
How do I switch a subscriber to another plan?
Plan changes are not payments. Do not start a second payment to switch plans; talk to the integration team about your offer structure.
Do I get the subscriber’s phone number?
No. You receive a subscriberUid scoped to your application. Keep your own account identifier in metadata.
How long does a token last?
One hour. Cache it and refresh shortly before it expires, not on every call.
What if my webhook endpoint is down?
PayLumia retries up to five times within 48 hours of the first attempt. After that the event is dead-lettered and can be replayed from the partner console.
Are refunds available?
Not through the hosted API in v1. Contact the integration team for a specific case.
Can the checkout be in Arabic or French?
The hosted checkout is localised for the subscriber; you do not translate consent screens yourself.