Cancel a Cash Payment

Localpayment enables you to cancel pending cash payments through API integration. This guide covers the complete cancellation workflow for cash 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 cash payment transaction you wish to cancel.
• Complete beneficiary information for data-required refunds.

Direct Cancellation for Cash Payments

Cash 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: Cash payments can only be cancelled while they are in a pending or in-progress state. Once a cash payment has been completed or settled, you must process a refund instead of a cancellation.

Step 1: Cancel Cash Payment via API

To cancel a cash 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 cash 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 cash 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