Receipt Validation API

Universal Receipt Validation 🔄

The foundation for integrating any platform with Iaptic. Validate purchases from:

• App Store (iOS/macOS)
• Play Store (Android)
• Stripe (Web)
• Third-party stores

Why Use This Endpoint?

• 🛡️ Secure Validation: Direct platform verification
• 🔄 Unified Interface: Single API for all platforms
• 📦 State Management: Automatic purchase tracking
• ⚡ Real-time Sync: Immediate entitlement updates

How It Works

sequenceDiagram
    participant Your App
    participant Your Server
    participant Iaptic
    participant Store
    Your App->>Iaptic: POST /v3/validate (with receipt)
    Iaptic->>Store: Verify receipt
    Store-->>Iaptic: Validation response
    Iaptic->>Iaptic: Process platform response
    Iaptic-->>Your App: Normalized validation result
    Iaptic-->>Your Server: Webhook notification

Example

iOS Request:

{
  "id": "app.example.com",
  "type": "application",
  "transaction": {
    "type": "ios-appstore",
    "id": "app.example.com",
    "appStoreReceipt": "MIIa...<base64 encoded receipt>..."
  },
  "additionalData": {
    "applicationUsername": "user_12345"
  }
}

Android Request:

{
  "id": "com.example.premium",
  "type": "subscription",
  "transaction": {
    "id": "GPA.1234-5678-9012-34567",
    "type": "android-playstore",
    "purchaseToken": "opaque_token_string",
    "receipt": "{...}",
    "signature": "Base64_RSA_signature"
  },
  "products": [
    {
      "id": "premium_monthly",
      "type": "subscription",
      "platforms": ["android"]
    }
  ]
}

Success Response: HTTP/1.1 200 OK

{
  "ok": true,
  "data": {
    "ineligible_for_intro_price": ["premium_monthly"],
    "id": "com.example.app.subscription",
    "collection": [
      {
        "id": "premium_monthly",
        "purchaseDate": 1630454400000,
        "expiryDate": 1633046400000,
        "isExpired": false,
        "isTrialPeriod": false,
        "isIntroPeriod": true,
        "renewalIntent": "Renew",
        "lastRenewalDate": 1630458000000
      }
    ],
    "transaction": {
      "platform-specific transaction data": "can be ignored"
    }
  }
}

Error Response: HTTP/1.1 200 OK

{
  "ok": false,
  "status": 419,
  "code": 6778003,
  "message": "Transaction has expired 2023-01-01 00:00:00 Etc/GMT",
  "data": {
    "latest_receipt": true
  }
}

Implementation Guide

1. Collect Receipt: After successful in-app purchase, obtain platform-specific receipt
2. Build Request:
   • Android: Include purchase token, receipt JSON, and signature
   • iOS: Include full App Store receipt
3. Send Validation: POST to /v3/validate with authentication headers
4. Handle Response:
   • Success: Store validation result and grant access, using the collection data as verified purchases.
   • Error: Surface appropriate message to user

Troubleshooting

Common Issues:

• 🔑 authentication_failed: Verify your appName/publicKey combination
• 📄 invalid_request: Check required fields in request body, and your settings are complete for the platform you are validating on.
• ⏳ validation_failed: Check Events for more details.

Next Steps

• Check the API reference for more details.
• Check the Webhook page for more details on how to handle the webhook notifications on your server.