Cancel Payment Authorization

Cancel an authorized payment and release the reserved funds back to the customer.

Endpoint

GET /api/v2/intents/{intent_id}/cancel-authorization

Authentication: Required (API Key)

Description

This endpoint allows you to cancel a payment authorization that has not yet been captured. When you cancel an authorization, the reserved funds are released back to the customer's payment method, making them available again.

When to Use

Cancel an authorized payment when:

• The customer cancels their order before shipment
• Inventory becomes unavailable after authorization
• Fraud checks indicate suspicious activity
• Order cannot be fulfilled for any reason
• Customer requests cancellation

Request

Headers

Path Parameters

Query Parameters

Example Request

curl -X GET https://app.infinic.com/api/v2/intents/550e8400-e29b-41d4-a716-446655440000/cancel-authorization \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://app.infinic.com/api/v2/intents/550e8400-e29b-41d4-a716-446655440000/cancel-authorization?iauth=eyJ0eXAiOiJKV1QiLCJhbGc..."

const intentId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(
  `https://app.infinic.com/api/v2/intents/${intentId}/cancel-authorization`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${YOUR_API_KEY}`,
    },
  },
);

const data = await response.json();
console.log("Cancellation result:", data);

import requests

intent_id = '550e8400-e29b-41d4-a716-446655440000'

response = requests.get(
    f'https://app.infinic.com/api/v2/intents/{intent_id}/cancel-authorization',
    headers={
        'Authorization': f'Bearer {YOUR_API_KEY}'
    }
)

data = response.json()
print('Cancellation result:', data)

Response

Success Response (200 OK)

The response contains details about the canceled payment.

{
  "id": 12345,
  "attempt_status": "canceled",
  "method": "card",
  "failure_reason": null,
  "intent_id": "550e8400-e29b-41d4-a716-446655440000",
  "intent_status": "canceled",
  "action": null,
  "redirect_url": null
}

Error Responses

401 Unauthorized

{
  "detail": "Invalid or missing API key"
}

Causes:

• Missing Authorization header
• Invalid API key
• Using sandbox key with production URL (or vice versa)

403 Forbidden

{
  "detail": "Not authorized to cancel this payment"
}

Causes:

• Intent belongs to different merchant
• Invalid iauth token
• Insufficient permissions

404 Not Found

{
  "detail": "Payment intent not found"
}

Causes:

• Invalid intent_id
• Intent does not exist
• Intent has been deleted

422 Validation Error

{
  "detail": "Payment intent is not in authorized status"
}

Causes:

• Intent is not in authorized status
• Payment has already been captured (use refund instead)
• Authorization has already been canceled
• Authorization has expired

Other possible errors:

{
  "detail": "Cancellation failed: Authorization already expired"
}

{
  "detail": "Cannot cancel a captured payment. Use refund endpoint instead."
}

Authorization Lifecycle

Status Flow

selection → pending → authorized → captured (success)
                              ↓
                          canceled (via this endpoint)
                              ↓
                          expired (automatic after 7 days)

State Transitions

1. authorized - Payment method has reserved the funds
2. canceled - Funds released back to customer (via this endpoint)
3. expired - Automatically canceled by payment provider after authorization window

Important Notes

Fund Release Timing

When you cancel an authorization:

• Immediate: The authorization is canceled in NjiaPay's system
• PSP Processing: The payment provider processes the cancellation
• Customer sees release: Typically within 1-7 business days depending on the bank/card issuer

The customer's available balance is restored, but they may still see the authorization on their statement temporarily until their bank processes the release.

Authorization Window

Authorizations automatically expire if not captured:

• Typical window: 7 days for most payment providers
• After expiration: Automatically canceled by the PSP
• Best practice: Manually cancel as soon as you know you won't capture

Cannot Cancel After Capture

Once a payment is captured (status = success), you cannot cancel it. You must create a refund instead:

• Use Create Refund for captured payments
• Refunds can be full or partial
• Refund timing varies by payment provider

Payment Method Support

Cancellation is supported for all payment methods that support authorization:

• Supported: Credit cards, debit cards
• N/A: Immediate capture methods (bank transfers, mobile money, etc.)

Webhook Notifications

After a successful cancellation, you'll receive a webhook notification:

{
  "type": "Cancelation",
  "created": "2024-09-01T00:00:00Z",
  "content": {
    "intent_id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_id": "order_12345",
    "purchaser_id": "customer_abc",
    "amount": 10000,
    "currency": "ZAR",
    "status": "canceled"
  }
}

Best Practices

1. Cancel Promptly

Cancel authorizations as soon as you know the order won't be fulfilled. Don't wait for automatic expiration.

Benefits:

• Faster fund release for customer
• Better customer experience
• Cleaner accounting records

2. Notify Customers

Always notify customers when you cancel an authorization:

• Send cancellation confirmation email
• Explain when funds will be available
• Provide customer support contact

3. Handle Edge Cases

Implement proper error handling:

try {
  const response = await cancelAuthorization(intentId);
  if (response.intent_status === "canceled") {
    // Update order status
    // Notify customer
    // Release inventory
  }
} catch (error) {
  if (error.status === 422) {
    // Already captured or expired
    // Check if refund is needed instead
  }
  // Handle other errors
}

4. Track Cancellations

Monitor cancellation metrics:

• Cancellation rate by reason
• Time between authorization and cancellation
• Customer impact analysis

5. Testing

Test cancellation flows in sandbox:

• Cancel immediately after authorization
• Attempt to cancel captured payments (should fail)
• Test expired authorization handling
• Verify webhook delivery

Common Scenarios

Scenario 1: Order Canceled Before Shipment

1. Customer places order → Authorization created
2. Customer cancels order → Call cancel-authorization
3. Update order status to canceled
4. Notify customer funds will be released
5. Release inventory back to stock

Scenario 2: Inventory Unavailable

1. Authorization successful
2. Check inventory → Out of stock
3. Call cancel-authorization
4. Notify customer of unavailability
5. Suggest alternative products

Scenario 3: Fraud Detection

1. Authorization successful
2. Fraud check flags transaction
3. Call cancel-authorization
4. Block future attempts from customer
5. Notify security team

Scenario 4: Customer Dispute

1. Customer contacts support
2. Verify authorization not captured
3. Call cancel-authorization
4. Confirm cancellation with customer
5. Process any refund if needed

Use Cases

1. Order Cancellation - Customer changes mind before shipment
2. Inventory Issues - Product unavailable after authorization
3. Fraud Prevention - Suspicious transaction detected
4. Price Changes - Price adjustment requires new authorization
5. Payment Issues - Customer wants to use different payment method

Comparison: Cancel vs Refund

Next Steps

After canceling an authorization:

1. Update order status - Mark as canceled in your system
2. Release inventory - Make products available again
3. Notify customer - Send cancellation confirmation
4. Update analytics - Track cancellation metrics

Related

• Capture Modes Guide
• Capture Authorized Payment
• Create Refund
• Create Payment Intent
• Get Intent
• Webhook Events