Cancel a Subscription

🚧

Under construction

Localpayment allows you to cancel active subscriptions when customers no longer wish to continue their recurring payments. This guide details the process for canceling a subscription through Localpayment's API, including immediate cancellations and end-of-billing period options.

Before You Begin

Ensure you have:

Step 1: Cancel a Subscription

To cancel an existing subscription, send a PATCH request to the Cancel a Subscription endpoint.

Key Request Parameters

The request requires several key objects:

Example Request

Below is an example using curl:

curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payin/subscriptions/{externalId}/status \
 		 --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data-raw '{
    "status": "CANCEL"
}'

⚠️

Important: Once a subscription is cancelled, it cannot be reactivated. You will need to create a new subscription if the customer wishes to resume service.

Step 2: Handle the Response

Successful Response

A successful cancellation returns the subscription cancellation confirmation:

{
    "externalId": "a2966037-52a1-4a73-9173-b682969b34ff",
    "internalId": "1ef01791-0e51-4b66-9d45-229895cd49d0",
    "status": {
        "code": "903",
        "description": "CANCELLED",
        "detail": "The subscription was canceled - merchant request"
    }
}

Key Response Fields

Error Response

When a subscription cancellation fails, you'll receive error information::

{
    "status": {
        "code": "400",
        "description": "ERROR",
        "detail": "Invalid externalID Subscription Not Found"
    }
}

Step 3: Track Transaction Status

After cancelling a subscription, monitor the status through these methods:

Common Status Codes

📝

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

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

1. Successful Cancellation: Cancel an active subscription with valid credentials.
2. Already Cancelled Subscription: Attempt to cancel already cancelled subscription.
3. Nonexistent Subscription: Cancel a subscription that doesn't exist.
4. Authentication Errors: Cancel with invalid or missing authentication.
5. Webhook Notifications: Confirm cancellation webhooks are triggered

Next Steps

After cancelling a subscription, you may need to perform additional actions: