Skip to main content

​
Overview

Prepaid Plans allow users to purchase trip packages in advance with discounts or special benefits. Plans can include a specific number of trips, percentage discounts, or fixed amount discounts.

​
List Prepaid Plans

Retrieve a paginated list of prepaid plans with optional filtering.
​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"10"
Number of items per page
​
currency
string
Filter by currency code (e.g., “CUP”, “USD”)
​
isActive
boolean
Filter by active status (“true” or “false”)
​
search
string
Search by plan name
curl -X GET "https://api.rodando.com/prepaid-plans?page=1&limit=10&isActive=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "ee0e8400-e29b-41d4-a716-446655440000",
      "name": "Pack 10 viajes -10%",
      "description": "Incluye 10 viajes con 10% de descuento",
      "tripsIncluded": 10,
      "discountPct": "10.00",
      "fixedDiscountAmount": null,
      "expiresInDays": 90,
      "price": "100.00",
      "currency": "CUP",
      "isActive": true,
      "createdAt": "2026-03-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 5
  }
}

​
Get Plan Details

Retrieve detailed information about a specific prepaid plan.
​
id
string
required
Prepaid plan UUID
curl -X GET "https://api.rodando.com/prepaid-plans/ee0e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "id": "ee0e8400-e29b-41d4-a716-446655440000",
    "name": "Pack 10 viajes -10%",
    "description": "Incluye 10 viajes con 10% de descuento",
    "tripsIncluded": 10,
    "discountPct": "10.00",
    "fixedDiscountAmount": null,
    "expiresInDays": 90,
    "price": "100.00",
    "currency": "CUP",
    "isActive": true,
    "planFeatures": {
      "tier": "standard",
      "perks": ["priority-support"]
    },
    "createdAt": "2026-03-01T00:00:00.000Z",
    "updatedAt": "2026-03-01T00:00:00.000Z"
  }
}

​
Create Prepaid Plan

Create a new prepaid plan offering.
​
name
string
required
Plan name (e.g., “Pack 10 viajes -10%”)
​
description
string
Detailed plan description
​
tripsIncluded
number
Number of trips included in the plan (null if not applicable)
​
discountPct
string
Percentage discount (0-100) as decimal string (e.g., “10.00”)
​
fixedDiscountAmount
string
Fixed discount amount in currency as decimal string
​
expiresInDays
number
Number of days until plan expires (1-3650)
​
price
string
required
Plan price as decimal string (e.g., “100.00”)
​
currency
string
required
ISO 4217 currency code (e.g., “CUP”, “USD”)
​
isActive
boolean
default:"true"
Whether the plan is available for purchase
​
planFeatures
object
Additional plan features and metadata
curl -X POST "https://api.rodando.com/prepaid-plans" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pack 10 viajes -10%",
    "description": "Incluye 10 viajes con 10% de descuento",
    "tripsIncluded": 10,
    "discountPct": "10.00",
    "expiresInDays": 90,
    "price": "100.00",
    "currency": "CUP",
    "isActive": true,
    "planFeatures": {
      "tier": "standard",
      "perks": ["priority-support"]
    }
  }'

{
  "success": true,
  "data": {
    "id": "ee0e8400-e29b-41d4-a716-446655440000",
    "name": "Pack 10 viajes -10%",
    "description": "Incluye 10 viajes con 10% de descuento",
    "tripsIncluded": 10,
    "discountPct": "10.00",
    "fixedDiscountAmount": null,
    "expiresInDays": 90,
    "price": "100.00",
    "currency": "CUP",
    "isActive": true,
    "planFeatures": {
      "tier": "standard",
      "perks": ["priority-support"]
    },
    "createdAt": "2026-03-09T10:00:00.000Z",
    "updatedAt": "2026-03-09T10:00:00.000Z"
  }
}

​
Update Prepaid Plan

Update an existing prepaid plan’s details.
​
id
string
required
Prepaid plan UUID
​
name
string
Updated plan name
​
description
string
Updated description
​
price
string
Updated price
​
isActive
boolean
Updated active status
curl -X PATCH "https://api.rodando.com/prepaid-plans/ee0e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": "95.00",
    "description": "Incluye 10 viajes con 10% de descuento - Oferta especial"
  }'

​
Toggle Plan Active Status

Activate or deactivate a prepaid plan.
​
id
string
required
Prepaid plan UUID
​
value
boolean
required
New active status (true or false)
curl -X PATCH "https://api.rodando.com/prepaid-plans/ee0e8400-e29b-41d4-a716-446655440000/active/false" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "id": "ee0e8400-e29b-41d4-a716-446655440000",
    "isActive": false,
    "updatedAt": "2026-03-09T10:30:00.000Z"
  }
}

​
Purchase Plan with Cash

Purchase a prepaid plan using cash at a collection point. This operation is idempotent when using the Idempotency-Key header.
​
planId
string
required
UUID of the plan to purchase
​
buyerUserId
string
required
UUID of the user making the purchase (driver or passenger)
​
collectionPointId
string
required
UUID of the cash collection point where payment is made
​
collectedByUserId
string
required
UUID of the staff member receiving the payment
​
Idempotency-Key
string
Optional key to prevent duplicate purchases
curl -X POST "https://api.rodando.com/prepaid-plans/purchase" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-2026-03-09-user-770e8400" \
  -d '{
    "planId": "ee0e8400-e29b-41d4-a716-446655440000",
    "buyerUserId": "770e8400-e29b-41d4-a716-446655440000",
    "collectionPointId": "bb0e8400-e29b-41d4-a716-446655440000",
    "collectedByUserId": "990e8400-e29b-41d4-a716-446655440000"
  }'

{
  "success": true,
  "data": {
    "userPlanId": "ff0e8400-e29b-41d4-a716-446655440000",
    "planId": "ee0e8400-e29b-41d4-a716-446655440000",
    "userId": "770e8400-e29b-41d4-a716-446655440000",
    "tripsRemaining": 10,
    "activatedAt": "2026-03-09T10:00:00.000Z",
    "expiresAt": "2026-06-07T10:00:00.000Z",
    "status": "ACTIVE"
  }
}

​
Purchase Plan with Wallet

Purchase a prepaid plan using the user’s driver wallet balance. This operation is idempotent when using the Idempotency-Key header.
​
planId
string
required
UUID of the plan to purchase
​
buyerUserId
string
required
UUID of the user making the purchase (must have a driver wallet)
​
note
string
Optional note or observation about the purchase
​
Idempotency-Key
string
Optional key to prevent duplicate purchases
curl -X POST "https://api.rodando.com/prepaid-plans/purchase-wallet" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-wallet-2026-03-09-user-880e8400" \
  -d '{
    "planId": "ee0e8400-e29b-41d4-a716-446655440000",
    "buyerUserId": "880e8400-e29b-41d4-a716-446655440000",
    "note": "Monthly plan renewal"
  }'

{
  "success": true,
  "data": {
    "userPlanId": "ff0e8400-e29b-41d4-a716-446655440000",
    "planId": "ee0e8400-e29b-41d4-a716-446655440000",
    "userId": "880e8400-e29b-41d4-a716-446655440000",
    "tripsRemaining": 10,
    "activatedAt": "2026-03-09T10:00:00.000Z",
    "expiresAt": "2026-06-07T10:00:00.000Z",
    "status": "ACTIVE",
    "walletTransactionId": "gg0e8400-e29b-41d4-a716-446655440000"
  }
}

​
Get User’s Active Plan

Retrieve the best active prepaid plan for a specific user.
​
userId
string
required
UUID of the user
curl -X GET "https://api.rodando.com/prepaid-plans/users/770e8400-e29b-41d4-a716-446655440000/active" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "userPlanId": "ff0e8400-e29b-41d4-a716-446655440000",
    "planId": "ee0e8400-e29b-41d4-a716-446655440000",
    "planName": "Pack 10 viajes -10%",
    "tripsRemaining": 7,
    "discountPct": "10.00",
    "activatedAt": "2026-03-09T10:00:00.000Z",
    "expiresAt": "2026-06-07T10:00:00.000Z",
    "status": "ACTIVE"
  }
}

​
List User’s Active Plans

Retrieve all active prepaid plans for a specific user, ordered by priority.
​
userId
string
required
UUID of the user
curl -X GET "https://api.rodando.com/prepaid-plans/users/770e8400-e29b-41d4-a716-446655440000/actives" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "userPlanId": "ff0e8400-e29b-41d4-a716-446655440000",
      "planId": "ee0e8400-e29b-41d4-a716-446655440000",
      "planName": "Pack 10 viajes -10%",
      "tripsRemaining": 7,
      "discountPct": "10.00",
      "activatedAt": "2026-03-09T10:00:00.000Z",
      "expiresAt": "2026-06-07T10:00:00.000Z",
      "status": "ACTIVE"
    },
    {
      "userPlanId": "gg0e8400-e29b-41d4-a716-446655440000",
      "planId": "hh0e8400-e29b-41d4-a716-446655440000",
      "planName": "Pack 5 viajes -5%",
      "tripsRemaining": 3,
      "discountPct": "5.00",
      "activatedAt": "2026-03-01T10:00:00.000Z",
      "expiresAt": "2026-05-30T10:00:00.000Z",
      "status": "ACTIVE"
    }
  ]
}

​
Delete Prepaid Plan

Permanently delete a prepaid plan. This is a hard delete operation.
​
id
string
required
Prepaid plan UUID
curl -X DELETE "https://api.rodando.com/prepaid-plans/ee0e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": null
}

​
Plan Features

Prepaid plans support two types of discounts:

​
Percentage Discount

Applies a percentage reduction to trip fares: 
{
  "discountPct": "10.00"
}
A 10% discount on a 100 CUP trip = 90 CUP charged.

​
Fixed Amount Discount

Applies a fixed currency amount reduction: 
{
  "fixedDiscountAmount": "15.00"
}
A 15 CUP discount on a 100 CUP trip = 85 CUP charged.
Plans can have either percentage discount or fixed amount discount, not both. If both are provided, the system will use the one that provides the greater benefit to the user.

​
Plan Status Lifecycle

  1. ACTIVE: Plan is purchased and can be used for trips
  2. EXPIRED: Plan has passed its expiration date
  3. DEPLETED: All included trips have been used (if applicable)
  4. CANCELLED: Plan was cancelled before completion

Build docs developers (and LLMs) love

Get started for freeTalk to us