Getting Started with Refunds

Whether you're implementing Mandate Refunds using PayTo or Account to Account Refunds via NPP, this guide covers both refund methods available in Australia, including:

1. Prerequisites and Setup: Get your account and credentials ready
2. Choose Your Refund Method: Understand mandated vs account to account refunds
3. Process Your First Refund: Make your first refund API call
4. Authorize Refunds: Understand how refunds are authorized
5. Monitor Refund Status: Track refund progress and handle webhooks
6. Error Handling: Implement robust error handling
7. Go Live: Deploy to production with confidence

Step 1: Prerequisites and SetupCopy URL

What You'll NeedCopy URL

Before processing refunds, ensure you have:

• Banked merchant account with refund capabilities enabled - Create account here
• API credentials - Your API key and secret (authentication guide)
• Original payment in "sent" state - You can only refund successfully processed payments
• Refund method setup - Either mandate token or eligible Float account (see Step 2)

API Request HeadersCopy URL

All refund API requests require these headers:

{
  "Authorization": "Bearer <OAuth_short_lived_scoped_token>",
  "Content-Type": "application/json",
  "Idempotency-Key": "unique-request-uuid"
}

Step 2: Choose Your Refund MethodCopy URL

Banked supports two refund methods, each suited for different merchant account types:

Step 3: Process Your First RefundCopy URL

All refunds use the same endpoint: POST /v3/refunds

Depending on your refund method, you'll need to provide different parameters in the request body.

curl --location --request POST 'https://api.banked.com/v3/refunds' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-refund-id-123' \
--data-raw '{
  "amount": 1000,
  "original_payin_information": {
    "id": "82a649c5-af14-474a-997a-b25b0d3f45be"
  },
  "processing_method": {
    "method_type": "MANDATE",
    "mandate": {
      "token": "a6017842-1a01-4cc1-9d5e-d66ef0094685"
    }
  }
}'

{
  "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"
}

curl --location --request POST 'https://api.banked.com/v3/refunds' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-refund-id-123' \
--data-raw '{
  "amount": 1000,
  "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"
    }
  }
}'

{
  "id": "4690e5d4-5fcb-49e1-ad90-396dc48587c5",
  "amount": 1000,
  "currency": "AUD",
  "status_details": {
    "status": "PENDING"
  },
  "debtor_account": {
      "account_type": "BANKED_BANK_ACCOUNT_ENTITY",
      "bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
    },
  "debtor_account": {
      "account_type": "BANKED_BANK_ACCOUNT_ENTITY",
      "bank_account_id": "06a1cb4b-f038-4d4d-b3f9-2114e31125a2"
    },
  "original_payin_information": {
    "amount": 1000,
    "id": "82a649c5-af14-474a-997a-b25b0d3f45be"
  },
  "created_at": "2025-05-22T10:38:49.162980987Z",
  "updated_at": "2025-05-22T10:38:49.246322209Z",
  "expiration": "2025-06-21T10:38:49.162981594Z"
}

Partial RefundsCopy URL

Both methods support partial refunds. Simply specify a lower amount than the original payment:

POST /v3/refunds
{
  "amount": 5, // Partial refund amount
  "original_payin_information": {
    "id": "82a649c5-af14-474a-997a-b25b0d3f45be"
  },
  "processing_method": {
    "method_type": "MANDATE",
    "mandate": {
      "token": "a6017842-1a01-4cc1-9d5e-d66ef0094685"
    }
  }
}

POST /v3/refunds
{
  "amount": 5, // Partial refund amount
  "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"
    }
  }
}

Step 4: Authorizing RefundsCopy URL

Step 5: Monitor Refund StatusCopy URL

You can check the refund status at any time using the refund ID from your initial response:

curl --location --request GET 'https://api.banked.com/v3/refunds/{refund_id}' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>'

Key Refund StatesCopy URL

Track your refund through these key states:

• PENDING: Refund request created, awaiting processing
• SENT: Refund successfully processed and sent to customer
• FAILED: Refund failed - check error details for reason

Initial Confirmation: Upon successful initiation of the refund request, you will receive a confirmation via the API response. The status_details.status field will initially be set to PENDING.

Testing With MockBankCopy URL

To test various refund scenarios, you can use the Banked sandbox environment. Here are some example account numbers and PayID aliases to simulate different outcomes, you must use these when creating and completing the initial payment:

Set Up Webhook Notifications (Recommended)Copy URL

Set up webhooks to receive real-time refund status updates:

Key webhook events:

• refund_sent: Refund successfully processed and sent to customer
• refund_failed: Refund processing failed
• refund_pending: Refund request created, awaiting processing

Handle Refund Status UpdatesCopy URL

Configure your systems to handle different refund outcomes:

Successful Refunds (SENT):

• Update your internal systems to reflect completed refund
• Send confirmation notification to customer
• Update order/transaction status

Failed Refunds (FAILED):

• Review error details in the refund response
• Determine if retry is appropriate
• Consider alternative refund methods
• Notify customer of the issue

Pending Refunds (PENDING):

• Receive real-time async updates on refund payment status via webhooks
• In the unlikely event that payments remain in a 'pending' status, Banked will raise an internal support ticket to request an updated status from the relevant NPP Participant or Connected Institution

Refund ExpirationCopy URL

All refunds include an expiration timestamp in the response. Use this to track and manage pending refunds that may need attention.

Step 6: Error HandlingCopy URL

Implement robust error handling for common refund scenarios

Step 7: Go LiveCopy URL

Pre-Launch ChecklistCopy URL

• [ ] Confirm refund capabilities enabled on your merchant account
• [ ] Verify mandate setup (for mandate refunds) or Float account eligibility (for A2A)
• [ ] Set up webhook endpoints for refund notifications
• [ ] Test refund flow in sandbox environment
• [ ] Implement proper error handling for all refund scenarios
• [ ] Set up monitoring for refund success rates
• [ ] Test partial refund scenarios

Next StepsCopy URL

Now that you've completed your first refund integration, explore these resources:

• Common Refund Scenarios - Examples of common refund patterns
• Refund States - Understand all possible refund states and transitions
• Refund Webhooks - Set up real-time refund notifications
• Refund Errors - Comprehensive error handling guide