Cancel an APM Payment

Localpayment enables you to cancel pending APM payments through API integration. This guide covers the complete cancellation workflow for APM transactions using the direct cancellation method that requires only the transaction's externalId.

Before You Begin

Ensure you have:

Additional Cancellation Requirements:

• User role with cancellation permissions (see User Roles documentation).
• The original transaction must be in a cancellable state.
• The externalId of the APM payment transaction you wish to cancel.
• Complete beneficiary information for data-required refunds.

Direct Cancellation for APM Payments

APM payment cancellations are processed as Direct Cancellations, meaning you only need the original transaction's externalId and the status parameter set to CANCELLED. The system immediately stops any further processing of the payment.

⚠️

Important: APM payments can only be cancelled while they are in a pending or in-progress state. Once a APM payment has been completed or settled, you must process a refund instead of a cancellation.

Step 1: Cancel APM Payment via API

To cancel a APM payment, send a PATCH request to the Cancel endpoint.

Key Request Parameters

The request requires several key parameters:

Example Request

Below is an example using curl:

curl --request PATCH \
  --url 'https://api.stage.localpayment.com/api/transactions/{{externalId}}/status' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "CANCELLED"
  }'

See all available parameters in the request.

Step 2: Handle the Response

Successful Response

A successfully cancelled APM payment returns confirmation details:

{
  "externalId": "1c364061-1f3d-4b94-c270-bf915c22e8f5",
  "internalId": "8a9abd31-31e0-429a-32a6-cca8b9e1e536",
  "status": {
    "code": "900",
    "description": "CANCELLED",
    "detail": "The payin was cancelled"
  }
}

Key Response Fields

Error Response

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

{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Invalid operation"
  }
}

Common Error Scenarios

Step 3: Track Cancellation Status

After initiating a cancellation, monitor its progress through these methods:

Common Cancellation 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 a pending APM payment with valid externalId.
2. Invalid Transaction: Try to cancel non-existent externalId.
3. Already Completed: Attempt to cancel a completed transaction.
4. Permission Validation: Test with users having different permission levels.
5. Missing Status Parameter: Attempt cancellation without the required status field.

Next Steps