Integration Guide

This guide explains how to integrate MiraclePay into your application to accept cryptocurrency payments. The External Payments API allows you to create payment requests programmatically and redirect customers to a hosted checkout page.

Contents:

• Prerequisites
  • API Credentials
  • Supported Blockchains
  • Get Active Blockchains
  • Base URLs
• External Payments API
  • Authentication
  • Create Payment Prompt
  • Get Payment Status
  • Error Responses
  • Integration Examples
  • Best Practices
  • Allowed Redirect Domains
• Redirect to Checkout
  • Checkout URL Structure
  • Redirect Methods
  • Checkout Flow
  • Post-Payment Handling
  • Payment Expiration
• Checking Payment Status
  • Payment Status Values
  • Polling for Status
  • Polling Implementation
  • Background Job Pattern
  • Status Transition Diagram
  • Best Practices

Quick Start

1. Get your credentials (Client ID and API Key) from the MiraclePay Dashboard

2. Create a payment prompt via POST /external/payments/prompt

3. Redirect your customer to the returned checkoutUrl

4. Poll for status via GET /external/payments/prompt/:id

# Create a payment
curl -X POST https://api.miraclecash.info/external/payments/prompt \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'your_client_id:your_api_key' | base64)" \
  -d '{
    "amount": 50.00,
    "blockchainIds": ["eth"],
    "payer": "customer"
  }'

# Response contains checkoutUrl - redirect your customer there