Advanced Payment Operations

These endpoints extend the core payment flow for specialized use cases like incremental authorization, extended authorization, post-capture cancellation, and session tokens.

Incremental Authorization

Increase the authorized amount on an existing payment that has been authorized but not yet captured. Useful for hotel stays, car rentals, and tab-based billing.

POST /payments/{payment_id}/incremental_authorization

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/incremental_authorization \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 7500,
    "reason": "Additional room service charges"
  }'

The payment must be in requires_capture status. Pass the new total amount, not the increment.

Extended Authorization

Request an extension of the authorization hold period before it expires.

POST /payments/{payment_id}/extend_authorization

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/extend_authorization \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Not all processors support extended authorization. Check the response for confirmation.

Cancel Post Capture

Cancel a payment that has already been captured. This triggers a refund on the processor side.

POST /payments/{payment_id}/cancel_post_capture

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/cancel_post_capture \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Order cancelled by customer"
  }'

Complete Authorization

For payments that require additional steps after the initial authorization (such as redirect-based flows), use this endpoint to complete the authorization.

POST /payments/{payment_id}/complete_authorize

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/complete_authorize \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Session Tokens

Create session tokens for third-party SDK integrations such as Apple Pay and Google Pay.

POST /payments/session_tokens

curl https://sandbox.perfectpay.ai/payments/session_tokens \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
    "wallets": ["apple_pay", "google_pay"]
  }'

The response includes the session tokens your frontend needs to initialize wallet payment sheets.

Update Payment Metadata

Attach or update metadata on an existing payment after creation.

PUT /payments/{payment_id}/update_metadata

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/update_metadata \
  -X PUT \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "internal_order_id": "ORD-5678",
      "fulfilled_at": "2026-03-23T10:00:00Z"
    }
  }'

Payment Eligibility

Check whether a payment is eligible for specific operations before attempting them.

GET /payments/{payment_id}/eligibility

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/eligibility \
  -H "api-key: YOUR_SECRET_API_KEY"

3DS External Authentication

Trigger external 3DS authentication for payments that require it.

POST /payments/{payment_id}/3ds/authentication

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/3ds/authentication \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

See the 3DS Authentication guide for the full 3DS flow.

Related

• Payments for core payment operations
• 3DS Authentication for the full 3DS flow
• Web SDK for client-side wallet integration