Purchase Journey
Data eSIM Service - Purchase Journey
| Authentication | Packages | Order | Install | Usage | Balance |
|---|---|---|---|---|---|
| User journey: Authenticate and get access token | User journey: Browse eSIM packages | User journey: Proceed to checkout and place an order | User journey: Install eSIM via QR code or manual method | User journey: Monitor eSIM usage | User journey: Check account balance |
| Endpoint: POST /customer/v2/token | Endpoint: GET /customer/v2/packages | Endpoint: POST /customer/v2/orders | Endpoint: GET /customer/v2/sims/:iccid/instructions | Endpoint: GET /customer/v2/sims/:iccid/usage | Endpoint: GET /customer/v2/balance |
| Description: [Request Access Token] provides JWT authentication for all subsequent API requests. Every API request must include the access token in the Authorization header. Access tokens are valid for 24 hours and can be refreshed using POST /customer/v2/auth/refresh. | Description: [Get Packages] provides Local, Regional, and Global packages available based on the applied filtering. Packages can include data-only or bundled Data + Voice + SMS plans. Optionally, the endpoint can also include all Top-up packages using the include=topup parameter. All packages are priced in NGN (Nigerian Naira). Tip: Partner can cache the result but should periodically refresh to avoid offering packages that are no longer available. Recommended to pull it at least once per hour. | Description: [Submit Order] creates an order and provides the eSIM including the ordered package details. There will be one or more eSIMs depending on the requested quantity. The response contains installation instructions and QR codes. Important note: Make an order only after payment is collected from the end user. Ensure your account has sufficient balance (pre-paid) or available credit (post-paid) before placing orders. All packages are priced in NGN (Nigerian Naira). | Description: Retrieving the language-specific installation instructions of a specific eSIM from the PressOne Partners API using the eSIM's ICCID. Installation methods: QR code - Generate QR code on your own (attribute qrcode) or use QR code link (qrcode_url). Manual installation - Use SM-DP+ address (lpa) and activation code (matching_id). Direct installation (iOS) - Use direct_apple_installation_url for iOS 17.4+ devices. | Description: [Get Data Usage] provides information about the usage of the eSIM. Limitation: Make sure to cache the result for up to 15 minutes for the same eSIM. The endpoint allows 1 request for an eSIM per 15 minutes to prevent rate limiting. | Description: [Get Balance] provides information about your account balance and credit limits. |
| Response: - token_type: "Bearer"- expires_in: 86400 (24 hours in seconds)- access_token: JWT access token string to be used during each API call | Response: - id (package_id): Main package id, required for ordering an eSIM package through [Submit Order]- price: PressOne retail price (minimum selling price)- net_price: Package net price (wholesale price)- retail_price: Recommended retail price- amount: Data volume in megabytes (0 for unlimited)- day (validity): Number of days- voice: Credits in minutes (if included)- text: Number of SMS messages (if included)- data: Data amount description (e.g., "3 GB" or "Unlimited")- is_unlimited: Boolean indicating unlimited data- type: Package type (local, regional, global)- country: Country information- operator: Operator information | Response: Package details: - package_id: Given package id- package: Package name and description- data: Data amount- validity: Validity period- price: Order priceeSIM details: - iccid: Unique id for the eSIM, required to store on partner side for reference- qrcode_url: Link for the QR code for automatic installation- qrcode: QR code data to build your own QR code- lpa: SM-DP+ address for manual installation- matching_id: Activation code for manual installation- apn_type: Manual or Automatic (OS-specific)- apn_value: APN to show and display to customers- direct_apple_installation_url: Direct installation on iOS devices (iOS 17.4+)- manual_installation: Installation guide for manual installation- qr_installation: Installation guide for QR code based installation | Response: Translated installation instructions for both iOS and Android, supporting different models and versions. The partner can create PDFs and emails with step-by-step instructions. Also contains eSIM specific codes and settings. - installation_qr_code: Step-by-step installation guide for QR code- installation_manual: Step-by-step installation guide for manual setup- network_setup: Step-by-step installation guide for network setup- apn_type: "automatic" or "manual"- apn_value: The value to be set in case of manual setup is needed- direct_apple_installation_url: Direct installation on iOS devices (iOS 17.4+) | Response: - remaining: Remaining data in megabytes- remaining_voice: Remaining voice minutes (if applicable)- remaining_text: Remaining number of text messages (if applicable)- total: Total data in megabytes- expired_at: In case the package is ACTIVE or EXPIRED or FINISHED, the expire date is set- status: Status of the package (ACTIVE, NOT_ACTIVE, ACTIVE_FINISHED, UNKNOWN, EXPIRED) | Response: - balance: Current account balance in NGN- available_credit: Available credit for post-paid accounts- credit_limit: Credit limit for post-paid accounts- currency: Currency code (NGN) |
| Request: - api_key: Your API key provided by PressOne during onboardingTip: Store the token securely and refresh it before expiration to avoid authentication errors. | Request: Depending on the destination selection, packages can be filtered by: - type=local or filter[type]=local: Country-specific packages only- type=global or filter[type]=global: Global and regional packages- country_code=US or filter[country]=US: Filter by specific country code- include=topup: Include top-up packages in response- page and limit: Pagination parameters | Request: - package_id: Id of local, regional or global package, returned by the [Get Packages] endpoint- quantity: Usually 1, customer buys 1 item. If the customer buys multiple eSIMs, use bulk order (e.g., for multiple customers)- description: Optional but can be used for filtering orders in [Get Order List]Tip: Use customer id, or customer id and own order id combination | Request: - iccid: Unique id for the eSIM returned by Submit Order (Path variable)- language: Optional language code (e.g., "en", "es", "fr") for localized instructions | Request: - iccid: Unique id for the eSIM returned by [Submit Order] (Path variable)Tip: Implement client-side caching to handle frequent customer requests and avoid rate limit errors. | Request: No parameters required (uses authenticated token) Tip: Check balance before placing orders to ensure sufficient funds are available. |
Voice-Only eSIM Service - Number Management Journey
| Authentication | Available Numbers | Claim Number | User Management |
|---|---|---|---|
| User journey: Authenticate API requests | User journey: Browse available phone numbers | User journey: Claim a phone number for a user | User journey: Retrieve users and subscription information |
| Endpoint: Bearer Token Authentication | Endpoint: GET /api/third-party/partner/available-numbers/ | Endpoint: POST /api/third-party/partner/claim-number/ | Endpoint: GET /api/third-party/partner/user/ |
Description: PressOne Africa provides you with an API key to communicate with the API endpoints. We use the Bearer token authentication method, so you must add the "Authorization" header to every request. Base URL: https://api.pressone.co/ Tip: Keep your API key secure and never expose it in client-side code or version control. | Description: [List Available Numbers] provides a paginated list of available phone numbers that can be claimed for users. You can filter by phone number and paginate through results. Tip: Use pagination to browse through available numbers efficiently. | Description: [Claim Number] assigns an available phone number to a user and creates their subscription. This is the primary step in provisioning a Voice-Only eSIM service for a customer. Important note: Ensure you have collected all required user information, including NIN (National Identification Number), before claiming a number. | Description: [List User] provides a paginated list of users who signed up to PressOne via your platform. This endpoint allows you to retrieve user information along with their subscription details. Tip: Use this endpoint to monitor user subscriptions, check active status, and manage your user base. |
Request Header:Authorization: Bearer YOUR_API_KEY | Response: - data: Array of available numbers- country_code: Two-letter country code- phone_number: Available phone number- total: Total number of available numbers- page_index: Current page number- page_size: Number of results per page- nb_pages: Total number of pages- previous: URL to previous page (if available)- next: URL to next page (if available) | Response: - message: Success or error message- success: Boolean indicating if the operation was successful- data: Response data (null on success) | Response: - data: Array of user objects- first_name: User's first name- last_name: User's last name- email: User's email address- mobile: User's mobile number- subscription: Subscription object- plan: Subscription plan name- term: Subscription term- standard_cost: Standard cost amount- is_active: Boolean indicating if subscription is active- is_free_trial: Boolean indicating if it's a free trial- billing_day: Day of the month when billing occurs- date_created: When the subscription was created- date_created: When the user account was created- total: Total number of users- page_index: Current page number- page_size: Number of results per page- nb_pages: Total number of pages- previous: URL to previous page (if available)- next: URL to next page (if available) |
| Request: - phone_number (optional): Filter by specific phone number- page_index (optional, default: 1, min: 1): Page number for pagination- page_size (optional, default: 10, min: 1, max: 100): Number of results per page | Request: - business_name: Business name (required)- dob: Date of birth in YYYY-MM-DD format (required)- email: User's email address (required)- first_name: User's first name (required)- last_name: User's last name (required)- mobile: User's mobile number (required)- nin: National Identification Number - max 11 digits, numeric only (required)- pressone_number: PressOne phone number to claim (required)- is_free_trial (optional, default: false): Whether this is a free trial subscriptionTip: Store the user's email and phone number for future reference, as these are used for renewals and user management. | Request: - mobile (optional): Filter by mobile number- email (optional): Filter by email address- page_index (optional, default: 1, min: 1): Page number for pagination- page_size (optional, default: 10, min: 1, max: 100): Number of results per page |
Modified at 2025-11-15 22:27:12