Cancel a payout

If you need to cancel a payout due to an error or change in requirements, you can do so as long as the payout is in one of the following statuses: Pending Authorization, Received, On Hold, or Locked.

You can cancel payouts through the Dashboard or programmatically via the API.

Prerequisites

Before canceling a payout, ensure you have:

• An active payout transaction with status: PendingAuth, Received, OnHold, or Locked
• Valid API credentials with proper permissions
• The transaction identifier (externalId)

⚠️

Important: Once a payout moves to Processing or Completed status, it cannot be cancelled through API. Contact support for assistance with processed transactions.

API Endpoint

To cancel a payout send a PATCHrequest to the Cancel a Payoutendpoint.

Cancel Payout Request

PATCH https://api.stage.localpayment.com/api/payout/cancel

Authentication

Include your access token in the request headers:

Authorization: Bearer <your_access_token>

Key Request Parameters

Example Request

curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payout/cancel \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7"
     }'

Response Handling

Success Response

When cancellation is successful, you'll receive a response with the updated status:

{
  "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7",
  "internalId": "3d36811d-1c02-41ea-a576-68df62c4603a",
  "status": {
    "code": "900",
    "description": "Cancelled",
    "detail": "The payout was cancelled successfully"
  }
}

Key Response Fields

Error Responses

{
  "Status": 404,
  "Message": "This transaction does not exist.",
  "TraceId": "dae2d1cb-7e9e-48a5-8530-980f38b31712"
}

Implementation Best Practices

💡

Security & Performance Tips

• Always validate transaction status before attempting cancellation
• Use HTTPS for all API requests
• Store access tokens securely and rotate them regularly
• Implement proper error handling and retry logic
• Log all cancellation attempts for audit purposes

Testing Your Implementation

Before deploying to production, test your cancellation logic thoroughly:

1. Test with valid transactions in cancellable statuses
2. Test with invalid transactions to handle errors gracefully
3. Test authentication failures and token expiration
4. Verify webhook handling if implemented
5. Test rate limiting and retry logic

Next Steps

Support & Resources

Need assistance with your payout cancellation integration?

• Technical Support: Contact our support team for integration help
• API Documentation: Complete endpoint reference and guides

🚀

Pro Tip: Test your cancellation workflow in our sandbox environment before implementing in production. This ensures your integration handles all edge cases and error scenarios correctly.