Create Plan

​Information

Creates a new subscription plan for the merchant. The plan starts in pending_card_linking status and returns a payment_link_url that must be opened by the customer to enter their card details once. The first cycle is charged as part of the card linking flow; subsequent cycles are auto-charged by SingaPay on the configured schedule.

---

​Request Details

​Headers Structure

​Body Structure

​Request Example — Amount-Only Plan

{
    "name": "Premium Monthly",
    "subscription_id": "PLAN-20260420-001",
    "merchant_reff_no": "SUB-CUST-ACME-001",
    "amount": 150000,
    "currency": "IDR",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "08123456789",
    "customer_id": "CUST-001",
    "account_id": "01K5G4FZZ18DMK0M5QTR8Y9QY9",
    "schedule": {
        "interval": 1,
        "interval_unit": "month",
        "total_interval": 12,
        "start_time": "2026-05-01"
    },
    "payment_type": "credit_card",
    "return_url": "https://merchant.com/callback",
    "retry_policy": {
        "max_attempts": 3,
        "interval_days": 3,
        "failed_payment_action": "stop_plan"
    },
    "allow_user_notification": true,
    "metadata": {
        "description": "Premium monthly subscription"
    }
}

​Request Example — Itemized Plan

{
    "name": "Team Plan",
    "merchant_reff_no": "SUB-CUST-ACME-TEAM",
    "items": [
        {
            "item_name": "Premium Seat",
            "item_type": "service",
            "quantity": 3,
            "unit_price": 75000
        },
        {
            "item_name": "Premium Support",
            "item_type": "service",
            "quantity": 1,
            "unit_price": 50000
        }
    ],
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "08123456789",
    "account_id": "01K5G4FZZ18DMK0M5QTR8Y9QY9",
    "schedule": {
        "interval": 1,
        "interval_unit": "month",
        "start_time": "2026-05-01"
    },
    "payment_type": "credit_card",
    "return_url": "https://merchant.com/callback"
}

cURL Example:

curl -X POST "https://your-domain.com/api/v2.0/recurring/plans" \
  -H "X-PARTNER-ID: {api_key}" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Monthly",
    "merchant_reff_no": "SUB-CUST-ACME-001",
    "amount": 150000,
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "08123456789",
    "account_id": "01K5G4FZZ18DMK0M5QTR8Y9QY9",
    "schedule": {
        "interval": 1,
        "interval_unit": "month",
        "start_time": "2026-05-01"
    },
    "payment_type": "credit_card",
    "return_url": "https://merchant.com/callback"
  }'

​Response Details

​Response Structure

​Response Example — Success (HTTP 201)

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "id": "01JAB3CD4E5F6G7H8J9K0M1N2",
        "name": "Premium Monthly",
        "amount": "150000",
        "currency": "IDR",
        "created_at": "2026-04-20T10:00:00+07:00",
        "schedule": {
            "interval": 1,
            "interval_unit": "month",
            "current_interval": 0,
            "total_interval": 12,
            "start_time": "2026-05-01T00:00:00+07:00",
            "previous_payment_at": null,
            "next_payment_at": "2026-05-01T00:00:00+07:00"
        },
        "status": "pending_card_linking",
        "payment_type": "credit_card",
        "retry_policy": {
            "max_attempts": 3,
            "interval_days": 3,
            "failed_payment_action": "stop_plan"
        },
        "metadata": {
            "description": "Premium monthly subscription",
            "extra": {
                "payment_type": "credit_card",
                "return_url": "https://merchant.com/callback",
                "api_created": true
            }
        },
        "subscription_id": "PLAN-20260420-001",
        "merchant_reff_no": "SUB-CUST-ACME-001",
        "payment_link_url": "https://pay.singapay.id/link/abc123",
        "parent_plan_id": null,
        "created_from": null
    }
}

​Error Response — Validation (HTTP 422)

{
    "message": "The amount field prohibits items from being present.",
    "errors": {
        "amount": [
            "The amount field prohibits items from being present."
        ],
        "items": [
            "The items field prohibits amount from being present."
        ]
    }
}

​Error Response — Account Not Found (HTTP 404)

{
    "response_code": "SP020",
    "response_message": "Merchant Account Not Found",
    "data": {}
}

---

​Post-Create Flow

1. Redirect the customer: Open payment_link_url in the customer’s browser. This is a one-time flow that collects card details and performs 3DS if required.
2. Initial charge: After successful card linking, the first cycle is charged immediately (if charge_immediately: true or start_time is today) or deferred to schedule.start_time.
3. Plan activates: Plan status transitions to active once the first charge succeeds.
4. Auto-charging: Subsequent cycles are charged automatically on the schedule using the tokenized card — no customer action required.
5. Webhooks: Your configured subscription_cycle_notif_url receives a subscription.cycle.payment_success or subscription.cycle.payment_failed notification for every cycle attempt. See the Subscription Cycle webhook reference.

---

​Important Notes

• Card-Only Channel: Subscriptions currently run on credit card recurring. payment_type must be credit_card (or omitted to inherit the account default).
• Card Minimum: The per-cycle charge must clear the card channel minimum. For itemized plans, the minimum is checked against the derived total (Σ quantity × unit_price).
• Schedule Start: schedule.start_time must be today or in the future.
• Plan ID Format: The plan id is a 26-character ULID. Use it on all subsequent GET, PATCH, and Cancel requests.
• Customer Notifications: Customer email / phone are used for payment notifications and invoice delivery.