Orders

This page describes how to work with orders in the Two-Coin payment system. Orders represent cryptocurrency purchase transactions with their entire lifecycle.

Order Lifecycle

An order goes through several states during its lifecycle:

Created

Order is initially created with an offer selected

Payment Pending

Waiting for customer to complete payment

Payment Received

Payment has been received but not yet processed

Final Status

Completed

Failed

Expired

Creating an Order

To create an order, make a POST request to the /api/on_ramp/orders endpoint with the required information:

POST https://api.dev2coin.space/api/on_ramp/orders

{
  "provider_code": "changelly",
  "from_currency": 35,
  "from_amount": "100.00",
  "to_currency": 15,
  "wallet_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "payment_method": "card",
  "country_code": "US",
  "state_code": "CA",
  "external_user_id": "user_12345",
  "external_order_id": "order_67890"
}

Required fields:

• provider_code - Provider from offers response
• from_currency / to_currency - Integer IDs (35=USD, 15=BTC)
• from_amount - Amount as string
• wallet_address - Validated cryptocurrency address
• payment_method - Payment method code (string)
• country_code - Two-letter country code
• external_user_id - Your internal user ID
• external_order_id - Your internal order ID

Conditionally required:

• state_code - Required if the country has states in GET /api/dict/countries response

Optional fields:

• ip - User IP address
• user_agent - Browser user agent
• extras - Additional provider-specific data

The response includes order details and a redirect URL to send the customer to complete payment:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "redirect_url": "https://provider.changelly.com/payment?orderId=abc123",
  "from_currency": 35,
  "from_amount": "100.00",
  "to_currency": 15,
  "to_amount": "0.00245",
  "wallet_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "payment_method": "card",
  "country_code": "US",
  "external_user_id": "user_12345",
  "external_order_id": "order_67890",
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "extras": {}
}

Important: Use the redirect_url to redirect the customer to complete the payment with the provider.

Retrieving Order Status

Retrieve the current status of an order by making a GET request:

GET https://api.dev2coin.space/api/on_ramp/orders/changelly?code=550e8400-e29b-41d4-a716-446655440000

Required query parameters:

code - The order id from the creation response

Order Status Values

created

Initial state when order is created

pending

Waiting for customer to complete payment

hold

Payment is on hold for verification

processing

Payment received, cryptocurrency purchase pending

complete

Order successfully fulfilled

failed

Order failed (check failure_reason field)

expired

Order expired due to inactivity

refunded

Payment has been refunded to customer

Webhook Notifications

You'll receive real-time updates about order status changes through webhooks. It's recommended to implement webhook verification and database storage of both id (provider's order code) and external_order_id (yours) for proper tracking.

See the Webhooks section for more details on handling status updates.

Best Practices

✓ Store both id (from provider) and external_order_id (yours)
✓ Always use integer currency IDs from the currency dictionary
✓ Validate wallet addresses before creating orders
✓ Implement webhook verification to ensure authenticity

Support

If you encounter any issues or have questions not addressed in this documentation, please contact our support team on Telegram at https://t.me/cs_2coin (@cs_2coin).