Refunds¶

SecPaid supports programmatic full and partial refunds via API.

How Refunds Work¶

stateDiagram-v2
    [*] --> Paid: Payment completed
    Paid --> RefundRequested: refundPayment API call
    RefundRequested --> Approved: Admin approves
    RefundRequested --> Rejected: Admin rejects
    Approved --> Refunded: Refund processed

You call POST /api/v2/refundPayment with the pay_id and refund_amount
A refund request is created (status: pending)
A SecPaid admin reviews and approves/rejects the refund
If approved, the refund is processed to the customer's original payment method

Requirements¶

Always specify refund_amount

The refund_amount field is always required — even for full refunds. Set it to the full payment amount for a complete refund.

Refund Types¶

Full Refund¶

Refund the entire payment amount:

{
  "pay_id": 12345,
  "refund_amount": 49.99,
  "isFullRefund": true
}

Partial Refund¶

Refund a portion of the payment:

{
  "pay_id": 12345,
  "refund_amount": 20.00
}

Conditions That Block Refunds¶

The API will reject a refund request if:

Condition	Error Message
Link was cancelled (not paid)	Link is cancelled
Invalid `pay_id`	Link not found
Link type is "invoice"	Cannot refund invoice-type links
Refund already requested for this link	Refund already requested
Active dispute exists on the payment	Refund blocked by dispute
`refund_amount` exceeds paid amount	Invalid refund amount
`refund_amount` is 0 or negative	Refund amount is required

Refund Status Lifecycle¶

Status	Meaning
`Pending`	Refund requested, awaiting admin review
`Approved`	Admin approved, processing
`Rejected`	Admin rejected with optional reason
`Completed`	Refund successfully processed

Important Notes¶

Refunds are processed back to the original payment method
There is no webhook notification when a refund is processed
Bank transfer payments may have different refund handling
The refund amount cannot exceed the original payment amount
Multiple partial refunds on the same link are not supported — one refund request per link

refundPayment API Reference