Voids and Refunds

Learn how to cancel payments with voids and return funds with refunds

Voids and refunds allow you to reverse payments that have been processed. Voids cancel payments before they settle, preventing funds from being transferred. Refunds return funds to customers after a payment has settled. Understanding when to use each ensures proper fund management and provides a smooth customer experience.

Prerequisites

Before implementing voids and refunds, it's helpful to learn about the following topics.

Understanding Voids vs Refunds

Voids and refunds serve different purposes in the payment lifecycle and have different eligibility requirements.

Voids

A void cancels a payment before it settles with the bank or card network. When you void a payment:

• The transaction is canceled before funds are transferred
• No money moves from the customer
• The authorization hold on the customer's card is released

Refunds

A refund reverses funds after a transaction has settled. When you refund a transaction:

• A new transaction is created to reverse the original transaction
• For payments: Funds are returned to the customer from your processing account
• For payouts: Funds are reversed from the recipient back to your processing account
• Takes 3-5 business days for funds to complete the transfer
• Available after transaction has settled

Voiding Payments

Cancel a payment before it settles by updating its status to voided.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve the payment transaction
payment = pl.Transaction.get('txn_payment123')
 
# Void the payment by updating status to voided
payment.update(status={'value': 'voided'})
 
print(f"Payment {payment.id} has been voided")
print(f"Status: {payment.status}")

This example demonstrates voiding a payment:

1. Retrieve the payment transaction by ID
2. Update the transaction status to voided
3. The authorization hold is released immediately
4. Customer is not charged

A payment can only be voided while its finalized property is false. Once a payment is finalized (finalized is true), it has settled and must be refunded instead.

Refunding Payments

Return funds to customers by creating a refund transaction.

• Full Refund
• Partial Refund

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve the original payment
payment = pl.Transaction.get('txn_payment123')
 
# Create a refund transaction with transfer linking to original payment
refund = pl.Transaction.create(
    type='refund',
    amount=payment.amount,
    description=f'Refund for order {payment.order_number}',
    transfers=[{
        'assoc_transaction_id': payment.id
    }]
)
 
print(f"Refund created: {refund.id}")
print(f"Amount: ${refund.amount}")
print(f"Status: {refund.status}")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve the original payment
payment = pl.Transaction.get('txn_payment123')
 
# Create a partial refund for $25 of a $100 payment with transfer linking
refund = pl.Transaction.create(
    type='refund',
    amount=25.00,
    description='Partial refund for one returned item',
    transfers=[{
        'assoc_transaction_id': payment.id
    }]
)
 
print(f"Partial refund created: {refund.id}")
print(f"Refund amount: ${refund.amount}")
print(f"Original payment: ${payment.amount}")
print(f"Status: {refund.status}")

Checking Refund Eligibility

Verify whether a payment can be voided or must be refunded based on its finalization status.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve the payment transaction
payment = pl.Transaction.get('txn_payment123')
 
# Check if payment can be voided or must be refunded using finalized property
if payment.finalized is False:
    print("Payment not finalized, can be voided")
    # Void the payment
    payment.update(status={'value': 'voided'})
    print(f"Payment {payment.id} has been voided")
 
elif payment.finalized is True:
    print("Payment is finalized, must be refunded")
    # Create a refund with transfer linking
    refund = pl.Transaction.create(
        type='refund',
        amount=payment.amount,
        transfers=[{
            'assoc_transaction_id': payment.id
        }]
    )
    print(f"Refund created: {refund.id}")
 
else:
    print(f"Payment finalized status is unknown, cannot void or refund")

This example demonstrates eligibility checks:

1. Retrieve the payment transaction
2. Check the finalized property to determine current state
3. If finalized is false, the payment can be voided
4. If finalized is true, the payment has settled and must be refunded

Checking eligibility before attempting voids or refunds prevents errors and ensures proper fund handling.

Handling Refund Failures

Properly handle scenarios where refunds cannot be processed.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve the original payment
payment = pl.Transaction.get('txn_payment123')
 
try:
    # Attempt to create a refund with transfer linking
    refund = pl.Transaction.create(
        type='refund',
        amount=150.00,
        transfers=[{
            'assoc_transaction_id': payment.id
        }]
    )
    print(f"Refund successful: {refund.id}")
 
except Exception as error:
    # Handle refund errors
    print(f"Refund failed: {error.error_description}")
    print(f"Error type: {error.error_type}")
    print("Details:", error.details)
 
    # Handle specific error types
    if error.error_type == 'InvalidAttributes':
        print("Action: Verify request parameters")
    else:
        print("Action: Contact support or check error details")

Common refund failure scenarios:

• Invalid Payment Method: Original payment method is closed or invalid
• Exceeded Amount: Refund amount exceeds original payment
• Already Refunded: Payment has already been fully refunded
• Network Issues: Temporary problems with payment network

Testing Voids and Refunds

Test void and refund functionality in test mode before production deployment.

• Testing Voids
• Testing Refunds

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a test payment
payment = pl.Transaction.create(
    type='payment',
    amount=50.00,
    sender={
        'method': {
            'type': 'card',
            'card': {
                'card_number': '4111111111111111',  # Test card
                'expiry': '12/25',
                'card_code': '123',
            },
            'billing_address': {'postal_code': '12345'},
        }
    },
    receiver={'account_id': 'acct_test123'},
)
 
print(f"Test payment created: {payment.id}")
print(f"Status: {payment.status}")
 
# Immediately void the payment
payment.update(status={'value': 'voided'})
 
print(f"\nPayment voided: {payment.id}")
print(f"New status: {payment.status}")
 
# Verify void succeeded
assert payment.status.value == 'voided', "Void failed"
print("\n✓ Void test passed")

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create and settle a test payment
payment = pl.Transaction.create(
    type='payment',
    amount=75.00,
    sender={
        'method': {
            'type': 'card',
            'card': {
                'card_number': '4111111111111111',
                'expiry': '12/25',
                'card_code': '123',
            },
            'billing_address': {'postal_code': '12345'},
        }
    },
    receiver={'account_id': 'acct_test123'},
)
 
print(f"Test payment created: {payment.id}")
print(f"Amount: ${payment.amount}")
 
# Create a refund with transfer linking
refund = pl.Transaction.create(
    type='refund', amount=payment.amount, transfers=[{'assoc_transaction_id': payment.id}]
)
 
print(f"\nRefund created: {refund.id}")
print(f"Refund amount: ${refund.amount}")
print(f"Status: {refund.status}")
 
# Verify refund
assert refund.type == 'refund', "Type should be refund"
assert refund.amount == payment.amount, "Amount should match payment"
print("\n✓ Refund test passed")

Monitoring Voids and Refunds

Track void and refund operations through webhooks and transaction queries.

Webhook Events

Monitor these webhook events for void and refund operations:

• void - Payment was successfully voided
• refund - Refund transaction was created
• processed - Refund completed and funds transferred
• decline - Payment declined before processing

For detailed webhook setup and implementation, see Transaction Webhooks.

Querying Transactions

List voided and refunded transactions:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query all refund transactions
refunds = pl.Transaction.filter_by(
    type='refund'
).all()
print(f"Found {len(refunds)} refund transactions\n")
 
# Display refund summary
total_refunded = 0
for refund in refunds:
    print(f"Refund: {refund.id}")
    print(f"  Amount: ${refund.amount}")
    print(f"  Status: {refund.status}")
    print(f"  Date: {refund.created_at}")
    print(f"  Description: {refund.description}")
    print()
    total_refunded += refund.amount
 
print(f"Total refunded: ${total_refunded}")
 
# Query voided transactions
voided = pl.Transaction.filter_by(
    status__value='voided'
).all()
print(f"\nFound {len(voided)} voided transactions")

Use queries to:

• Generate refund reports for accounting
• Monitor refund rates by product or service
• Identify high-refund accounts or customers
• Track refund processing times
• Analyze refund reasons

Schema Reference

The following fields are relevant for void and refund operations:

Transaction Fields

For complete transaction field documentation, see the Transaction API Reference.

Next Steps

Enhance your payment operations with voids and refunds

Handle Payment Lifecycle

Process payments with the Payment API, implement Two-Step Processing to authorize and capture payments separately, and receive real-time updates via Webhook Events for void and refund operations.

Manage Failed Payments

Handle Payment Declines for real-time payment failures, manage Bank Rejects for asynchronous ACH rejections, and resolve Disputes to handle customer disputes and chargebacks.

Track and Reconcile Payments

Monitor payment metrics with Reporting Overview, query and analyze transaction data using Build Report Queries, and match bank statements with Bank Reconciliation.

Related articles

• Payment API - Process payments
• Payment Processing - Payment lifecycle
• Transactions API Reference
• Webhooks - Transaction events