Skip to main content
POST
/
v1
/
payments
/
{paymentId}
/
cancel
Cancel a payment
curl --request POST \
  --url https://api-eu.flexportal.io/v1/payments/{paymentId}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "reason": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "payment": {
    "paymentId": "<string>",
    "tenantId": "<string>",
    "customerId": "<string>",
    "subtotal": 1,
    "total": 1,
    "currency": "<string>",
    "paymentType": "individual",
    "billingPeriod": "<string>",
    "status": "pending",
    "idempotencyKey": "<string>",
    "dueDate": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "taxAmount": 0,
    "taxRate": 0,
    "amount": 1,
    "rentalId": "<string>",
    "billingGroupId": "<string>",
    "provider": "stripe",
    "transactionId": "<string>",
    "providerResponse": {},
    "manuallyMarked": false,
    "paymentReference": "<string>",
    "markedBy": "<string>",
    "captureAttempts": 0,
    "lastCaptureError": {
      "code": "<string>",
      "message": "<string>",
      "declineCode": "<string>"
    },
    "lineItems": [
      {
        "rentalId": "<string>",
        "description": "<string>",
        "amount": 1,
        "taxAmount": 0
      }
    ],
    "lateFeeApplied": false,
    "lateFeeAmount": 1,
    "originalAmount": 1,
    "notes": "<string>",
    "paidAt": "<string>",
    "lastCaptureAttempt": "<string>",
    "nextRetryAt": "<string>"
  }
}

​
Overview

Cancel a pending or failed payment. Use this when a payment should not be collected—for example, when a subscription was ended early or a billing adjustment is needed.
Cancelling a payment removes it from collection. This action cannot be undone. For refunds of already-paid payments, use your payment processor’s refund functionality.

​
Common Use Cases

  • Early Termination: Subscription ended before payment due
  • Billing Adjustment: Correcting overcharges or errors
  • Customer Goodwill: Waiving a payment as a courtesy
  • Duplicate Payments: Removing duplicate scheduled payments
  • Subscription Cancelled: Associated subscription was cancelled

​
Request Fields

FieldRequiredDescription
reasonYesReason for cancellation

​
Example Request

{
  "reason": "Subscription ended early - customer relocated"
}

​
What Happens

When you cancel a payment:
  1. Payment status changes to cancelled
  2. Cannot be collected or marked as paid
  3. Subscription metrics may be updated
  4. Reason recorded for audit trail

​
Which Payments Can Be Cancelled

Current StatusCan Cancel?
pendingYes
processingNo (wait for result)
paidNo (use refund instead)
failedYes
cancelledNo (already cancelled)

​
Example: Cancel Due to Early Return

async function handleEarlyReturn(subscriptionId) {
  // Get all pending payments for this subscription
  const { payments } = await listPayments({
    rentalId: subscriptionId,
    status: 'pending'
  });

  // Cancel remaining payments
  for (const payment of payments) {
    await cancelPayment(payment.paymentId, {
      reason: `Subscription ${subscriptionId} ended early`
    });
  }

  return {
    cancelledPayments: payments.length,
    savedAmount: payments.reduce((sum, p) => sum + p.amount, 0)
  };
}

​
Example: Cancel with Customer Reason

async function cancelAsGoodwill(paymentId, customerName) {
  return await cancelPayment(paymentId, {
    reason: `Goodwill gesture for ${customerName} - approved by manager`
  });
}

​
Error Handling

Error CodeCauseSolution
NOT_FOUNDPayment doesn’t existVerify payment ID
ALREADY_PAIDCannot cancel paid paymentUse refund instead
ALREADY_CANCELLEDPayment already cancelledNo action needed
PAYMENT_PROCESSINGPayment currently processingWait for result

Authorizations

​
Authorization
string
header
required

API key obtained from FlexPortal dashboard

Headers

​
Tenant-ID
string
required

Your tenant identifier

Path Parameters

​
paymentId
string
required

The payment ID

Body

application/json
​
reason
string
required
Minimum string length: 1

Response

Payment cancelled

​
success
enum<boolean>
required
Available options:
true,
false
​
message
string
required
​
payment
object
required