Skip to content
ShaBaas Pay / Docs
Payment Initiation

Refund a settled payment

Refund part or all of a settled payment that belongs to the authenticated merchant. Send the bearer token from POST /api/public/authorization. Do not send the raw API key.

Generate a new Idempotency-Key for each refund attempt, for example a UUID. Sending the same key again for this payment returns the original refund and does not pay the customer again, even if amount is different. A second partial refund needs a new key. Using the same key on a different payment returns 409. A failed refund stays tied to that key. To try again, send a new key.

The payment must already be settled. acsc with settled: false is not refundable yet. The payer must still have a saved BSB or PayID. Inbound PayID, destination, bookkeeper, settlement, and redeem rows are refused.

Developer credits are checked only outside production, and only for a developer merchant when credit limits are configured. One credit is taken after a new Ok or Pending result. A replay and a Failed result do not take a credit.

Error Codes

CodeStatusReasonWhat to do
GN-0000422Idempotency-Key is missingSend a client-generated key, such as a UUID.
GN-0000404Payment initiation not found for this merchantUse a payment_initiation_id owned by the token's merchant.
PI-0003422Amount is zero or negativeSend a positive dollar amount.
PI-0002422Payment cannot be refunded, or the amount is above the remainderConfirm the payment is settled, has no destination, and the payer still has an account. Lower the amount to the remainder.
GN-0000422Already refundedThe full payment amount is already reserved by Ok and Pending refunds.
GN-0000422Refund wallet not foundThe merchant ledger wallet is missing.
GN-0000422Not enough balance to refundRetry later. The platform balance does not cover this amount.
GN-0000409This key was already used for a different paymentSend a new Idempotency-Key.
GN-0000402Developer credits exhaustedNon-production only. Top up credits and retry with the same key only if no refund row was created.
Provider code422The scheme rejected the refundRead message and error_code. Retry only with a new Idempotency-Key.
post/api/public/payment_initiation/refund

Refund a settled payment

Refund part or all of a settled payment that belongs to the authenticated merchant. Send the bearer token from POST /api/public/authorization. Do not send the raw API key.

Generate a new Idempotency-Key for each refund attempt, for example a UUID. Sending the same key again for this payment returns the original refund and does not pay the customer again, even if amount is different. A second partial refund needs a new key. Using the same key on a different payment returns 409. A failed refund stays tied to that key. To try again, send a new key.

The payment must already be settled. acsc with settled: false is not refundable yet. The payer must still have a saved BSB or PayID. Inbound PayID, destination, bookkeeper, settlement, and redeem rows are refused.

Developer credits are checked only outside production, and only for a developer merchant when credit limits are configured. One credit is taken after a new Ok or Pending result. A replay and a Failed result do not take a credit.

Error Codes

CodeStatusReasonWhat to do
GN-0000422Idempotency-Key is missingSend a client-generated key, such as a UUID.
GN-0000404Payment initiation not found for this merchantUse a payment_initiation_id owned by the token's merchant.
PI-0003422Amount is zero or negativeSend a positive dollar amount.
PI-0002422Payment cannot be refunded, or the amount is above the remainderConfirm the payment is settled, has no destination, and the payer still has an account. Lower the amount to the remainder.
GN-0000422Already refundedThe full payment amount is already reserved by Ok and Pending refunds.
GN-0000422Refund wallet not foundThe merchant ledger wallet is missing.
GN-0000422Not enough balance to refundRetry later. The platform balance does not cover this amount.
GN-0000409This key was already used for a different paymentSend a new Idempotency-Key.
GN-0000402Developer credits exhaustedNon-production only. Top up credits and retry with the same key only if no refund row was created.
Provider code422The scheme rejected the refundRead message and error_code. Retry only with a new Idempotency-Key.

Servers

Staging: https://dev-api.shabaas.com

Production: https://api.shabaas.com

Authentication

BearerAuthAuthorization: Bearer <token>

Bearer token returned by /api/public/authorization.

Parameters

Idempotency-KeyheaderRequired

Client-generated label for this refund attempt. A UUID is suitable. The same value on the same payment returns the stored refund and does not send money again.

string

Request Body

Required
application/json
object

Properties

payment_initiationRequiredobject
object

Properties

payment_initiation_idRequiredstring

Settled payment initiation that belongs to the authenticated merchant.

string
Example
"12345PI1714316400"
amountRequired

Dollars to refund. May be a partial amount up to the remainder.

oneOf

string
number
Example
"1.00"
notesOptionalstring

Optional reason stored on the refund.

string
Example
"Customer requested a refund"
Partial refund
{
  "payment_initiation": {
    "payment_initiation_id": "12345PI1714316400",
    "amount": "1.00",
    "notes": "Customer requested a refund"
  }
}
Refund the remaining amount
{
  "payment_initiation": {
    "payment_initiation_id": "12345PI1714316400",
    "amount": "10.00"
  }
}

Responses

200Refund completed (`Ok`) or accepted and still in progress (`Pending`). Repeating the same `Idempotency-Key` also returns `200` with the original refund.
application/json

Payment initiation envelope plus the refund created or replayed by this call. data.refund is that one refund. data.refunds lists every refund on the payment.

object

Properties

messageOptionalstring
string
Example
"Success"
dataOptional

allOf

Payment initiation object returned by create/get initiation APIs.

object

Properties

payment_initiation_idOptionalstring

Unique payment initiation identifier.

string
Example
"12345PI1714316400"
payment_agreement_idOptionalstring

Linked payment agreement identifier.

string
Example
"3652PA20260428120000123"
amountOptional

Debit amount for this initiation.

oneOf

string
number
Example
"10.00"
currencyOptionalstring

Currency of this initiation.

string
Example
"AUD"
operation_idOptionalstring

Present when the request included Idempotency-Key. Use it to retrieve the original operation.

string · nullable
Example
"op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"
merchant_referenceOptionalstring

Merchant reference stored with the idempotency key. Null when the request omitted it.

string · nullable
Example
"invoice-4201"
state_versionOptionalinteger

Monotonic version of this payment record.

integer
Example
1
statusOptionalstring

Current initiation processing status.

string
Example
"accp"
created_atOptionalstring

Initiation creation timestamp in ISO8601 format.

stringformat: date-time
Example
"2026-04-28T13:45:00.000Z"
settledOptionalboolean

Indicates whether the initiation has settled.

boolean
Example
false
transferOptionalstring

Transfer state/classification when available.

string · nullable
Example
null
failure_codeOptionalstring

Provider/business failure code.

string
Example
"R803"
messageOptionalstring

Failure or status message supplied by processing system.

string
Example
"Similar payment attempted within last 24 hours"
split_percentage_feeOptionalnumber

Bookkeeper retain percentage when set (greater than 0 and less than 100). Retained share stays on the business ledger for end-of-day transfer.

number · nullable
Example
20
refund_amountOptionalstring

Total of Ok and Pending refunds reserved against this payment. Null when no refund has reserved an amount.

string · nullable
Example
"1.0"
refundsOptionalarray

Refunds for this payment, oldest first. Empty when none exist.

array
Array item schema

One refund of a payment initiation.

object

Properties

idOptionalinteger

Refund row id.

integer
Example
41
amountOptionalstring

Dollars sent, or reserved, for this refund.

string
Example
"1.0"
statusOptionalstring

Ok is paid. Pending is still in progress. Failed did not pay the customer.

string
Example
"Ok"
notesOptionalstring

Caller-supplied reason. Scheme errors are not stored here.

string · nullable
Example
"Customer requested a refund"
created_atOptionalstring
stringformat: date-time
Example
"2026-04-28T15:00:00.000Z"
completed_atOptionalstring

Reserved timestamp. Currently null even when status is Ok.

string · nullableformat: date-time
Example
null
transaction_idOptionalstring

Scheme transaction id once the refund is accepted.

string · nullable
Example
"90010001"
failure_codeOptionalstring

Scheme failure code. Null on Ok and Pending.

string · nullable
failure_messageOptionalstring

Scheme failure message. Null on Ok and Pending.

string · nullable
object

Properties

refundOptionalobject

One refund of a payment initiation.

object

Properties

idOptionalinteger

Refund row id.

integer
Example
41
amountOptionalstring

Dollars sent, or reserved, for this refund.

string
Example
"1.0"
statusOptionalstring

Ok is paid. Pending is still in progress. Failed did not pay the customer.

string
Example
"Ok"
notesOptionalstring

Caller-supplied reason. Scheme errors are not stored here.

string · nullable
Example
"Customer requested a refund"
created_atOptionalstring
stringformat: date-time
Example
"2026-04-28T15:00:00.000Z"
completed_atOptionalstring

Reserved timestamp. Currently null even when status is Ok.

string · nullableformat: date-time
Example
null
transaction_idOptionalstring

Scheme transaction id once the refund is accepted.

string · nullable
Example
"90010001"
failure_codeOptionalstring

Scheme failure code. Null on Ok and Pending.

string · nullable
failure_messageOptionalstring

Scheme failure message. Null on Ok and Pending.

string · nullable
Refund paid immediately
{
  "message": "Success",
  "data": {
    "payment_initiation_id": "12345PI1714316400",
    "status": "return_complete",
    "created_at": "2026-04-28T13:45:00.000Z",
    "settled": true,
    "transfer": "transferred",
    "split_percentage_fee": null,
    "refund_amount": "1.0",
    "refunds": [
      {
        "id": 41,
        "amount": "1.0",
        "status": "Ok",
        "notes": "Customer requested a refund",
        "created_at": "2026-04-28T15:00:00.000Z",
        "completed_at": null,
        "transaction_id": "90010001",
        "failure_code": null,
        "failure_message": null
      }
    ],
    "refund": {
      "id": 41,
      "amount": "1.0",
      "status": "Ok",
      "notes": "Customer requested a refund",
      "created_at": "2026-04-28T15:00:00.000Z",
      "completed_at": null,
      "transaction_id": "90010001",
      "failure_code": null,
      "failure_message": null
    }
  }
}
Refund accepted and still in progress
{
  "message": "Success",
  "data": {
    "payment_initiation_id": "12345PI1714316400",
    "status": "return_in_progress",
    "created_at": "2026-04-28T13:45:00.000Z",
    "settled": true,
    "transfer": "transferred",
    "split_percentage_fee": null,
    "refund_amount": "1.0",
    "refunds": [
      {
        "id": 42,
        "amount": "1.0",
        "status": "Pending",
        "notes": "Customer requested a refund",
        "created_at": "2026-04-28T15:05:00.000Z",
        "completed_at": null,
        "transaction_id": null,
        "failure_code": null,
        "failure_message": null
      }
    ],
    "refund": {
      "id": 42,
      "amount": "1.0",
      "status": "Pending",
      "notes": "Customer requested a refund",
      "created_at": "2026-04-28T15:05:00.000Z",
      "completed_at": null,
      "transaction_id": null,
      "failure_code": null,
      "failure_message": null
    }
  }
}
401Invalid or missing bearer token.
application/json
object

Properties

messageRequiredstring
string
Example
"Payee account cannot receive NPP Payments"
error_codeRequiredstring
string
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"
dataRequiredobject
object
Example
{
  "response_time": "2026-04-08T12:28:26.759Z"
}

Additional properties are supported; see the endpoint definition for their schema.

Authorization failed
{
  "message": "Unauthorized Access to an operation",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
402Developer credit balance is insufficient. Applies only outside production.
application/json
object

Properties

messageRequiredstring
string
Example
"Payee account cannot receive NPP Payments"
error_codeRequiredstring
string
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"
dataRequiredobject
object
Example
{
  "response_time": "2026-04-08T12:28:26.759Z"
}

Additional properties are supported; see the endpoint definition for their schema.

Non-production credits exhausted
{
  "message": "Developer credits exhausted",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
404Payment initiation was not found for this merchant.
application/json
object

Properties

messageRequiredstring
string
Example
"Payee account cannot receive NPP Payments"
error_codeRequiredstring
string
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"
dataRequiredobject
object
Example
{
  "response_time": "2026-04-08T12:28:26.759Z"
}

Additional properties are supported; see the endpoint definition for their schema.

Unknown id or another merchant's payment
{
  "message": "Payment Initiation not found",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
409This Idempotency-Key already belongs to a different payment for this merchant.
application/json
object

Properties

messageRequiredstring
string
Example
"Payee account cannot receive NPP Payments"
error_codeRequiredstring
string
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"
dataRequiredobject
object
Example
{
  "response_time": "2026-04-08T12:28:26.759Z"
}

Additional properties are supported; see the endpoint definition for their schema.

Key reused on another payment
{
  "message": "Idempotency-Key was already used for a different payment",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
422The refund was refused or the scheme rejected it. The same key will not try the payment again.
application/json
object

Properties

messageRequiredstring
string
Example
"Payee account cannot receive NPP Payments"
error_codeRequiredstring
string
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"
dataRequiredobject
object
Example
{
  "response_time": "2026-04-08T12:28:26.759Z"
}

Additional properties are supported; see the endpoint definition for their schema.

Idempotency-Key header omitted
{
  "message": "Idempotency-Key is required",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
Amount is zero or negative
{
  "message": "Invalid amount for refund",
  "error_code": "PI-0003",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
Unsettled, ineligible, or amount above the remainder
{
  "message": "Payment Initiation cannot be refunded",
  "error_code": "PI-0002",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
Nothing remains to refund
{
  "message": "Already refunded",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
Scheme rejected the refund
{
  "message": "Refund failed",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-28T15:00:00.000Z"
  }
}
Full endpoint OpenAPI definition
{
  "openapi": "3.0.3",
  "info": {
    "title": "ShaBaasPay Public API",
    "version": "1.0.0",
    "description": "Describes public REST endpoints for authorization, payment agreements, payment initiations,\nrefunds, webhooks, and PayID collection APIs.\n"
  },
  "servers": [
    {
      "url": "https://dev-api.shabaas.com",
      "description": "Staging"
    },
    {
      "url": "https://api.shabaas.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Payment Initiation",
      "x-displayName": "Payment Initiation",
      "description": "Create and retrieve payment initiations, and refund a settled payment that belongs to the authenticated merchant."
    }
  ],
  "x-tagGroups": [
    {
      "name": "SHABAASPAY PUBLIC API",
      "tags": [
        "API Keys",
        "Payment Agreement",
        "Payment Initiation",
        "Checkout",
        "B2B Collections",
        "Webhooks"
      ]
    },
    {
      "name": "Internal",
      "tags": [
        "Clients"
      ]
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/public/payment_initiation/refund": {
      "post": {
        "tags": [
          "Payment Initiation"
        ],
        "summary": "Refund a settled payment",
        "operationId": "refundPaymentInitiation",
        "description": "Refund part or all of a settled payment that belongs to the authenticated merchant.\nSend the bearer token from `POST /api/public/authorization`. Do not send the raw API key.\n\nGenerate a new `Idempotency-Key` for each refund attempt, for example a UUID.\nSending the same key again for this payment returns the original refund and does not pay the customer again, even if `amount` is different.\nA second partial refund needs a new key. Using the same key on a different payment returns `409`.\nA failed refund stays tied to that key. To try again, send a new key.\n\nThe payment must already be settled. `acsc` with `settled: false` is not refundable yet.\nThe payer must still have a saved BSB or PayID. Inbound PayID, destination, bookkeeper, settlement, and redeem rows are refused.\n\nDeveloper credits are checked only outside production, and only for a developer merchant when credit limits are configured.\nOne credit is taken after a new `Ok` or `Pending` result. A replay and a `Failed` result do not take a credit.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| GN-0000 | 422 | `Idempotency-Key` is missing | Send a client-generated key, such as a UUID. |\n| GN-0000 | 404 | Payment initiation not found for this merchant | Use a `payment_initiation_id` owned by the token's merchant. |\n| PI-0003 | 422 | Amount is zero or negative | Send a positive dollar amount. |\n| PI-0002 | 422 | Payment cannot be refunded, or the amount is above the remainder | Confirm the payment is settled, has no destination, and the payer still has an account. Lower the amount to the remainder. |\n| GN-0000 | 422 | Already refunded | The full payment amount is already reserved by `Ok` and `Pending` refunds. |\n| GN-0000 | 422 | Refund wallet not found | The merchant ledger wallet is missing. |\n| GN-0000 | 422 | Not enough balance to refund | Retry later. The platform balance does not cover this amount. |\n| GN-0000 | 409 | This key was already used for a different payment | Send a new `Idempotency-Key`. |\n| GN-0000 | 402 | Developer credits exhausted | Non-production only. Top up credits and retry with the same key only if no refund row was created. |\n| Provider code | 422 | The scheme rejected the refund | Read `message` and `error_code`. Retry only with a new `Idempotency-Key`. |\n",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client-generated label for this refund attempt. A UUID is suitable.\nThe same value on the same payment returns the stored refund and does not send money again.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRefundRequest"
              },
              "examples": {
                "partial": {
                  "summary": "Partial refund",
                  "value": {
                    "payment_initiation": {
                      "payment_initiation_id": "12345PI1714316400",
                      "amount": "1.00",
                      "notes": "Customer requested a refund"
                    }
                  }
                },
                "remainder": {
                  "summary": "Refund the remaining amount",
                  "value": {
                    "payment_initiation": {
                      "payment_initiation_id": "12345PI1714316400",
                      "amount": "10.00"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refund completed (`Ok`) or accepted and still in progress (`Pending`).\nRepeating the same `Idempotency-Key` also returns `200` with the original refund.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessRefundResponse"
                },
                "examples": {
                  "completed": {
                    "summary": "Refund paid immediately",
                    "value": {
                      "message": "Success",
                      "data": {
                        "payment_initiation_id": "12345PI1714316400",
                        "status": "return_complete",
                        "created_at": "2026-04-28T13:45:00.000Z",
                        "settled": true,
                        "transfer": "transferred",
                        "split_percentage_fee": null,
                        "refund_amount": "1.0",
                        "refunds": [
                          {
                            "id": 41,
                            "amount": "1.0",
                            "status": "Ok",
                            "notes": "Customer requested a refund",
                            "created_at": "2026-04-28T15:00:00.000Z",
                            "completed_at": null,
                            "transaction_id": "90010001",
                            "failure_code": null,
                            "failure_message": null
                          }
                        ],
                        "refund": {
                          "id": 41,
                          "amount": "1.0",
                          "status": "Ok",
                          "notes": "Customer requested a refund",
                          "created_at": "2026-04-28T15:00:00.000Z",
                          "completed_at": null,
                          "transaction_id": "90010001",
                          "failure_code": null,
                          "failure_message": null
                        }
                      }
                    }
                  },
                  "pending": {
                    "summary": "Refund accepted and still in progress",
                    "value": {
                      "message": "Success",
                      "data": {
                        "payment_initiation_id": "12345PI1714316400",
                        "status": "return_in_progress",
                        "created_at": "2026-04-28T13:45:00.000Z",
                        "settled": true,
                        "transfer": "transferred",
                        "split_percentage_fee": null,
                        "refund_amount": "1.0",
                        "refunds": [
                          {
                            "id": 42,
                            "amount": "1.0",
                            "status": "Pending",
                            "notes": "Customer requested a refund",
                            "created_at": "2026-04-28T15:05:00.000Z",
                            "completed_at": null,
                            "transaction_id": null,
                            "failure_code": null,
                            "failure_message": null
                          }
                        ],
                        "refund": {
                          "id": 42,
                          "amount": "1.0",
                          "status": "Pending",
                          "notes": "Customer requested a refund",
                          "created_at": "2026-04-28T15:05:00.000Z",
                          "completed_at": null,
                          "transaction_id": null,
                          "failure_code": null,
                          "failure_message": null
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Authorization failed",
                    "value": {
                      "message": "Unauthorized Access to an operation",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Developer credit balance is insufficient. Applies only outside production.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "developer_credits": {
                    "summary": "Non-production credits exhausted",
                    "value": {
                      "message": "Developer credits exhausted",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Payment initiation was not found for this merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "not_found": {
                    "summary": "Unknown id or another merchant's payment",
                    "value": {
                      "message": "Payment Initiation not found",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "This Idempotency-Key already belongs to a different payment for this merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "key_conflict": {
                    "summary": "Key reused on another payment",
                    "value": {
                      "message": "Idempotency-Key was already used for a different payment",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The refund was refused or the scheme rejected it. The same key will not try the payment again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missing_key": {
                    "summary": "Idempotency-Key header omitted",
                    "value": {
                      "message": "Idempotency-Key is required",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  },
                  "invalid_amount": {
                    "summary": "Amount is zero or negative",
                    "value": {
                      "message": "Invalid amount for refund",
                      "error_code": "PI-0003",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  },
                  "not_refundable": {
                    "summary": "Unsettled, ineligible, or amount above the remainder",
                    "value": {
                      "message": "Payment Initiation cannot be refunded",
                      "error_code": "PI-0002",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  },
                  "already_refunded": {
                    "summary": "Nothing remains to refund",
                    "value": {
                      "message": "Already refunded",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  },
                  "scheme_rejected": {
                    "summary": "Scheme rejected the refund",
                    "value": {
                      "message": "Refund failed",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-28T15:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateRefundRequest": {
        "type": "object",
        "required": [
          "payment_initiation"
        ],
        "properties": {
          "payment_initiation": {
            "type": "object",
            "required": [
              "payment_initiation_id",
              "amount"
            ],
            "properties": {
              "payment_initiation_id": {
                "type": "string",
                "description": "Settled payment initiation that belongs to the authenticated merchant.",
                "example": "12345PI1714316400"
              },
              "amount": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ],
                "description": "Dollars to refund. May be a partial amount up to the remainder.",
                "example": "1.00"
              },
              "notes": {
                "type": "string",
                "description": "Optional reason stored on the refund.",
                "example": "Customer requested a refund"
              }
            }
          }
        }
      },
      "SuccessRefundResponse": {
        "type": "object",
        "description": "Payment initiation envelope plus the refund created or replayed by this call.\n`data.refund` is that one refund. `data.refunds` lists every refund on the payment.\n",
        "properties": {
          "message": {
            "type": "string",
            "example": "Success"
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PaymentInitiation"
              },
              {
                "type": "object",
                "properties": {
                  "refund": {
                    "$ref": "#/components/schemas/Refund"
                  }
                }
              }
            ]
          }
        }
      },
      "PaymentInitiation": {
        "type": "object",
        "description": "Payment initiation object returned by create/get initiation APIs.",
        "properties": {
          "payment_initiation_id": {
            "type": "string",
            "description": "Unique payment initiation identifier.",
            "example": "12345PI1714316400"
          },
          "payment_agreement_id": {
            "type": "string",
            "description": "Linked payment agreement identifier.",
            "example": "3652PA20260428120000123"
          },
          "amount": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ],
            "description": "Debit amount for this initiation.",
            "example": "10.00"
          },
          "currency": {
            "type": "string",
            "description": "Currency of this initiation.",
            "example": "AUD"
          },
          "operation_id": {
            "type": "string",
            "nullable": true,
            "description": "Present when the request included `Idempotency-Key`. Use it to retrieve the original operation.\n",
            "example": "op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"
          },
          "merchant_reference": {
            "type": "string",
            "nullable": true,
            "description": "Merchant reference stored with the idempotency key. Null when the request omitted it.",
            "example": "invoice-4201"
          },
          "state_version": {
            "type": "integer",
            "description": "Monotonic version of this payment record.",
            "example": 1
          },
          "status": {
            "type": "string",
            "description": "Current initiation processing status.",
            "example": "accp"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Initiation creation timestamp in ISO8601 format.",
            "example": "2026-04-28T13:45:00.000Z"
          },
          "settled": {
            "type": "boolean",
            "description": "Indicates whether the initiation has settled.",
            "example": false
          },
          "transfer": {
            "type": "string",
            "description": "Transfer state/classification when available.",
            "nullable": true,
            "example": null
          },
          "failure_code": {
            "type": "string",
            "description": "Provider/business failure code.",
            "example": "R803"
          },
          "message": {
            "type": "string",
            "description": "Failure or status message supplied by processing system.",
            "example": "Similar payment attempted within last 24 hours"
          },
          "split_percentage_fee": {
            "type": "number",
            "nullable": true,
            "description": "Bookkeeper retain percentage when set (greater than 0 and less than 100).\nRetained share stays on the business ledger for end-of-day transfer.\n",
            "example": 20
          },
          "refund_amount": {
            "type": "string",
            "nullable": true,
            "description": "Total of `Ok` and `Pending` refunds reserved against this payment.\nNull when no refund has reserved an amount.\n",
            "example": "1.0"
          },
          "refunds": {
            "type": "array",
            "description": "Refunds for this payment, oldest first. Empty when none exist.",
            "items": {
              "$ref": "#/components/schemas/Refund"
            }
          }
        }
      },
      "Refund": {
        "type": "object",
        "description": "One refund of a payment initiation.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Refund row id.",
            "example": 41
          },
          "amount": {
            "type": "string",
            "description": "Dollars sent, or reserved, for this refund.",
            "example": "1.0"
          },
          "status": {
            "type": "string",
            "description": "`Ok` is paid. `Pending` is still in progress. `Failed` did not pay the customer.",
            "example": "Ok"
          },
          "notes": {
            "type": "string",
            "nullable": true,
            "description": "Caller-supplied reason. Scheme errors are not stored here.",
            "example": "Customer requested a refund"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-04-28T15:00:00.000Z"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Reserved timestamp. Currently null even when status is `Ok`.",
            "example": null
          },
          "transaction_id": {
            "type": "string",
            "nullable": true,
            "description": "Scheme transaction id once the refund is accepted.",
            "example": "90010001"
          },
          "failure_code": {
            "type": "string",
            "nullable": true,
            "description": "Scheme failure code. Null on `Ok` and `Pending`."
          },
          "failure_message": {
            "type": "string",
            "nullable": true,
            "description": "Scheme failure message. Null on `Ok` and `Pending`."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "message",
          "error_code",
          "data"
        ],
        "properties": {
          "message": {
            "type": "string",
            "example": "Payee account cannot receive NPP Payments"
          },
          "error_code": {
            "type": "string",
            "example": "MOV_NPP_PAYMENT_NOT_SUPPORTED"
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "response_time": "2026-04-08T12:28:26.759Z"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token returned by `/api/public/authorization`."
      }
    }
  }
}
Download endpoint OpenAPI JSON →
← Back to API Reference