Skip to main content

iOS Wallet Endpoints

This documentation covers the endpoints for managing iOS wallet operations, including in-app purchase charging, credit balance checking, and App Store server notifications.

Charge Wallet via In-App Purchase​

Charge the user's wallet with credits after a successful in-app purchase transaction.

Endpoint​

POST /v1/mobile/ios/wallets/charge-by-iap

Authentication​

Requires customer authentication token.

Request Body​

ParameterTypeDescription
transaction_idstringThe transaction ID received from StoreKit after a successful purchase

Response​

Success Response​

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "balance": 916.05
    },
    "status_code": 200
}

Implementation Flow​

  1. JWT Authentication

    • System generates an App Store Server API JWT token using AppStoreJwtAuthenticatorService
    • JWT is used to authenticate requests to App Store Server API

  2. Transaction Validation

    • System validates the transaction with Apple's servers using InAppPurchaseService
    • Different endpoints are used for sandbox and production environments

  3. Wallet Charging

    • Upon successful validation, the system charges the user's wallet
    • Credits are added based on the purchased package

Environment Handling​

  • Sandbox mode is automatically enabled for non-production environments
  • Production mode uses live App Store endpoints

Get Wallet Credits​

Retrieve the current balance of the user's wallet.

Endpoint​

GET /v1/mobile/ios/wallets/credits

Authentication​

Requires customer authentication token.

Response​

Success Response​

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "balance": 916.05
    },
    "status_code": 200
}

Implementation Notes​

  • If user doesn't have a wallet, one is automatically created using WalletService
  • Balance is always fetched from a fresh instance of the user model

App Store Server Notifications​

Handle App Store Server Notifications for transaction updates.

Endpoint​

POST /v1/mobile/ios/in-app-purchase/callback

Request Body​

ParameterTypeDescription
signedPayloadstringJWT signed payload from App Store Server Notifications

Implementation Notes​

  • Processes App Store Server Notifications via InAppPurchaseService
  • Handles various notification types
  • Updates transaction status in the database

Example Implementation Flow​

  1. Purchase Initiation

    • App initiates purchase through StoreKit
    • User completes payment through App Store

  2. Transaction Processing

    • App receives transaction details from StoreKit
    • App sends transaction ID to backend
    • Backend validates with App Store servers
    • Credits are added to user's wallet

  3. Server Notifications

    • App Store sends notifications about transaction updates
    • Backend processes notifications and updates transaction status

Key Considerations​

  • Implement proper error handling for failed transactions
  • Handle network timeouts and retries
  • Maintain transaction logs for debugging
  • Consider implementing transaction status polling
  • Handle sandbox vs production environment differences