This guide provides practical examples for processing refunds using Banked's API. It covers the primary refund methods and demonstrates how to handle common use cases like full and partial refunds.
Prerequisite: Before initiating a refund, ensure the original payment (pay-in) has a status of SENT.
This guide will walk you through these key scenarios:
- Understanding Refund Types: Mandated vs. AccountToAccount refunds.
- Mandated Refund Scenarios: Full and partial refunds using a payment mandate.
- AccountToAccount Refund Scenarios: Full and partial refunds to a specified bank account.
- Retrieving Refund Status: How to check the status of a processed refund.
When to Use Each Refund Type
Choose the right refund type based on the original payment method and the information you have available.
Mandated Refunds
Best for: Merchants with non-NAB accounts, flexible account arrangements
- Uses PayTo mandate system for real-time refunds
- Requires pre-established refund mandate (set up by Banked Support)
- Works with any eligible merchant account type
- Automatic authorization via mandate token
Refund mandates are created during merchant onboarding and can only be created or modified by authorized Banked personnel. Contact Banked Support to set up or modify your refund mandate.
Account-to-Account Refunds
Best for: NAB account holders
- Direct NPP processing via NAB's New Payments Platform connection
- Faster setup (no mandate required)
- Real-time processing
- Requires eligible NAB account
Only available for merchants with NAB accounts that are eligible for processing refunds.
Mandated Refund Scenarios
These scenarios outline how to create and retrieve refunds using a pre-existing payment mandate.
Scenario 1. Create a Full Mandated Refund
Use Case: A customer paid 10.00 AUD for an item using a mandated payment and has returned it for a full refund. Implementation Strategy: Create a refund for the full amount of the original pay-in, referencing the pay-in ID and the mandate token used for the payment.
Example Request:
POST /v3/refunds
{
"amount": 10,
"original_payin_information": {
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"processing_method": {
"method_type": "MANDATE",
"mandate": {
"token": "a6017842-1a01-4cc1-9d5e-d66ef0094685"
}
}
}
Example Response:
{
"amount": 10,
"created_at": "2025-05-22T10:38:49.162980987Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
},
"mandate": {
"id": "3f80b430-4127-46f9-a86f-3ce18a02a53d"
},
"expiration": "2025-06-21T10:38:49.162981594Z",
"id": "4690e5d4-5fcb-49e1-ad90-396dc48587c5",
"original_payin_information": {
"amount": 10,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"status_details": {
"status": "PENDING"
},
"updated_at": "2025-05-22T10:38:49.246322209Z"
}
Scenario 2. Create a Partial Mandated Refund
Use Case: A customer's order was 10.00 AUD, but only one item worth 5.00 AUD was returned. The original payment was made via mandate.
Implementation Strategy: Create a refund for the partial amount, specifying 5.00 in the amount field.
Example Request:
POST /v3/refunds
{
"amount": 5,
"original_payin_information": {
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"processing_method": {
"method_type": "MANDATE",
"mandate": {
"token": "a6017842-1a01-4cc1-9d5e-d66ef0094685"
}
}
}
Example Response:
{
"amount": 5,
"created_at": "2025-05-22T10:38:49.162980987Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
},
"mandate": {
"id": "3f80b430-4127-46f9-a86f-3ce18a02a53d"
},
"expiration": "2025-06-21T10:38:49.162981594Z",
"id": "4690e5d4-5fcb-49e1-ad90-396dc48587c5",
"original_payin_information": {
"amount": 10,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"status_details": {
"status": "PENDING"
},
"updated_at": "2025-05-22T10:38:49.246322209Z"
}
AccountToAccount Refund Scenarios
These scenarios outline how to process refunds directly to a customer's bank account.
Scenario 1. Create a Full AccountToAccount Refund
Use Case: A customer paid 10.00 AUD via a standard single payment and requires a full refund.
Implementation Strategy: Create a refund for the full amount, specifying the debtor_account (the customer's account) where the funds should be sent.
Example Request:
POST /v3/refunds
{
"amount": 10,
"original_payin_information": {
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"processing_method": {
"method_type": "ACCOUNT_TO_ACCOUNT",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
}
}
}
Example Response:
{
"amount": 10,
"created_at": "2025-07-02T11:10:22.512Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
},
"expiration": "2025-08-01T11:10:22.512Z",
"id": "c4d9e8f7-6a5b-4c3d-b2a1-e0f9d8c7b6a5",
"original_payin_information": {
"amount": 10,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"status_details": {
"status": "PENDING"
},
"updated_at": "2025-07-02T11:10:22.678Z"
}
Scenario 2. Create a Partial AccountToAccount Refund
Use Case: A customer is eligible for a partial refund of 5.00 AUD on a 10.00 AUD order as a goodwill gesture.
Implementation Strategy: Create a refund for the partial amount by specifying 5.00 and providing the customer's debtor_account details.
Example Request:
POST /v3/refunds
{
"amount": 5,
"original_payin_information": {
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"processing_method": {
"method_type": "ACCOUNT_TO_ACCOUNT",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
}
}
}
Example Response:
{
"amount": 5,
"created_at": "2025-07-02T11:15:05.123Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
},
"expiration": "2025-08-01T11:15:05.123Z",
"id": "d5e6f7a8-9b0c-1d2e-3f4a-5b6c7d8e9f0a",
"original_payin_information": {
"amount": 10,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"status_details": {
"status": "PENDING"
},
"updated_at": "2025-07-02T11:15:05.234Z"
}
Retrieving a Refund
You can check the status of any refund by its unique ID. This is useful for confirming whether the funds have been sent successfully.
Get Refund by ID
Use Case: You want to confirm the final status of a refund you processed earlier.
Implementation Strategy: Use a GET request to the /v3/refunds/{id} endpoint with the ID of the refund you want to retrieve.
Example Request:
GET /v3/refunds/4690e5d4-5fcb-49e1-ad90-396dc48587c5
Example Response (Successful Refund):
The status will move from PENDING to SENT once the refund has been successfully processed and sent to the customer's bank.
{
"amount": 10,
"created_at": "2025-07-02T10:38:49.162Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
},
"mandate": {
"id": "3f80b430-4127-46f9-a86f-3ce18a02a53d" // Only present for mandated refunds
},
"expiration": "2025-08-01T10:38:49.162Z",
"id": "4690e5d4-5fcb-49e1-ad90-396dc48587c5",
"original_payin_information": {
"amount": 10,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"status_details": {
"status": "SENT"
},
"updated_at": "2025-07-02T10:39:15.987Z"
}
mandate: The mandate field is only present for refunds processed using a mandate. For AccountToAccount refunds, this field will not be included.
Implementation Best Practices
Webhook Processing for Refunds
Set up webhooks to receive real-time updates on refund status changes. Your system should listen for refund-specific events to automate internal processes:
Example Webhook Handler:
function handleRefundWebhook(webhookData) {
const { event, data } = webhookData;
switch (event) {
case 'refund.sent':
// Update your system: Mark refund as complete
updateRefundStatus(data.id, 'completed');
// Send customer notification
notifyCustomer(data.original_payin_information.id, 'refund_completed');
break;
case 'refund.failed':
// Update your system: Mark refund as failed
updateRefundStatus(data.id, 'failed');
// Alert support team for manual intervention
alertSupportTeam(data.id, data.failure_reason);
break;
case 'refund.pending':
// Update your system: Mark refund as processing
updateRefundStatus(data.id, 'processing');
break;
default:
console.log(`Received unhandled refund event: ${event}`);
}
}
Refund Expiration Strategy
Unlike payments, refunds typically don't require customer action, but they do have expiration times. Monitor refund expiration to handle edge cases:
- Mandated Refunds: Usually expire within 30 days if not processed
- AccountToAccount Refunds: May expire based on banking network rules
- Failed Refunds: Implement retry logic for temporary failures
Testing Strategies
Scenario-Based Testing
Thoroughly test all refund scenarios in the sandbox environment to ensure your integration handles both success and failure cases correctly.
Refund Testing Checklist:
- [ ] Successful full and partial refunds (both Mandated and AccountToAccount)
- [ ] Failed refunds (invalid account details, expired payments)
- [ ] Multiple partial refunds for same payment
- [ ] Refund amount exceeding original payment
- [ ] Invalid mandate tokens and suspended mandates
- [ ] Network timeouts and webhook delivery failures
Testing with Mock Bank
For testing with mock bank accounts see our Testing with Mock Bank section.
Mock Refund Scenarios:
- Use test mandate tokens provided in sandbox
- Test with various account types (savings, checking)
- Simulate network failures and retries
- Verify webhook delivery in test environment
Next Steps
After implementing these common refund scenarios, explore:
- Refund Webhooks - Set up real-time notifications for refund events
- Refund States - Understand the complete refund lifecycle
- Refund Errors - Comprehensive error handling guide
- Payment Integration - Understanding the payment flow that precedes refunds
- API Reference - Complete refunds API documentation
For specific implementation questions or regional requirements, contact Banked Support.