Skip to content
ShaBaas Pay / Docs
Payment Initiation

Initiate PayTo Payment Request

Initiate a payment against an active payment agreement.

Idempotency-Key and merchant_reference are optional.

Error Codes

CodeStatusReasonWhat to do
PAM_SB_PAG_NOT_FOUND_ERROR404Payment agreement not foundVerify payment_agreement_id and merchant ownership.
PAS_AGREEMENT_STATUS_INACTIVE422Agreement is not activeActivate agreement before initiating payment.
PAS_AGREEMENT_ENDED400Agreement end date has passedUse a valid active agreement.
PAS_AGREEMENT_NOT_STARTED400Agreement start date is in futureRetry after agreement start date.
PAS_PAYMENT_TOO_SOON400Execution window/cooldown not metWait and retry after the cooldown window.
PAS_MAX_AMT_EXCEEDED400Amount exceeds agreement max amountLower amount or amend agreement limits.
R804422Duplicate/too-soon payment initiation detectedWait for cooldown window and retry once eligible.
R101422Amount exceeds per-transaction/agreement limitReduce amount to allowed limit.
R102422Daily spend limit exceededRetry next cycle or reduce amount.
R100422Daily transaction count limit exceededRetry next day or after account review.
R103422Destination payout not allowed for merchant settingsEnable eligible payout settings or remove destination.
R803422Upstream initiation failedRetry; if persistent, contact support with request metadata.
PAS_NPP_GATEWAY_ERROR502Provider gateway returned an errorRetry with backoff; contact support if repeated.
PAS_NPP_GATEWAY_TIMEOUT504Provider gateway timeoutRetry request and check status afterwards.
R805200Upstream timeout with accepted processing statePoll status using get endpoint until terminal state. A request without Idempotency-Key keeps this result.
invalid_idempotency_key400Idempotency-Key is present but has the wrong shapeUse 16 to 128 characters: letters, numbers, ., _, :, or -.
idempotency_conflict409This key was already used for a different request bodyRepeat the original body, or send a new key for a new payment.
—202Payment result is not known yetReuse the same Idempotency-Key and merchant_reference. Do not create a new payment.
CREDITS_EXHAUSTED402Developer credits exhaustedTop up developer credits and retry.
post/api/public/payment_initiation

Initiate PayTo Payment Request

Initiate a payment against an active payment agreement.

Idempotency-Key and merchant_reference are optional.

Error Codes

CodeStatusReasonWhat to do
PAM_SB_PAG_NOT_FOUND_ERROR404Payment agreement not foundVerify payment_agreement_id and merchant ownership.
PAS_AGREEMENT_STATUS_INACTIVE422Agreement is not activeActivate agreement before initiating payment.
PAS_AGREEMENT_ENDED400Agreement end date has passedUse a valid active agreement.
PAS_AGREEMENT_NOT_STARTED400Agreement start date is in futureRetry after agreement start date.
PAS_PAYMENT_TOO_SOON400Execution window/cooldown not metWait and retry after the cooldown window.
PAS_MAX_AMT_EXCEEDED400Amount exceeds agreement max amountLower amount or amend agreement limits.
R804422Duplicate/too-soon payment initiation detectedWait for cooldown window and retry once eligible.
R101422Amount exceeds per-transaction/agreement limitReduce amount to allowed limit.
R102422Daily spend limit exceededRetry next cycle or reduce amount.
R100422Daily transaction count limit exceededRetry next day or after account review.
R103422Destination payout not allowed for merchant settingsEnable eligible payout settings or remove destination.
R803422Upstream initiation failedRetry; if persistent, contact support with request metadata.
PAS_NPP_GATEWAY_ERROR502Provider gateway returned an errorRetry with backoff; contact support if repeated.
PAS_NPP_GATEWAY_TIMEOUT504Provider gateway timeoutRetry request and check status afterwards.
R805200Upstream timeout with accepted processing statePoll status using get endpoint until terminal state. A request without Idempotency-Key keeps this result.
invalid_idempotency_key400Idempotency-Key is present but has the wrong shapeUse 16 to 128 characters: letters, numbers, ., _, :, or -.
idempotency_conflict409This key was already used for a different request bodyRepeat the original body, or send a new key for a new payment.
—202Payment result is not known yetReuse the same Idempotency-Key and merchant_reference. Do not create a new payment.
CREDITS_EXHAUSTED402Developer credits exhaustedTop up developer credits and retry.

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-KeyheaderOptional

When sent, persist it and reuse the same value with the same body.

stringminLength: 16maxLength: 128pattern: ^[A-Za-z0-9._:-]{16,128}$
Example
"payment-invoice-4201-v1"

Request Body

Required
application/json
object

Properties

payment_initiationRequiredobject

Request payload used to initiate a payment against an active agreement.

object

Properties

payment_agreement_idRequiredstring

Existing active payment agreement identifier.

string
Example
"3652PA20260428120000123"
amountRequired

Debit amount to initiate for this request.

oneOf

number
string
Example
"10.00"
merchant_referenceOptionalstring

Optional merchant reference for this payment. Send it with Idempotency-Key when the caller has one.

stringminLength: 1maxLength: 128
Example
"invoice-4201"
notesOptionalstring

Optional note attached to the initiation.

stringmaxLength: 140
Example
"Invoice 1042"
descriptionOptionalstring

Ignored by the API; use notes for optional text.

string
Example
"(ignored)"
minimal
{
  "payment_initiation": {
    "payment_agreement_id": "3652PA20260408123221550",
    "amount": "10.00"
  }
}
With optional note
{
  "payment_initiation": {
    "payment_agreement_id": "3652PA20260408123221550",
    "amount": 10,
    "notes": "Invoice 1042"
  }
}
Optional key and merchant reference
{
  "payment_initiation": {
    "payment_agreement_id": "3652PA20260408123221550",
    "amount": "50.00",
    "merchant_reference": "invoice-4201",
    "notes": "Invoice 4201"
  }
}

Responses

200Payment initiation created successfully (or accepted for processing).
application/json

Standard success envelope for payment initiation APIs.

object

Properties

messageOptionalstring

Human-readable outcome message.

string
Example
"Success"
dataOptionalobject

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
Initiation accepted
{
  "message": "Success",
  "data": {
    "payment_initiation_id": "12345PI1714316400",
    "settled": false,
    "status": "accp",
    "transfer": null,
    "created_at": "2026-04-28T13:45:00.000Z"
  }
}
Accepted with timeout notice
{
  "message": "Payment request accepted and processing is pending",
  "data": {
    "payment_initiation_id": "12345PI1714316400",
    "settled": false,
    "status": "accp",
    "transfer": null,
    "created_at": "2026-04-28T13:45:00.000Z"
  }
}
202`Retry-After` is 5 seconds. Repeat the same key and body. Do not create a new payment.
application/json

Standard success envelope for payment initiation APIs.

object

Properties

messageOptionalstring

Human-readable outcome message.

string
Example
"Success"
dataOptionalobject

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
Original operation is still pending
{
  "message": "Payment outcome pending; retrieve the original operation",
  "data": {
    "payment_initiation_id": "12345PI1714316400",
    "amount": "50.00",
    "currency": "AUD",
    "settled": false,
    "status": "initiated",
    "operation_id": "op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44",
    "merchant_reference": "invoice-4201",
    "state_version": 1,
    "created_at": "2026-04-28T13:45:00.000Z"
  }
}
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-28T13:45:00.000Z"
  }
}
402Developer credit balance is insufficient for this operation.
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.

developer_credits
{
  "message": "Developer credits exhausted",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-10T12:00:00.000Z"
  }
}
404Referenced payment agreement 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.

agreement_missing
{
  "message": "MONOOVA-monoova.PAM_SB_PAG_NOT_FOUND_ERROR",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-10T12:00:00.000Z"
  }
}
408Upstream timeout while initiating payment.
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.

422Agreement inactive, limits exceeded, cooldown violation, other business errors.
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.

Agreement exists but is not active
{
  "message": "MONOOVA-monoova.PAS_AGREEMENT_STATUS_INACTIVE",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-10T12:00:00.000Z"
  }
}
Too soon vs recent initiation (example code)
{
  "message": "MONOOVA-monoova.R804",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-10T12:00:00.000Z"
  }
}
Amount exceeds agreement or per-tx cap (example)
{
  "message": "MONOOVA-monoova.R101",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-10T12:00:00.000Z"
  }
}
Initiation failed at scheme (representative)
{
  "message": "MONOOVA-monoova.R803",
  "error_code": "GN-0000",
  "data": {
    "response_time": "2026-04-10T12: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": {
      "post": {
        "tags": [
          "Payment Initiation"
        ],
        "summary": "Initiate PayTo Payment Request",
        "operationId": "createPaymentInitiation",
        "description": "Initiate a payment against an active payment agreement.\n\n`Idempotency-Key` and `merchant_reference` are optional.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify `payment_agreement_id` and merchant ownership. |\n| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |\n| PAS_AGREEMENT_ENDED | 400 | Agreement end date has passed | Use a valid active agreement. |\n| PAS_AGREEMENT_NOT_STARTED | 400 | Agreement start date is in future | Retry after agreement start date. |\n| PAS_PAYMENT_TOO_SOON | 400 | Execution window/cooldown not met | Wait and retry after the cooldown window. |\n| PAS_MAX_AMT_EXCEEDED | 400 | Amount exceeds agreement max amount | Lower amount or amend agreement limits. |\n| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |\n| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce `amount` to allowed limit. |\n| R102 | 422 | Daily spend limit exceeded | Retry next cycle or reduce amount. |\n| R100 | 422 | Daily transaction count limit exceeded | Retry next day or after account review. |\n| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |\n| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |\n| PAS_NPP_GATEWAY_ERROR | 502 | Provider gateway returned an error | Retry with backoff; contact support if repeated. |\n| PAS_NPP_GATEWAY_TIMEOUT | 504 | Provider gateway timeout | Retry request and check status afterwards. |\n| R805 | 200 | Upstream timeout with accepted processing state | Poll status using get endpoint until terminal state. A request without `Idempotency-Key` keeps this result. |\n| invalid_idempotency_key | 400 | `Idempotency-Key` is present but has the wrong shape | Use 16 to 128 characters: letters, numbers, `.`, `_`, `:`, or `-`. |\n| idempotency_conflict | 409 | This key was already used for a different request body | Repeat the original body, or send a new key for a new payment. |\n| — | 202 | Payment result is not known yet | Reuse the same `Idempotency-Key` and `merchant_reference`. Do not create a new payment. |\n| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |\n",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]{16,128}$"
            },
            "description": "When sent, persist it and reuse the same value with the same body.\n",
            "example": "payment-invoice-4201-v1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payment_initiation"
                ],
                "properties": {
                  "payment_initiation": {
                    "$ref": "#/components/schemas/CreatePaymentInitiationRequest"
                  }
                }
              },
              "examples": {
                "minimal": {
                  "value": {
                    "payment_initiation": {
                      "payment_agreement_id": "3652PA20260408123221550",
                      "amount": "10.00"
                    }
                  }
                },
                "with_notes": {
                  "summary": "With optional note",
                  "value": {
                    "payment_initiation": {
                      "payment_agreement_id": "3652PA20260408123221550",
                      "amount": 10,
                      "notes": "Invoice 1042"
                    }
                  }
                },
                "with_idempotency": {
                  "summary": "Optional key and merchant reference",
                  "value": {
                    "payment_initiation": {
                      "payment_agreement_id": "3652PA20260408123221550",
                      "amount": "50.00",
                      "merchant_reference": "invoice-4201",
                      "notes": "Invoice 4201"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment initiation created successfully (or accepted for processing).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessPaymentInitiationResponse"
                },
                "examples": {
                  "created": {
                    "summary": "Initiation accepted",
                    "value": {
                      "message": "Success",
                      "data": {
                        "payment_initiation_id": "12345PI1714316400",
                        "settled": false,
                        "status": "accp",
                        "transfer": null,
                        "created_at": "2026-04-28T13:45:00.000Z"
                      }
                    }
                  },
                  "timeout_accepted": {
                    "summary": "Accepted with timeout notice",
                    "value": {
                      "message": "Payment request accepted and processing is pending",
                      "data": {
                        "payment_initiation_id": "12345PI1714316400",
                        "settled": false,
                        "status": "accp",
                        "transfer": null,
                        "created_at": "2026-04-28T13:45:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "`Retry-After` is 5 seconds. Repeat the same key and body. Do not create a new payment.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds to wait before repeating the same request.",
                "example": "5"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessPaymentInitiationResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "Original operation is still pending",
                    "value": {
                      "message": "Payment outcome pending; retrieve the original operation",
                      "data": {
                        "payment_initiation_id": "12345PI1714316400",
                        "amount": "50.00",
                        "currency": "AUD",
                        "settled": false,
                        "status": "initiated",
                        "operation_id": "op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44",
                        "merchant_reference": "invoice-4201",
                        "state_version": 1,
                        "created_at": "2026-04-28T13:45:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "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-28T13:45:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Developer credit balance is insufficient for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "developer_credits": {
                    "value": {
                      "message": "Developer credits exhausted",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-10T12:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Referenced payment agreement was not found for this merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "agreement_missing": {
                    "value": {
                      "message": "MONOOVA-monoova.PAM_SB_PAG_NOT_FOUND_ERROR",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-10T12:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "408": {
            "description": "Upstream timeout while initiating payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Agreement inactive, limits exceeded, cooldown violation, other business errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "agreement_inactive": {
                    "summary": "Agreement exists but is not active",
                    "value": {
                      "message": "MONOOVA-monoova.PAS_AGREEMENT_STATUS_INACTIVE",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-10T12:00:00.000Z"
                      }
                    }
                  },
                  "cooldown": {
                    "summary": "Too soon vs recent initiation (example code)",
                    "value": {
                      "message": "MONOOVA-monoova.R804",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-10T12:00:00.000Z"
                      }
                    }
                  },
                  "amount_limit": {
                    "summary": "Amount exceeds agreement or per-tx cap (example)",
                    "value": {
                      "message": "MONOOVA-monoova.R101",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-10T12:00:00.000Z"
                      }
                    }
                  },
                  "monoova_failed": {
                    "summary": "Initiation failed at scheme (representative)",
                    "value": {
                      "message": "MONOOVA-monoova.R803",
                      "error_code": "GN-0000",
                      "data": {
                        "response_time": "2026-04-10T12:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreatePaymentInitiationRequest": {
        "type": "object",
        "description": "Request payload used to initiate a payment against an active agreement.",
        "required": [
          "payment_agreement_id",
          "amount"
        ],
        "properties": {
          "payment_agreement_id": {
            "type": "string",
            "description": "Existing active payment agreement identifier.",
            "example": "3652PA20260428120000123"
          },
          "amount": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Debit amount to initiate for this request.",
            "example": "10.00"
          },
          "merchant_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Optional merchant reference for this payment. Send it with `Idempotency-Key` when the caller has one.\n",
            "example": "invoice-4201"
          },
          "notes": {
            "type": "string",
            "maxLength": 140,
            "description": "Optional note attached to the initiation.",
            "example": "Invoice 1042"
          },
          "description": {
            "type": "string",
            "description": "Ignored by the API; use `notes` for optional text.",
            "example": "(ignored)"
          }
        }
      },
      "SuccessPaymentInitiationResponse": {
        "type": "object",
        "description": "Standard success envelope for payment initiation APIs.",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable outcome message.",
            "example": "Success"
          },
          "data": {
            "$ref": "#/components/schemas/PaymentInitiation"
          }
        }
      },
      "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