Getting Started with Refunds

Whether you're implementing mandated 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 National Australia Bank (NAB) account (see Step 2)

API Request HeadersCopy URL

All refund API requests require these headers:

{
  "Authorization": "Basic <base64_encoded_credentials>",
  "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:

Mandated RefundsCopy URL

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

Account-to-Account RefundsCopy URL

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

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.

Option A: Mandated RefundsCopy URL

This section details the process for initiating a refund using a mandate token.

Use the POST /v3/refunds endpoint to initiate the refund.

Initiate Refund Request:

curl --location --request POST 'https://api.banked.com/v3/refunds' \
--header 'Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)' \
--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"
    }
  }
}'

Key parameters for mandated refunds:

• processing_method.method_type: Set to "MANDATE"
• processing_method.mandate.token: Your pre-established refund mandate token

Example Response (Success - 201 Created):

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

Option B: Account-to-Account RefundsCopy URL

This section details the process for initiating a refund using an eligible NAB account.

Use the POST /v3/refunds endpoint to initiate the refund.

curl --location --request POST 'https://api.banked.com/v3/refunds' \
--header 'Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)' \
--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"
    }
  }
}'

Key parameters for A2A refunds:

• processing_method.method_type: Set to "ACCOUNT_TO_ACCOUNT"
• processing_method.debtor_account: Specify your eligible NAB account details
• debtor_account.bank_account_id: Your NAB account ID (must be eligible for refunds)

Example Response (Success - 201 Created):

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

Mandate Refund Example:

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

Account-to-Account Refund Example:

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

Unlike payments, refunds do not require explicit authorization. The Banked system automatically authorizes refunds based on the provided mandate token (for mandated refunds) or the eligible NAB account (for account-to-account refunds).

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: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)'

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):

• Monitor pending refunds regularly
• Follow up with customers if refunds are not processed within expected timeframes

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 mandated refunds) or NAB 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