Cancel Payment

The Cancel Payment API allows you to cancel a payment that is still awaiting customer action. A payment can only be cancelled while it is in a pending state. Once a payment has been completed, failed, expired, or previously cancelled, it can no longer be cancelled.

Note Cancellation only prevents the customer from completing the payment. If the payment has already been processed successfully, use refunds or reversals where applicable.

Endpoint

POST /payments/cancel

Authentication

Every request must include your API credentials.

Header	Required	Description
X-API-KEY	✅	Merchant API Key
X-API-SECRET	✅	Merchant API Secret
Content-Type	✅	application/json

Example Request

cURL
JavaScript
Python
PHP

curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/cancel \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxx" \
  --data '{
    "reference": "CIR-6723dg"
}'

const response = await fetch(
  "https://api.splashpay.co.tz/api/v1/payments/cancel",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": process.env.SPLASHPAY_KEY,
      "X-API-SECRET": process.env.SPLASHPAY_SECRET,
    },
    body: JSON.stringify({
      reference: "CIR-6723dg",
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/cancel",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "pk_live_xxxxxxxxx",
        "X-API-SECRET": "sk_live_xxxxxxxxx",
    },
    json={
        "reference": "CIR-6723dg"
    }
)

print(response.json())

$client = new \GuzzleHttp\Client();

$response = $client->post(
    'https://api.splashpay.co.tz/api/v1/payments/cancel',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'X-API-KEY' => 'pk_live_xxxxxxxxx',
            'X-API-SECRET' => 'sk_live_xxxxxxxxx',
        ],
        'json' => [
            'reference' => 'CIR-6723dg',
        ],
    ]
);

echo $response->getBody();

Request Body

Field	Type	Required	Description
reference	string	✅	Unique merchant payment reference returned when the payment was created.

Example Response

{
    "status": "success",
    "code": "PAYMENT_CANCELLED",
    "message": "Payment cancelled successfully",
    "data": {
        "reference": "CIR-6723e8hs6",
        "provider_reference": "S20629971309",
        "status": "cancelled",
        "cancelled_at": "2026-07-12 11:01:56"
    },
    "meta": [],
    "request_id": "05ae240d-f77f-4cff-a8c5-b4bc09e92b32"
}

Error Responses

Payment Already Completed

{
    "status": "error",
    "code": "PAYMENT_NOT_CANCELLABLE",
    "message": "Payment cannot be cancelled because it has already been completed."
}

Payment Expired

{
    "status": "error",
    "code": "PAYMENT_NOT_CANCELLABLE",
    "message": "Payment cannot be cancelled because it has expired."
}

Payment Not Found

{
    "status": "error",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found."
}

Cancellable Statuses

Payment Status	Can Cancel
`pending`	✅
`processing`	✅ (if supported by the payment provider)
`success`	❌
`failed`	❌
`expired`	❌
`cancelled`	❌

Webhook Notification

If your merchant account has a webhook endpoint configured, SplashPay sends a payment.cancelled event after the payment has been successfully cancelled. The webhook is dispatched only after the cancellation has been confirmed and the transaction has been updated in SplashPay.

Event

payment.cancelled

Sample Webhook

{
  "event": "payment.cancelled",
  "created_at": "2026-07-12T11:01:56Z",
  "data": {
    "reference": "CIR-6723e8hs6",
    "provider_reference": "S20629971309",
    "amount": "1000.00",
    "currency": "TZS",
    "status": "cancelled",
    "payment_method": "tanqr",
    "provider": "selcom",
    "channel": "tanqr",
    "network": "SELCOMTANQR",
    "cancelled_at": "2026-07-12T11:01:56Z"
  }
}

Best Practices

Cancel only pending payments

Call the Cancel Payment endpoint before the customer completes the payment. Once payment is successful, it cannot be cancelled.

Use the merchant reference

Always store the merchant reference returned when creating the payment. It is required to cancel or check the payment status.

Verify the final status

After cancelling a payment, you can use the Check Payment Status endpoint to confirm that the payment status is cancelled.

Handle webhook notifications

If your application receives webhook events, update your local payment record whenever a payment.cancelled event is received.

Check Payment Status

Retrieve the latest status of a payment.

Webhooks

Receive real-time payment events.

Mobile Money

Accept Mobile Money payments.

Dynamic TanQR

Accept payments using Dynamic TanQR.

Getting Started

Collections

Disbursements

Cancel Payment

Cancel Payment

Endpoint

Authentication

Example Request

Request Body

Example Response

Error Responses

Payment Already Completed

Payment Expired

Payment Not Found

Cancellable Statuses

Webhook Notification

Event

Sample Webhook

Best Practices

Check Payment Status

Webhooks

Mobile Money

Dynamic TanQR

​Cancel Payment

​Endpoint

​Authentication

​Example Request

​Request Body

​Example Response

​Error Responses

​Payment Already Completed

​Payment Expired

​Payment Not Found

​Cancellable Statuses

​Webhook Notification

​Event

​Sample Webhook

​Best Practices

​Related Guides

Check Payment Status

Webhooks

Mobile Money

Dynamic TanQR

Cancel Payment

Endpoint

Authentication

Example Request

Request Body

Example Response

Error Responses

Payment Already Completed

Payment Expired

Payment Not Found

Cancellable Statuses

Webhook Notification

Event

Sample Webhook

Best Practices

Related Guides