Skip to main content

BoltPay (Payment Gateway)

Purpose
Enterprise payment gateway providing comprehensive financial transaction processing with advanced fraud detection, recurring billing, and multi-provider support.

Description
boltPay represents a complete payment processing ecosystem that handles everything from simple one-time transactions to complex recurring billing scenarios. The system integrates multiple payment providers, implements sophisticated fraud detection algorithms, and provides real-time transaction monitoring. It supports various payment methods, currencies, and regional payment preferences while maintaining PCI DSS compliance.

Core Payment Operations

  • Multi-provider payment routing and failover
  • Advanced fraud detection and risk scoring
  • Real-time authorization and capture processing
  • Comprehensive refund and chargeback management
  • Payment method tokenization for security

Recurring Payment Management

  • Flexible subscription billing cycles
  • Dunning management for failed payments
  • Prorated billing and mid-cycle changes
  • Subscription lifecycle automation
  • Revenue recognition and reporting

Callback and Webhook System

  • Real-time payment status notifications
  • Automated business process triggers
  • Comprehensive event logging and monitoring
  • Retry mechanisms for failed notifications
  • Custom webhook endpoint configuration

Business Value
Maximizes payment success rates, minimizes fraud losses, automates financial operations, ensures regulatory compliance, provides comprehensive financial reporting, and enables global payment processing with local payment method support.

Payment Processing

Purpose: Enterprise payment gateway providing comprehensive financial transaction processing with advanced fraud detection, recurring billing, and multi-provider support.

Description: boltPay represents a complete payment processing ecosystem that handles everything from simple one-time transactions to complex recurring billing scenarios. The system integrates multiple payment providers, implements sophisticated fraud detection algorithms, and provides real-time transaction monitoring. It supports various payment methods, currencies, and regional payment preferences while maintaining PCI DSS compliance.

Core Payment Operations​

  • Multi_provider payment routing and failover
  • Advanced fraud detection and risk scoring
  • Real_time authorization and capture processing
  • Comprehensive refund and chargeback management
  • Payment method tokenization for security

Recurring Payment Management​

  • Flexible subscription billing cycles
  • Dunning management for failed payments
  • Prorated billing and mid_cycle changes
  • Subscription lifecycle automation
  • Revenue recognition and reporting

Callback and Webhook System​

  • Real_time payment status notifications
  • Automated business process triggers
  • Comprehensive event logging and monitoring
  • Retry mechanisms for failed notifications
  • Custom webhook endpoint configuration

Business Value: Maximizes payment success rates, minimizes fraud losses, automates financial operations, ensures regulatory compliance, provides comprehensive financial reporting, and enables global payment processing with local payment method support.

Legacy Payment Endpoints

Purpose: Backward compatibility support for existing rental payment integrations while maintaining transition path to modern payment infrastructure.

Description: These endpoints provide continuity for existing rental product integrations that were built before the comprehensive boltPay system implementation. They maintain the specific rental payment workflow while gradually migrating functionality to the more robust boltPay infrastructure. The system handles rental-specific payment scenarios including equipment delivery confirmations, damage deposits, and return processing.

Rental Payment Features​

  • Equipment_specific payment tracking
  • Delivery and return confirmation integration
  • Damage assessment and billing
  • Security deposit management

Business Value: Ensures uninterrupted service for existing integrations, provides smooth migration path to enhanced payment infrastructure, and maintains rental-specific business logic during platform evolution.

POST /boltpay/authorization

Purpose:
Authorizes payment transactions with comprehensive fraud detection and risk assessment.

Endpoint Explanation:
This endpoint performs payment authorization by validating payment methods, checking available funds, and conducting real-time fraud analysis. The system reserves the specified amount without capturing funds, enabling merchants to confirm orders before final payment processing. Advanced risk scoring algorithms evaluate transaction patterns, customer behavior, and device fingerprints to detect potential fraud while minimizing false positives that could impact legitimate customers.

BoltPay Authorization

Purpose:
Authorizes payment transactions with comprehensive fraud detection and risk assessment.

Endpoint Explanation:
This endpoint performs payment authorization by validating payment methods, checking available funds, and conducting real-time fraud analysis. The system reserves the specified amount without capturing funds, enabling merchants to confirm orders before final payment processing. Advanced risk scoring algorithms evaluate transaction patterns, customer behavior, and device fingerprints to detect potential fraud while minimizing false positives that could impact legitimate customers.

POST /boltpay/authorization​

curl -X POST https://api.bolttech.com/boltpay/authorization     -H "Authorization: Bearer <token>"     -H "Content-Type: application/json"     -d '{
    "amount": 150.00,
    "currency": "EUR",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4111111111111111",
        "expiry_month": "12",
        "expiry_year": "2025",
        "cvv": "123",
        "holder_name": "John Smith"
      }
    },
    "customer": {
      "id": "CUST_123456",
      "email": "[email protected]",
      "name": "John Smith"
    },
    "order_id": "ORDER_789456123",
    "description": "Device Protection Insurance Premium",
    "capture": false,
    "metadata": {
      "product_type": "device_protection",
      "partner_id": "PARTNER_001"
    }
  }'

POST /boltpay/payment/create​

Purpose:
Creates new payment transactions with comprehensive fraud and risk checks.

Endpoint Explanation:
This endpoint initiates complete payment transactions by combining authorization and capture processes with advanced fraud detection capabilities. The system validates payment instruments, performs real-time risk assessment, processes payments through optimal routing algorithms, and provides immediate transaction results. Multi-layered security includes device fingerprinting, behavioral analysis, and machine learning-based fraud detection.

curl -X POST https://api.bolttech.com/boltpay/payment/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 199.99,
    "currency": "EUR",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4111111111111111",
        "expiry_month": "12",
        "expiry_year": "2025",
        "cvv": "123",
        "holder_name": "Maria Silva"
      }
    },
    "customer": {
      "id": "CUST_789456",
      "email": "[email protected]",
      "name": "Maria Silva",
      "phone": "+351934567890"
    },
    "order_id": "ORDER_456789123",
    "description": "Insurance Premium Payment",
    "capture": true,
    "return_url": "https://partner.com/payment/success",
    "cancel_url": "https://partner.com/payment/cancel",
    "webhook_url": "https://partner.com/webhooks/payment",
    "metadata": {
      "contract_id": "CONTRACT_001",
      "product_type": "health_insurance",
      "partner_reference": "PARTNER_REF_123"
    },
    "risk_data": {
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "device_fingerprint": "fp_abc123def456"
    }
  }'

Payment Capture

Purpose:
Captures previously authorized payments with automatic settlement processing.

Endpoint Explanation:
This endpoint finalizes payment transactions by capturing funds from previously authorized transactions. The system validates authorization status, processes fund transfers, calculates final fees, and initiates settlement procedures. Capture operations can be partial or full amounts and include comprehensive transaction logging for reconciliation and reporting purposes.

POST /boltpay/payment/capture​

curl -X POST https://api.bolttech.com/boltpay/payment/capture \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN_987654321",
    "amount": 150.00,
    "currency": "EUR",
    "final_amount": 150.00,
    "metadata": {
      "capture_reason": "order_confirmed",
      "order_status": "shipped",
      "tracking_number": "TRK123456789"
    }
  }'
{
  "transaction_id": "TXN_987654321",
  "status": "captured",
  "captured_amount": 150.0,
  "currency": "EUR",
  "settlement_date": "2024-01-09T00:00:00Z",
  "fees": {
    "processing_fee": 2.25,
    "currency": "EUR"
  },
  "captured_at": "2024-01-08T16:20:45Z"
}

Payment Void

Purpose:
Voids authorized payments before capture with audit trail maintenance.

Endpoint Explanation:
This endpoint cancels previously authorized transactions before funds are captured, releasing reserved amounts on customer payment methods. The system validates void eligibility, processes authorization cancellations, and maintains comprehensive audit trails for compliance and reconciliation purposes.

POST /boltpay/payment/void​

curl -X POST https://api.bolttech.com/boltpay/payment/void \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN_987654321",
    "reason": "customer_cancellation",
    "metadata": {
      "void_reason": "Customer requested order cancellation",
      "cancelled_by": "customer_service",
      "cancellation_timestamp": "2024-01-08T17:15:30Z"
    }
  }'
{
  "transaction_id": "TXN_987654321",
  "status": "voided",
  "original_amount": 150.0,
  "currency": "EUR",
  "voided_at": "2024-01-08T17:20:15Z",
  "void_reference": "VOID_123456789"
}

Payment Refund

Purpose:
Processes full or partial refunds with reason tracking and notification handling.

Endpoint Explanation:
This endpoint handles refund processing for captured transactions by calculating refund amounts, processing fund returns, and managing notification workflows. The system supports partial refunds, handles refund reason tracking, and maintains comprehensive audit trails while coordinating with accounting systems for proper financial reconciliation.

POST /boltpay/payment/refund​

curl -X POST https://api.bolttech.com/boltpay/payment/refund \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN_456789012",
    "amount": 199.99,
    "currency": "EUR",
    "reason": "customer_request",
    "refund_type": "full",
    "metadata": {
      "refund_reason": "Customer not satisfied with service",
      "requested_by": "customer_service",
      "customer_id": "CUST_789456",
      "refund_request_id": "REF_REQ_123456"
    }
  }'
{
  "refund_id": "REF_987654321",
  "transaction_id": "TXN_456789012",
  "status": "processing",
  "refund_amount": 199.99,
  "currency": "EUR",
  "estimated_arrival": "2024-01-12T00:00:00Z",
  "refund_method": "original_payment_method",
  "processed_at": "2024-01-08T18:30:45Z"
}

GET /boltpay/payment/{transactionId}​

Purpose:
Retrieves detailed payment transaction information and status.

Endpoint Explanation:
This endpoint provides comprehensive transaction details including current status, payment method information, processing history, fee breakdowns, and related transaction references. The system aggregates data from multiple sources to present complete transaction visibility while maintaining appropriate access controls and data privacy compliance.

curl -X GET https://api.bolttech.com/boltpay/payment/{transactionId} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"
{
  "transaction_id": "TXN_456789012",
  "status": "completed",
  "amount": 199.99,
  "currency": "EUR",
  "payment_method": {
    "type": "card",
    "last_four": "1111",
    "brand": "visa",
    "expiry_month": "12",
    "expiry_year": "2025"
  },
  "customer": {
    "id": "CUST_789456",
    "email": "[email protected]",
    "name": "Maria Silva"
  },
  "order_id": "ORDER_456789123",
  "authorization_code": "AUTH789456",
  "fees": {
    "processing_fee": 2.99,
    "currency": "EUR"
  },
  "risk_score": 15,
  "created_at": "2024-01-08T15:45:30Z",
  "completed_at": "2024-01-08T15:45:35Z",
  "metadata": {
    "contract_id": "CONTRACT_001",
    "product_type": "health_insurance",
    "partner_reference": "PARTNER_REF_123"
  }
}

POST /boltpay/payment/verify​

Purpose:
Verifies payment status and validates transaction integrity.

Endpoint Explanation:
This endpoint performs transaction verification by validating payment status, confirming transaction integrity, and providing real-time payment confirmation. The system cross-references multiple data sources, validates transaction signatures, and provides authoritative payment status information for reconciliation and customer service purposes.

curl -X POST https://api.bolttech.com/boltpay/payment/verify     -H "Authorization: Bearer <token>"     -H "Content-Type: application/json"     -d '{
    "transaction_id": "TXN_456789012",
    "verification_type": "status_check",
    "merchant_reference": "ORDER_456789123",
    "metadata": {
      "verification_reason": "reconciliation",
      "requested_by": "system_cron",
      "verification_timestamp": "2024-01-08T20:00:00Z"
    }
  }'
{
  "transaction_id": "TXN_456789012",
  "verification_status": "verified",
  "payment_status": "completed",
  "amount": 199.99,
  "currency": "EUR",
  "integrity_check": "passed",
  "last_updated": "2024-01-08T15:45:35Z",
  "verification_timestamp": "2024-01-08T20:00:15Z",
  "signature_valid": true
}

POST /boltpay/recurring/create​

Purpose:
Establishes recurring payment schedules for subscription and installment models with automated billing cycles.

Endpoint Explanation:
This endpoint creates comprehensive recurring payment arrangements by setting up automated billing cycles, payment method tokenization, and subscription management workflows. The system handles various billing frequencies, prorated billing scenarios, trial periods, and complex subscription modifications while maintaining PCI compliance through secure payment method storage and processing.

curl -X POST https://api.bolttech.com/boltpay/recurring/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "id": "CUST_789456",
      "email": "[email protected]",
      "name": "Maria Silva",
      "phone": "+351934567890"
    },
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4111111111111111",
        "expiry_month": "12",
        "expiry_year": "2025",
        "cvv": "123",
        "holder_name": "Maria Silva"
      }
    },
    "subscription": {
      "plan_id": "PLAN_MONTHLY_INSURANCE",
      "amount": 29.99,
      "currency": "EUR",
      "billing_frequency": "monthly",
      "billing_day": 15,
      "start_date": "2024-01-15T00:00:00Z",
      "trial_period_days": 0
    },
    "contract_id": "CONTRACT_001",
    "product_name": "Monthly Health Insurance",
    "metadata": {
      "partner_id": "PARTNER_001",
      "product_type": "health_insurance",
      "customer_segment": "premium"
    }
  }'
{
  "subscription_id": "SUB_123456789",
  "status": "active",
  "customer_id": "CUST_789456",
  "payment_method_token": "PM_TOKEN_987654321",
  "next_billing_date": "2024-01-15T00:00:00Z",
  "amount": 29.99,
  "currency": "EUR",
  "billing_frequency": "monthly",
  "created_at": "2024-01-08T21:00:00Z"
}

Recurring Payment Update

Purpose:
Modifies existing recurring payment details including amount and schedule adjustments.

Endpoint Explanation:
This endpoint handles subscription modifications including payment amount changes, billing frequency adjustments, payment method updates, and schedule modifications. The system calculates prorated amounts, handles mid-cycle changes, and maintains billing continuity while preserving subscription history and ensuring proper financial reconciliation.

POST /boltpay/recurring/update​

curl -X POST https://api.bolttech.com/boltpay/recurring/update \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "SUB_123456789",
    "updates": {
      "amount": 34.99,
      "billing_frequency": "monthly",
      "billing_day": 20,
      "payment_method": {
        "type": "card",
        "card": {
          "number": "4111111111111111",
          "expiry_month": "08",
          "expiry_year": "2026",
          "cvv": "456",
          "holder_name": "Maria Silva"
        }
      }
    },
    "proration": {
      "apply_proration": true,
      "proration_date": "2024-01-20T00:00:00Z"
    },
    "metadata": {
      "update_reason": "plan_upgrade",
      "updated_by": "customer",
      "previous_amount": 29.99
    }
  }'
{
  "subscription_id": "SUB_123456789",
  "status": "active",
  "updated_amount": 34.99,
  "currency": "EUR",
  "billing_frequency": "monthly",
  "billing_day": 20,
  "next_billing_date": "2024-02-20T00:00:00Z",
  "proration_amount": 2.5,
  "payment_method_token": "PM_TOKEN_456789123",
  "updated_at": "2024-01-20T10:30:00Z"
}

POST /boltpay/recurring/cancel​

Purpose:
Cancels recurring payment subscriptions with proper notification handling and final billing.

Endpoint Explanation:
This endpoint processes subscription cancellations by stopping future billing cycles, calculating final charges, processing refunds if applicable, and coordinating customer notifications. The system handles immediate and scheduled cancellations while maintaining comprehensive audit trails and ensuring proper financial settlement.

curl -X POST https://api.bolttech.com/boltpay/recurring/cancel \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "SUB_123456789",
    "cancellation": {
      "cancel_at_period_end": true,
      "cancellation_reason": "customer_request",
      "immediate_cancellation": false,
      "refund_unused_time": false
    },
    "metadata": {
      "cancelled_by": "customer",
      "cancellation_date": "2024-01-25T14:30:00Z",
      "customer_feedback": "No longer needed",
      "retention_attempted": true
    }
  }'
{
  "subscription_id": "SUB_123456789",
  "status": "cancelled",
  "cancelled_at": "2024-01-25T14:30:00Z",
  "final_billing_date": "2024-02-20T00:00:00Z",
  "refund_amount": 0.0,
  "currency": "EUR",
  "cancellation_effective_date": "2024-02-20T23:59:59Z",
  "final_invoice_id": "INV_FINAL_789456"
}

Recurring Payment Pause

Purpose:
Temporarily pauses recurring payment schedules without cancellation.

Endpoint Explanation:
This endpoint suspends recurring payments temporarily while preserving subscription relationships and payment methods. The system stops billing cycles, maintains customer data, and provides mechanisms for resuming payments while handling various pause scenarios including voluntary suspensions and temporary payment failures.

POST /boltpay/recurring/pause​

curl -X POST https://api.bolttech.com/boltpay/recurring/pause \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "SUB_123456789",
    "pause_details": {
      "pause_duration": 60,
      "pause_unit": "days",
      "pause_reason": "temporary_financial_difficulty",
      "resume_date": "2024-03-25T00:00:00Z",
      "maintain_benefits": false
    },
    "metadata": {
      "paused_by": "customer",
      "pause_request_date": "2024-01-25T16:00:00Z",
      "customer_communication": "Temporary pause due to job transition"
    }
  }'
{
  "subscription_id": "SUB_123456789",
  "status": "paused",
  "paused_at": "2024-01-25T16:00:00Z",
  "resume_date": "2024-03-25T00:00:00Z",
  "pause_duration": 60,
  "next_billing_date": "2024-03-25T00:00:00Z",
  "benefits_maintained": false,
  "pause_reference": "PAUSE_789456123"
}

POST /boltpay/recurring/resume​

Purpose:
Resumes previously paused recurring payment schedules with billing reconciliation.

Endpoint Explanation:
This endpoint reactivates paused subscriptions by recalculating billing schedules, processing any required catch-up payments, and resuming normal billing cycles. The system handles various resume scenarios including automatic resumption, manual reactivation, and billing adjustments for pause periods.

curl -X POST https://api.bolttech.com/boltpay/recurring/resume     -H "Authorization: Bearer <token>"     -H "Content-Type: application/json"     -d '{
    "subscription_id": "SUB_123456789",
    "resume_details": {
      "resume_immediately": true,
      "catch_up_payments": false,
      "prorate_current_period": true,
      "resume_reason": "financial_situation_improved"
    },
    "billing_adjustments": {
      "skip_missed_periods": true,
      "adjust_next_billing_date": "2024-03-01T00:00:00Z"
    },
    "metadata": {
      "resumed_by": "customer",
      "resume_request_date": "2024-02-28T12:00:00Z",
      "customer_confirmation": "Ready to resume subscription"
    }
  }'
{
  "subscription_id": "SUB_123456789",
  "status": "active",
  "resumed_at": "2024-02-28T12:00:00Z",
  "next_billing_date": "2024-03-01T00:00:00Z",
  "catch_up_amount": 0.0,
  "prorated_amount": 25.99,
  "currency": "EUR",
  "billing_cycle_restored": true,
  "resume_reference": "RESUME_456789123"
}

GET /boltpay/recurring/{subscriptionId}​

Purpose:
Retrieves comprehensive recurring payment subscription details and status information.

Endpoint Explanation:
This endpoint provides complete subscription information including current status, billing history, payment method details, and upcoming payment schedules. The system aggregates data from billing cycles, payment processing records, and customer management systems to present unified subscription visibility.

{
  "subscription_id": "SUB_123456789",
  "status": "active",
  "customer_id": "CUST_789456",
  "plan_id": "PLAN_MONTHLY_INSURANCE",
  "amount": 34.99,
  "currency": "EUR",
  "billing_frequency": "monthly",
  "billing_day": 20,
  "payment_method": {
    "type": "card",
    "last_four": "1111",
    "brand": "visa",
    "expiry_month": "08",
    "expiry_year": "2026"
  },
  "next_billing_date": "2024-03-20T00:00:00Z",
  "created_at": "2024-01-08T21:00:00Z",
  "updated_at": "2024-01-20T10:30:00Z",
  "trial_end_date": null,
  "current_period_start": "2024-02-20T00:00:00Z",
  "current_period_end": "2024-03-20T00:00:00Z",
  "cancel_at_period_end": false,
  "metadata": {
    "partner_id": "PARTNER_001",
    "product_type": "health_insurance",
    "customer_segment": "premium"
  }
}

GET /boltpay/recurring/{subscriptionId}/transactions​

Purpose:
Retrieves complete transaction history for subscription billing cycles.

Endpoint Explanation:
This endpoint provides detailed transaction history for recurring payment subscriptions including successful payments, failed attempts, refunds, and adjustments. The system maintains comprehensive records for financial reconciliation, customer service, and compliance reporting purposes.

{
  "subscription_id": "SUB_123456789",
  "transactions": [
    {
      "transaction_id": "TXN_001234567",
      "status": "completed",
      "amount": 34.99,
      "currency": "EUR",
      "billing_date": "2024-02-20T00:00:00Z",
      "payment_method": "card_1111",
      "invoice_id": "INV_202402_001"
    },
    {
      "transaction_id": "TXN_001234568",
      "status": "completed",
      "amount": 29.99,
      "currency": "EUR",
      "billing_date": "2024-01-20T00:00:00Z",
      "payment_method": "card_1111",
      "invoice_id": "INV_202401_001"
    },
    {
      "transaction_id": "TXN_001234569",
      "status": "failed",
      "amount": 29.99,
      "currency": "EUR",
      "billing_date": "2024-01-15T00:00:00Z",
      "failure_reason": "insufficient_funds",
      "retry_count": 2,
      "next_retry_date": "2024-01-18T00:00:00Z"
    }
  ],
  "total_transactions": 15,
  "successful_payments": 13,
  "failed_payments": 2,
  "total_amount_paid": 449.87,
  "currency": "EUR"
}

POST /boltpay/recurring/charge​

Purpose:
Executes immediate charge on existing recurring payment method outside regular billing cycle.

Endpoint Explanation:
This endpoint processes ad-hoc charges using stored payment methods from active subscriptions. The system handles one-time charges, usage overages, and additional services while maintaining security compliance and providing immediate payment processing results.

curl -X POST https://api.bolttech.com/boltpay/recurring/charge \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "SUB_123456789",
    "charge_details": {
      "amount": 50.00,
      "currency": "EUR",
      "description": "One-time usage overage charge",
      "charge_type": "usage_overage"
    },
    "billing_options": {
      "charge_immediately": true,
      "add_to_next_invoice": false,
      "prorate": false
    },
    "metadata": {
      "charge_reason": "additional_services",
      "service_period": "2024-02-01_to_2024-02-28",
      "usage_units": 25,
      "overage_rate": 2.00
    }
  }'
{
  "charge_id": "CHG_789456123",
  "subscription_id": "SUB_123456789",
  "transaction_id": "TXN_987654321",
  "status": "completed",
  "amount": 50.0,
  "currency": "EUR",
  "charged_at": "2024-02-28T18:45:00Z",
  "invoice_id": "INV_ADHOC_001",
  "payment_method": "card_1111"
}

Recurring Payment Retry

Purpose:
Retries failed recurring payments with updated parameters and smart retry logic.

Endpoint Explanation:
This endpoint handles retry processing for failed recurring payments using intelligent retry algorithms, dunning management, and customer communication workflows. The system applies configurable retry schedules, updates payment methods when necessary, and maintains customer relationships through automated communication sequences.

POST /boltpay/recurring/retry​

curl -X POST https://api.bolttech.com/boltpay/recurring/retry \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "SUB_123456789",
    "transaction_id": "TXN_001234569",
    "retry_details": {
      "retry_immediately": true,
      "update_payment_method": false,
      "retry_reason": "customer_requested",
      "max_retry_attempts": 3
    },
    "payment_updates": {
      "amount": 29.99,
      "currency": "EUR",
      "use_backup_payment_method": false
    },
    "metadata": {
      "retry_initiated_by": "customer_service",
      "original_failure_reason": "insufficient_funds",
      "customer_contacted": true,
      "funds_confirmed": true
    }
  }'
{
  "retry_id": "RETRY_456789123",
  "subscription_id": "SUB_123456789",
  "original_transaction_id": "TXN_001234569",
  "new_transaction_id": "TXN_987654321",
  "status": "completed",
  "amount": 29.99,
  "currency": "EUR",
  "retry_attempt": 3,
  "processed_at": "2024-03-01T09:15:00Z",
  "payment_method": "card_1111"
}

Payment Success Callback

Purpose:
Handles successful payment notifications with automated business process triggers.

Endpoint Explanation:
This webhook endpoint receives real-time notifications for successful payment transactions, triggering downstream business processes such as contract activation, service provisioning, and customer communications. The system validates webhook signatures, processes business logic, and maintains event logs for audit and troubleshooting purposes.

POST /boltpay/callback/payment/success​

curl -X POST https://api.bolttech.com/boltpay/callback/payment/success     -H "Content-Type: application/json"     -d '{
    "event_type": "payment.success",
    "transaction_id": "TXN_987654321",
    "order_id": "ORDER_456789123",
    "amount": 199.99,
    "currency": "EUR",
    "status": "completed",
    "payment_method": "card",
    "customer_id": "CUST_789456",
    "timestamp": "2024-03-01T10:30:45Z",
    "signature": "sha256=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "metadata": {
      "contract_id": "CONTRACT_001",
      "product_type": "health_insurance",
      "partner_reference": "PARTNER_REF_123"
    }
  }'
{
  "received": true,
  "processed_at": "2024-03-01T10:30:47Z",
  "webhook_id": "WH_SUCCESS_123456",
  "actions_triggered": [
    "contract_activation",
    "customer_notification",
    "service_provisioning"
  ]
}

POST /boltpay/callback/payment/failure​

Purpose:
Processes failed payment notifications with retry logic and customer communication.

Endpoint Explanation:
This webhook handles payment failure notifications by initiating retry workflows, customer communication sequences, and business process adjustments. The system analyzes failure reasons, applies appropriate retry strategies, and coordinates with customer service systems for resolution.

{
  "event_type": "payment.failure",
  "transaction_id": "TXN_001234569",
  "order_id": "ORDER_456789124",
  "amount": 29.99,
  "currency": "EUR",
  "status": "failed",
  "failure_code": "insufficient_funds",
  "failure_message": "The payment method has insufficient funds",
  "payment_method": "card",
  "customer_id": "CUST_789456",
  "timestamp": "2024-03-01T11:15:30Z",
  "retry_count": 1,
  "signature": "sha256=z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
  "metadata": {
    "contract_id": "CONTRACT_002",
    "product_type": "device_protection",
    "partner_reference": "PARTNER_REF_124"
  }
}
{
  "received": true,
  "processed_at": "2024-03-01T11:15:32Z",
  "webhook_id": "WH_FAILURE_123457",
  "actions_triggered": [
    "retry_scheduled",
    "customer_notification",
    "dunning_workflow_initiated"
  ],
  "retry_schedule": {
    "next_retry": "2024-03-04T11:15:30Z",
    "max_retries": 3,
    "retry_interval": "72_hours"
  }
}

GET /boltpay/healthcheck​

Purpose:
Checks payment gateway system health and connectivity status.

Endpoint Explanation:
This endpoint provides real-time system health monitoring for the payment infrastructure including payment processor connectivity, database status, queue health, and service availability. The system performs comprehensive health checks and provides detailed status information for operational monitoring and alerting.

{
  "status": "healthy",
  "timestamp": "2024-03-01T12:00:00Z",
  "version": "v2.1.3",
  "services": {
    "payment_processor": {
      "status": "operational",
      "response_time": "45ms"
    },
    "database": {
      "status": "operational",
      "response_time": "12ms"
    },
    "queue_system": {
      "status": "operational",
      "pending_jobs": 23
    },
    "external_providers": {
      "stripe": "operational",
      "adyen": "operational",
      "paypal": "maintenance"
    }
  },
  "uptime": "99.98%",
  "last_restart": "2024-02-28T06:30:00Z"
}

POST /rental/payments/{paymentOrderId}/paid​

Purpose:
Marks rental payment as successful with contract activation triggers and equipment tracking integration.

Endpoint Explanation:
This endpoint records successful rental payment completion by updating payment status, triggering contract activation workflows, and coordinating with equipment delivery systems. The system handles rental-specific scenarios including security deposits, monthly payments, damage assessments, and return processing while maintaining integration with the broader contract management and logistics systems.

# To be included
{
  // To be included
}

POST /rental/payments/{paymentOrderId}/failed​

Purpose:
Records failed rental payment attempts with retry scheduling and customer notification workflows.

Endpoint Explanation:
This endpoint handles failed rental payment processing by logging failure details, initiating retry workflows, and coordinating customer communication sequences. The system applies rental-specific dunning management, handles equipment hold procedures, and maintains rental contract status while working toward payment resolution.

# To be included
{
  // To be included
}