Cancel Payment

Cancels a payment that is in a cancellable status. Once cancelled, the payment cannot be completed by the customer.

Endpoint

POST /api/v1/payments/{payment_id}/cancel

Authentication

This endpoint requires HMAC Integration Authentication.

Path Parameters

Parameter	Type	Required	Description
`payment_id`	string	Yes	The UUID of the payment to cancel

Example Request

import crypto from 'crypto';

const API_KEY = process.env.PAYMENT_API_KEY!;
const API_SECRET = process.env.PAYMENT_API_SECRET!;

async function cancelPayment(paymentId: string) {
  const method = 'POST';
  const path = `/api/v1/payments/${paymentId}/cancel`;
  const body = '';
  const timestamp = Date.now().toString();

  const message = `${timestamp}.${body}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(message)
    .digest('hex');

  const response = await fetch(`https://api.example.com${path}`, {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': `sha256=${signature}`,
    },
  });

  const result = await response.json();

  if (result.success) {
    console.log('Payment cancelled:', result.data.id);
    console.log('Status:', result.data.status);
    return result.data;
  } else {
    console.error('Error:', result.error);
    throw new Error(result.error.message);
  }
}

// Cancel payment
const payment = await cancelPayment('550e8400-e29b-41d4-a716-446655440000');

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "1000.00",
    "currency": "THB",
    "status": "canceled",
    "paymentMethod": "promptpay",
    "referenceId": "order-12345",
    "description": "Payment for order #12345",
    "metadata": {
      "order_id": "12345"
    },
    "clientSecret": null,
    "nextAction": null,
    "confirmedAt": null,
    "capturedAt": null,
    "canceledAt": "2024-01-01T00:10:00.000Z",
    "expiresAt": "2024-01-01T01:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:10:00.000Z"
  }
}

Error Responses

Payment Not Found (404)

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Payment not found"
  }
}

Payment Cannot Be Cancelled (400)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Payment cannot be cancelled because it has already been completed"
  }
}

Cancellation Rules

Important

Only payments in certain statuses can be cancelled. Payments that are succeeded, canceled, expired, or payment_failed cannot be cancelled.

Cancellable Statuses

✅ processing - Payment can be cancelled
✅ requires_payment_method - Payment can be cancelled
✅ requires_confirmation - Payment can be cancelled
✅ requires_action - Payment can be cancelled
✅ requires_capture - Payment can be cancelled (before capture)

Non-cancellable Statuses

❌ succeeded - Payment has been completed
❌ canceled - Payment is already cancelled
❌ expired - Payment has expired
❌ payment_failed - Payment has already failed