​

Key Features of Swipe API

​

Getting Started

​

1. Create an Account

• Sign up on Swipe if you haven’t already.
• This gives you access to the Swipe API and other features.

​

2. Generate Your API Key

• Visit the API Integration section in your Swipe dashboard.
• Generate your API key and store it securely—it will be used for authentication.

​

3. Test the API in Playground

• Open our API Playground.
• Enter your API key as Bearer Token for any of the available endpoints and ensure everything is working.

​

4. Customize Invoice Templates & Settings (Optional)

• Log in to your Swipe portal and visit settings page.
• Modify invoice templates, settings, and configurations as per your business needs.

​

5. Start Using the API

• Use the Swipe API to create, edit invoices, manage customer/vendor data, and automate financial workflows.
• The API supports invoicing, payments, e-way bills, e-invoices, subscriptions, and more.

​

6. Monitor & Manage via Dashboard

• Track all invoices and transactions in real-time from the Swipe dashboard.
• Easily manage and analyze your invoicing data.

​

How to Test the API

1. Copy your API key from the Swipe portal.
2. Open the API Playground by visiting API Playground Link.
3. Enter your API key in the authorization field.
4. Select the API endpoint you want to test.
5. Fill in all the required fields for that specific API request.
6. Click the “Send” button to make the API request and see the response.
7. Review the response to verify if the API request was successful.

​

Webhooks

​

How Webhooks Work

1. Event Occurs: When an event happens in your Swipe account (like document creation or inventory changes)
2. Webhook Triggered: Swipe sends an HTTP POST request to your configured webhook URL
3. Your App Responds: Your application processes the webhook payload and responds with a 200 status code
4. Verification: Use the X-Signature header to verify the request authenticity

​

Available Event Types

​

Document Events

• Document creation
• Document updates
• Document status changes
• Document cancellation

​

Inventory Events

• Stock in operations
• Stock out operations
• Inventory level changes

​

Security & Verification

​

Verifying Webhook Signatures

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret):
    """
    Verify webhook signature using HMAC-SHA256
    
    Args:
        payload (str): Raw request body as string
        signature (str): Signature from X-Signature header
        secret (str): Your webhook secret
    
    Returns:
        bool: True if signature is valid, False otherwise
    """
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# Flask example
from flask import Flask, request

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    # Parse and process the webhook event
    event = json.loads(payload)
    print(f"Received event: {event['event_type']}")
    
    # Your webhook processing logic here
    if event['event_type'] == 'inventory':
        handle_inventory_event(event['data'])
    elif event['event_type'] == 'document':
        handle_document_event(event['data'])
    
    return 'OK', 200

def handle_inventory_event(data):
    product_id = data['swipe_product_id']
    qty = data['qty']
    movement = data['movement']
    print(f"Inventory update: Product {product_id}, {movement} {qty}")

def handle_document_event(data):
    doc_type = data['document_type']
    serial_number = data['serial_number']
    print(f"Document event: {doc_type} {serial_number}")

​

Setting Up Webhooks

1. Configure Webhook URL: Set up your webhook endpoint in your Swipe dashboard
2. Choose Event Types: Select which events you want to receive (document, inventory)
3. Set Webhook Secret: Configure a secret key for signature verification
4. Test Your Integration: Use our webhook testing tools to ensure proper setup

​

Best Practices

• Respond Quickly: Always respond with a 200 status code within 30 seconds
• Verify Signatures: Always verify the X-Signature header for security
• Handle Retries: Implement proper error handling as Swipe will retry failed webhooks
• Idempotency: Make your webhook handlers idempotent to handle duplicate events
• Logging: Log all webhook events for debugging and monitoring

​

Example Webhook Payloads

​

Document Event Payload

{
  "event_id": "ae24831c-6093-11f0-aef5-6045bd733335",
  "event_type": "document",
  "data": {
    "document_type": "purchase",
    "serial_number": "ui-1255test-25-26",
    "hash_id": "PUlgCNPb",
    "message": "Document Created",
    "timestamp": "2025-07-14 09:19:44.000000"
  }
}

​

Inventory Event Payload

{
  "event_id": "ae960d63-6093-11f0-aef5-6045bd733335",
  "event_type": "inventory",
  "data": {
    "swipe_product_id": 39346,
    "partner_product_id": -1,
    "product_name": "brazil",
    "qty": 1.0,
    "movement": "in",
    "timestamp": "2025-07-14 09:19:45.000000"
  }
}

​

Sample Webhook Request

curl -X POST https://your.webhook.endpoint \
  -H "Content-Type: application/json" \
  -H "X-Signature: f4c3b2d9d27d3fc4b0f53f2e1f1a9fda33e8b705f5155c9ef16e225b6a098765" \
  -d '{"event_id":"236c2c42-58c7-11f0-aef5-6045bd733335","event_type":"inventory","data":{"swipe_product_id":4839,"partner_product_id":"install_1500_p","product_name":"Installation (Split AC)","qty":7.0,"timestamp":"2025-07-04 11:07:56.000000","movement":"in"}}'