Orders - Spell Docs

Orders are a core function of Spell, referring to operations related to initiating payments. Registered users can perform the following actions via the web interface or API requests:

Create an order
Query one or more orders
Cancel an order
Delete an order

Note: Once an order is created, its information cannot be modified.

Order Types

Currently, Spell offers two types of orders: Pre-configured Invoices and Custom Transfers (not yet available).

The following fields are unavailable when an order is created via the web interface:

Group number group_no (API only)
Order number order_no (automatically generated)
Notify URL notify_url (API only)
Return URL return_url (API only)
Timeout timeout (defaults to 30 minutes)

Pre-configured Invoice

A pre-configured invoice is the best payment order type for a good user experience and can be used to pay for any goods or services.

The invoice information is pre-configured by the recipient (merchant/individual). After creation, a unique payment link is generated, such as: spell.im/pay/[orderId]. The payer (user) visits the payment page, clicks the pay button within the link, and a browser wallet extension is called to complete the payment. After payment is completed, a POST request is made to the notify URL, and the recipient is redirected to the return URL if the recipient has configured it.

An invoice can only be paid once. After payment is completed, the order’s life cycle ends.

Custom Transfer

A custom transfer is similar to a regular transfer and is suitable for scenarios like donations.

The recipient (merchant/individual) only specifies the recipient address (blockchain network and currency are optional). After creation, a unique link is generated, such as: spell.im/pay/[orderId]. The payer (user) visits the payment page, selects the blockchain network (if not specified) and currency (if not specified), enters the amount, and then clicks the transfer button. This calls a browser wallet extension to complete the transfer.

A custom transfer order can be paid repeatedly.

Order Confirmation Methods

Due to the decentralized nature of blockchain transfers, they do not rely on any centralized institution. Therefore, Spell uses specific technical capabilities to confirm the payment status of orders:

ID Confirmation: The order ID is compiled as additional data and added to the blockchain transaction details. After the payment is completed, the payment is confirmed by matching the order ID.
Tail Confirmation: A 4 digit tail amount is added to the order amount. When the user initiates a blockchain transfer, the order amount + tail is used to locate and confirm the payment.

Order Status

Order status is the only parameter in the order information that can be changed after creation. It indicates the stage the order is in during its lifecycle:

Pending Payment (status code 0): The order has been successfully created and is waiting for the user to complete the blockchain transfer.
Payment Successful (status code 1): A transfer matching the order information is detected on the blockchain, and the order status changes to “Payment Successful”.
Overdue (status code 2): The user did not complete the blockchain transfer within the specified time after the order was created, and the order automatically changes to “Overdue”.
Canceled (status code 3): The order is canceled by the merchant/individual after creation and before it times out, and the order status changes to “Canceled”.

Note: Canceled and overdue orders cannot be paid. After an order is canceled or timed out, its status will no longer be changed, even if the user manually completes a qualifying blockchain transfer.