ChoEsim Partner API: FAQ
1. What can I do with the API?
You can list the plans you can buy, price a basket, buy eSIMs from a prepaid USD wallet, read orders and activation strings, cancel an order of unused eSIMs, and receive signed webhooks.
2. How do I get an API key?
You create keys yourself. Apply online with a verified email address, then sign in to the partner portal and create a test key; no one has to approve you first. A live key can be created in the portal after your first top-up has been credited. A key is shown once.
2b. How do I apply?
Use the online application: sign in, fill in the company details and tick the partner terms. Your account opens at once with a test wallet and default limits. We refuse the application automatically only for countries under comprehensive sanctions. If the form does not work for you, write to support@choesim.com with the subject "Partner API".
3. Can I try the API without paying?
Yes. A cesim_test_ key uses a fake catalogue and a fake wallet. It never reaches a supplier and never spends money.
4. What currency and format do amounts use?
US dollars, as integers in cents (amount_minor). For example 1260 is USD 12.60. There are no decimals.
5. Do I see a retail price?
No. You see your wholesale price. The cost to ChoEsim and any retail price are never returned. ChoEsim does not publish a suggested retail price: you set your own prices.
6. How is my wallet funded?
In the partner portal you enter the amount you want and pay by card through OnePay. The card is charged in Vietnamese dong at the ChoEsim system exchange rate with no margin added, and ChoEsim pays the payment gateway fees. The balance is credited when the payment is confirmed. Where we have agreed a bank transfer, the portal shows the bank details and the exact reference to write on the transfer. There is no top-up API for live wallets.
7. What is the minimum deposit?
USD 50 for the first top-up and USD 25 for each later top-up. The wallet balance cannot exceed three times your daily spend limit.
8. Can the balance go below zero?
No. If the wallet is lower than the order total you get 402 insufficient_balance, and nothing is debited.
9. How many eSIMs can I buy in one order?
Up to 10 lines, at most 10 eSIMs per line, and 30 eSIMs in total. Your account also has a maximum order value, a daily spend limit (per UTC day) and a maximum number of open orders. GET /me shows them.
10. Can I buy daily (per-day) plans?
Not in version 1. Only fixed-data plans are sold.
11. My order call timed out. What do I do?
Do not create a second order. Read the order with GET /orders/{id} or GET /orders?reference=..., or repeat the same request with the same Idempotency-Key.
12. What does processing with under_review mean?
ChoEsim staff are checking the outcome. Your wallet stays debited until the result is proven. The order is not failed. ChoEsim gives no committed resolution time in version 1.
13. How long do idempotency keys last?
7 days. The reference of an order stays unique forever per mode, so a duplicate is still caught after that.
14. I got 409 price_changed. Can I reuse the same Idempotency-Key?
Yes. The order was refused before any money was taken, so nothing is stored for the key. You may send the corrected request with the same key or with a new key.
15. What does a repeated request return?
The current state of the same order, with Idempotent-Replayed: true. The status code follows that state: 201 once the order is fulfilled, 202 while it is accepted or processing, 200 if it ended as failed or cancelled.
16. Can I cancel an order?
Yes, if every eSIM in the order is unused, the supplier accepts it, and the order is within the cancellation window. The whole order is cancelled and your wallet is credited in full. Partial cancellation is not supported.
17. How long do I have to cancel?
14 days from the day the order was created, by default. ChoEsim can set a different value for your account. GET /me shows it as cancel_window_days. After that, a cancel gets 409 cancel_window_expired.
18. How many cancellations can I make per day?
A daily cap applies, per UTC day. The default is 5 (daily_cancel_cap in GET /me). Above the cap you get 422 cancel_limit_exceeded.
19. Can I get unused wallet money back in cash?
Not as cash. A cancelled order is credited back to your balance. When you end the agreement, or on written request, ChoEsim refunds the unused balance only to the card or bank account that paid it and that is in your name (card refunds go through the payment gateway), after bank fees and amounts you owe. See the partner terms.
20. Do webhooks always arrive?
No. They can be late, out of order or repeated. Treat GET /orders/{id} as the truth and use GET /events to catch up. Use webhook-id to skip duplicates.
21. Can I send my customers' names or e-mail addresses?
No, and you do not need to. Use customer_reference, your own opaque id. A value with an @ sign or nine or more digits in a row is rejected. ChoEsim does not e-mail your customers.
22. Do you give me a QR code?
No. You get the activation string (lpa). Build your own QR code from it. Treat the string as a secret.
23. Do you promise coverage, speed or device compatibility?
No. coverage is reported by the supplier and is not a ChoEsim guarantee. ChoEsim makes no promise about speed. Check device compatibility with your customer before you sell.
24. What are the rate limits?
Default targets, which may change: 60 reads, 30 quotes, 10 order creations (burst of 3) and 5 cancels per minute per key. The live limit is always in the X-RateLimit-* headers, and a 429 has Retry-After.
25. What is the support promise or uptime?
Support is by e-mail on business days, Vietnam time (GMT+7). We aim to reply within two business days; this is a target, not a commitment. v1 has no uptime guarantee. The status of an order is always available from GET /orders/{id}, so a temporary problem on our side never loses an order.
26. How much notice will I get before a breaking change?
At least six months for a deprecation. For urgent security, legal or abuse reasons it can be shorter.
27. What do the partner terms cover?
The partner terms cover responsibility for leaked keys, service levels, deposit and refund rules, tax, data roles, and what you may and may not do when you sell. They are not repeated in this documentation.