Skip to main content
POST
/
api
/
orders
/
initialize
curl -X POST https://api.gatepass.io/api/orders/initialize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "clx1234567890",
    "tierId": "clx0987654321",
    "quantity": 2,
    "paymentMethod": "FIAT",
    "gateway": "flutterwave",
    "customerEmail": "[email protected]",
    "customerName": "John Doe"
  }'

{
  "ok": true,
  "orderId": "clx1234567890abcdef",
  "reference": "GP-clx1234567890-1234567890-a1b2c3d4",
  "checkoutUrl": "https://checkout.flutterwave.com/v3/hosted/pay/abc123"
}
This endpoint creates a new order for purchasing event tickets. It supports both crypto and fiat payment methods, with integration for Flutterwave, Paystack, and M-Pesa payment gateways.

​
Authentication

​
Authorization
string
required
Bearer token for authentication

​
Request Body

​
eventId
string
required
The ID of the event for which tickets are being purchased
​
tierId
string
required
The ID of the ticket tier to purchase
​
quantity
number
required
Number of tickets to purchase (must be at least 1)
​
paymentMethod
string
required
Payment method type: CRYPTO or FIAT
​
gateway
string
Payment gateway for fiat payments: paystack, flutterwave, or mpesa
​
customerEmail
string
Customer email address (defaults to authenticated user’s email)
​
customerName
string
Customer name (defaults to authenticated user’s name)

​
Response

​
ok
boolean
Indicates if the order was successfully created
​
orderId
string
Unique identifier for the created order
​
reference
string
Payment reference for tracking the transaction
​
checkoutUrl
string
Payment gateway checkout URL (for Flutterwave)

​
Order Model

The Order object contains the following fields:
  • id: Unique order identifier (CUID)
  • totalAmount: Total order amount including platform fees (2.5%)
  • quantity: Number of tickets purchased
  • currency: Payment currency (e.g., NGN, USD, ETH)
  • paymentMethod: CRYPTO or FIAT
  • paymentStatus: PENDING, COMPLETED, or FAILED
  • customerEmail: Customer’s email address
  • customerName: Customer’s name
  • userId: ID of the purchasing user
  • eventId: ID of the event
  • createdAt: Order creation timestamp
  • updatedAt: Last update timestamp
curl -X POST https://api.gatepass.io/api/orders/initialize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "clx1234567890",
    "tierId": "clx0987654321",
    "quantity": 2,
    "paymentMethod": "FIAT",
    "gateway": "flutterwave",
    "customerEmail": "[email protected]",
    "customerName": "John Doe"
  }'

{
  "ok": true,
  "orderId": "clx1234567890abcdef",
  "reference": "GP-clx1234567890-1234567890-a1b2c3d4",
  "checkoutUrl": "https://checkout.flutterwave.com/v3/hosted/pay/abc123"
}

​
Platform Fees

GatePass applies a 2.5% platform fee on top of the ticket price. The total amount is calculated as: 
totalAmount = (ticketPrice × quantity) × 1.025

​
Payment Flow

  1. Order Initialization: Create an order with this endpoint
  2. Payment Processing: User completes payment through the gateway
  3. Webhook Verification: Payment gateway sends webhook to GatePass
  4. Order Confirmation: Order status updated to COMPLETED
  5. Ticket Minting: NFT tickets minted on blockchain (if applicable)
  6. Notification: User receives confirmation notification
For Flutterwave payments, redirect users to the checkoutUrl returned in the response. The user will be redirected back to your application after payment.

Build docs developers (and LLMs) love

Get started for freeTalk to us