Wallet App: Guide to Fetching a User's Receipts via OAuth

This is a developer guide for stores and brands that have their own iOS app, Android app, or LINE Mini App.
Using ReceiptRoller's OAuth authentication and API, you can fetch the digital receipts issued at your store, with the user's consent, and display them in your own app.

Use cases

For example, you can build things like these.

• A convenience-store chain shows "purchase history" in its own app
• A drugstore shows "My Receipts" in a LINE Mini App
• An e-commerce brand shows a monthly spending summary on the dashboard of its Android app
• The moment a purchase completes, receipt data is sent to your own server via Webhook

How it works

User → Your app → OAuth consent screen (ReceiptRoller)
                              ↓
                        Access token issued
                              ↓
              Your app → Receipts API → Fetch digital receipts

Your app obtains an access token via ReceiptRoller's OAuth 2.0 flow.
When you call the API with that token, it returns the receipts that user received at your store.

Step 1: Register an app

1. Log in to ReceiptRoller's developer portal
2. From "Register app," issue a client ID and secret
3. Set the redirect_uri (the redirect destination after authorization)

Step 2: Implement the OAuth authorization code flow

2-1. Obtain an authorization code

Send the user to the following URL in a browser.

GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=user.receipts.read user.spending.read
  &state=RANDOM_STRING

When the user taps "Allow" on ReceiptRoller's consent screen, an authorization code is returned to redirect_uri.

YOUR_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STRING

2-2. Exchange the code for a token

POST /api/v1/auth/token
Content-Type: application/json

{
  "grantType": "authorization_code",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "code": "AUTH_CODE",
  "redirectUri": "YOUR_REDIRECT_URI"
}

Response:

{
  "accessToken": "eyJ...",
  "refreshToken": "def50200...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "user.receipts.read user.spending.read"
}

2-3. Refreshing the token

Refresh when the access token expires.

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "def50200...",
  "clientId": "YOUR_CLIENT_ID"
}

Step 3: Fetch receipts

Add an Authorization: Bearer {access_token} header to every API request.

Receipt list (supports monthly filtering)

GET /api/v1/user/receipts?year=2026&month=4
Authorization: Bearer {access_token}

Receipt detail (includes line items and store info)

GET /api/v1/user/receipts/{id}
Authorization: Bearer {access_token}

Monthly spending summary

GET /api/v1/user/receipts/summary?year=2026&month=4
Authorization: Bearer {access_token}

Scope: user.spending.read
Returns the breakdown by category, month-over-month comparison, and receipt count. Useful for building a dashboard screen.

Step 4: Receive real-time notifications via Webhook

Instead of polling the API, you can receive a notification to your own server the moment a receipt is issued. Registering a Webhook endpoint from the developer portal causes a POST every time a user's receipt is created or updated.

Security verification

To confirm that a received Webhook is legitimate, verify the X-RR-Signature header.

import hmac, hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Scopes needed

Supported platforms

Frequently asked questions

Q. Do I only get receipts from my own store?
A. Yes. Of the receipts the OAuth-authenticated user received, the API returns only those associated with your store. You cannot fetch other stores' data.

Q. What if the user revokes consent?
A. The access token is invalidated. Subsequent API requests return 401.

Q. Are Webhooks re-sent?
A. If your server doesn't return 2xx, they are automatically retried up to 4 times.

Next steps

• For technical questions, contact support