Create a Subscription

Localpayment enables merchants to set up recurring payment subscriptions using credit and debit cards, supporting both fixed plans and custom billing scenarios across multiple countries. This guide outlines the process for creating a subscription through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes.

Before You Begin

Ensure you have:

API Credentials

Valid API credentials and access token for authentication.

Account Setup

Proper account setup for your target country and business verification.

Country Requirements

Understanding of country-specific requirements and local regulations.

Step 1: Create a Subscription

To create a new subscription, you'll need to send a POST request to the Create a Subscription endpoint.

Key Request Parameters

The request requires several key parameters depending on whether you're creating a fixed plan subscription or a custom subscription:

Parameter	Description	Required
`externalId`	Your unique reference for the subscription	✅
`merchant`	Merchant/business details	✅
`country`	Country code where the subscription will be processed	✅
`currency`	Currency code for the subscription	✅
`paymentMethod`	Payment method configuration	✅
`planId`	ID of a predefined subscription plan (for fixed plans)	❌
`autoRecurring`	Billing frequency (required for scheduled subscriptions)	Conditional
`amount`	Subscription amount (required if no planId)	Conditional

Subscription Types

Fixed Plan Subscription: Use when you have predefined subscription plans created via the Create Subscription Plan endpoint.
Custom Subscription: Use for variable billing scenarios where each payment may differ in amount or timing.

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/subscriptions \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1900",
        "flow": "DIRECT"
    },
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "country": "COL",
    "amount": 10000.00,
    "currency": "COP",
    "accountNumber": "170.170.00000004",
    "conceptCode": "0001",
    "comment": "Test subscription",
    "merchant": {
        "type": "COMPANY",
        "name": "My Company SA DE CV",
        "document": {
            "type": "CC",
            "id": "717321230"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "id": "1073695321",
            "type": "CC"
        },
        "email": "[email protected]"
    },
    "card": {
        "name": "John Doe",
        "number": "4242424242424242",
        "cvv": "123",
        "expirationMonth": "11",
        "expirationYear": "2029",
        "installments": 1
    },
    "type": "SOFTWARE",
    "autoRecurring": {
        "repetitions": 1,
        "type": "day"
    }
}'
'

See all available parameters in the request.

Step 2: Handle the Response

Successful Response

A successful response includes detailed subscription information and identifiers:

{
    "type": "SOFTWARE",
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "internalId": "990017f0-7928-4c20-a149-0c1673035f2c",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "170.170.00000004",
    "status": {
        "code": "105",
        "description": "WAITINGAUTH",
        "detail": "The subscription is active"
    },
    "date": {
        "creationDate": "2025-11-13T05:05:58.8502173",
        "nextPaymentDate": "2025-11-14T05:05:58.8502036"
    },
    "payments": [
        {
            "externalId": "36e1ce13-8a20-4565-b5f5-e275e1df0010",
            "internalId": "adccc452-4a8c-414c-b777-152f4b0ed2da",
            "status": {
                "code": "100",
                "description": "INPROGRESS",
                "detail": "The payin is pending the confirmation"
            },
            "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly93ZWItY2hlY2tvdXQuc3RhZ2UubG9jYWxwYXltZW50LmNvbS92ZXJpZmljYXRpb24vMDA5Nz9pbnRlcm5hbElkPTQzYzVjZDE1LTg0N2UtNDRhNC05MTU1LTcyYmVmNjZiZDAzMw"
        }
    ],
    "errors": []
}

Key Response Fields

Parameter	Description	Use Case
`internalId`	Localpayment's unique subscription identifier.	Subscription tracking and management.
`status.code`	Current subscription status code.	Status monitoring and automation.
`date.creationDate`	When the subscription was created	Audit trail and reporting.
`date.nextPaymentDate`	When the next payment will be processed.	Billing cycle management.
`payments`	Array of payment objects for the subscription.	Payment history and tracking.

Error Response

When a request fails, you'll receive detailed error information:

{
    "externalId": "b27ebf99-e92d-4aca-ba16-f9f8412372cd",
    "internalId": "f95883ce-f08a-485f-9734-0182ec3af70d",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "170.170.00000004",
    "type": "SOFTWARE",
    "autoRecurring": {
        "repetitions": 1,
        "type": "day"
    },
    "status": {
        "code": "300",
        "description": "REJECTED"
    },
    "date": {
        "creationDate": "2025-11-13T05:07:42.7612531"
    },
    "payments": [
        {
            "externalId": "672022a9-b595-4d78-88d0-6ac8d6738082",
            "internalId": "8279db2d-2502-4c1f-8d3b-b668c8b5ff53",
            "status": {
                "code": "300",
                "description": "REJECTED"
            }
        }
    ],
    "errors": [
        {
            "code": "300",
            "detail": "Invalid param + [payer.email] + must not be null"
        }
    ]
}

Step 3: Track Transaction Status

After creating a subscription, monitor its lifecycle through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

The Localpayment API provides various status codes to indicate the state of the subscription.

Code	Status	Description
`105`	`ACTIVE`	Subscription is active and in progress.
`300`	`REJECTED`	Subscription creation or payment was rejected.

📝
Note: For complete status code reference, see the Transaction Status documentation.

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

Successful Subscription Creation: Standard subscription flow with valid card.
Fixed Plan Subscription: Subscription with predefined plan.
Custom Subscription: Subscription with custom billing parameters.
Validation Errors: Invalid card, missing required fields
Status Updates: Webhook handling and status polling

Next Steps

After a subscription is created, you may need to perform additional actions, such as:

Update subscription

Modify existing subscription details including billing amount, frequency, or customer information.

Cancel subscription

Terminate active subscriptions while preserving transaction history and billing records.

Handle subscription webhooks

Set up webhooks to receive real-time notifications for subscription events and payment status changes.