Pre-Orders QR Integration - API Documentation

Introduction

This document describes the TotalCoin API endpoints for managing pre-orders with QR code generation and processing.

Authentication

API access control is done through OAuth 2.0 with Bearer Tokens.

Endpoint

POST api/auth/login

Request

{
    "username": "",
    "password": ""
}

Field	Type	Description	Required
username	String	Username	Yes
password	String	Password	Yes

Response (HTTP 200)

{
    "token": "",
    "expires_in": 3600
}

Field	Type	Description
token	String	Authentication token
expires_in	Number	Token validity in seconds

Possible Errors

Code	Description
401	Invalid or non-existent credentials
403	No permissions to access the API

Credentials: Must be requested from the technical department.

Create Pre-Order

Creates a new pre-order and generates a QR code for payment.

Endpoint

POST api/pre-orders

Request

{
    "amount": 100.00,
    "currency": "USD",
    "description": "Pre-order for product X",
    "expiration_date": "2024-04-26T23:59:59Z",
    "customer": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
    }
}

Field	Type	Description	Required
amount	Number	Order amount	Yes
currency	String	Currency code (USD, EUR, etc.)	Yes
description	String	Order description	Yes
expiration_date	String	ISO 8601 date when the pre-order expires	Yes
customer	Object	Customer information	Yes
customer.name	String	Customer's full name	Yes
customer.email	String	Customer's email address	Yes
customer.phone	String	Customer's phone number	Yes

Response (HTTP 201)

{
    "id": "pre_order_123",
    "status": "pending",
    "qr_code": "data:image/png;base64,...",
    "payment_url": "https://totalcoin.com/pay/pre_order_123",
    "created_at": "2024-03-26T10:00:00Z",
    "expires_at": "2024-04-26T23:59:59Z"
}

Field	Type	Description
id	String	Unique identifier for the pre-order
status	String	Current status of the pre-order
qr_code	String	Base64 encoded QR code image
payment_url	String	URL for payment processing
created_at	String	Creation timestamp
expires_at	String	Expiration timestamp

Possible Errors

Code	Description
400	Invalid request parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions

Get Pre-Order Status

Retrieves the current status of a pre-order.

Endpoint

GET api/pre-orders/{id}

Response (HTTP 200)

{
    "id": "pre_order_123",
    "status": "paid",
    "amount": 100.00,
    "currency": "USD",
    "description": "Pre-order for product X",
    "customer": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
    },
    "payment_details": {
        "transaction_id": "txn_456",
        "payment_method": "qr",
        "paid_at": "2024-03-26T11:00:00Z"
    },
    "created_at": "2024-03-26T10:00:00Z",
    "expires_at": "2024-04-26T23:59:59Z"
}

Field	Type	Description
id	String	Unique identifier for the pre-order
status	String	Current status (pending, paid, expired, cancelled)
amount	Number	Order amount
currency	String	Currency code
description	String	Order description
customer	Object	Customer information
payment_details	Object	Payment information (only present if paid)
created_at	String	Creation timestamp
expires_at	String	Expiration timestamp

Possible Errors

Code	Description
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Pre-order not found

Webhook Notifications

Webhooks are sent to notify about status changes in pre-orders.

Event Types

Event	Description
pre_order.paid	Pre-order has been paid
pre_order.expired	Pre-order has expired
pre_order.cancelled	Pre-order has been cancelled

Webhook Payload

{
    "event": "pre_order.paid",
    "data": {
        "id": "pre_order_123",
        "status": "paid",
        "amount": 100.00,
        "currency": "USD",
        "payment_details": {
            "transaction_id": "txn_456",
            "payment_method": "qr",
            "paid_at": "2024-03-26T11:00:00Z"
        }
    },
    "timestamp": "2024-03-26T11:00:00Z"
}

Webhook Configuration: Contact the technical department to set up webhook endpoints and receive the necessary credentials.