Create a Subscription

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.

IP Whitelisting

Whitelist your server IP addresses for API access.

Webhook Endpoint

Set up a webhook URL to receive payment notifications.

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	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.

Payment Method Codes

In every country, paymentMethod.code identifies the country, the card brand, and the product (credit or debit), so send the code that matches the card and the subscription's country. In Peru, where cards are accepted in two currencies, the code must also match the currency: for example, a Visa credit card uses 6000 with PEN and 6004 with USD. See Card Payment Method Codes for the codes of all countries.

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": "{{accountNumber}}",
    "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": {
        "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": "{{accountNumber}}",
    "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": "{{accountNumber}}",
    "type": "SOFTWARE",
    "autoRecurring": {
        "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.

Business Portal 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.

🗒️
Complete Reference
View all status codes in our 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.