Initiate PayTo Payment Request
Initiate a payment against an active payment agreement.
Idempotency-Key and merchant_reference are optional.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify payment_agreement_id and merchant ownership. |
| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |
| PAS_AGREEMENT_ENDED | 400 | Agreement end date has passed | Use a valid active agreement. |
| PAS_AGREEMENT_NOT_STARTED | 400 | Agreement start date is in future | Retry after agreement start date. |
| PAS_PAYMENT_TOO_SOON | 400 | Execution window/cooldown not met | Wait and retry after the cooldown window. |
| PAS_MAX_AMT_EXCEEDED | 400 | Amount exceeds agreement max amount | Lower amount or amend agreement limits. |
| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |
| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce amount to allowed limit. |
| R102 | 422 | Daily spend limit exceeded | Retry next cycle or reduce amount. |
| R100 | 422 | Daily transaction count limit exceeded | Retry next day or after account review. |
| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |
| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |
| PAS_NPP_GATEWAY_ERROR | 502 | Provider gateway returned an error | Retry with backoff; contact support if repeated. |
| PAS_NPP_GATEWAY_TIMEOUT | 504 | Provider gateway timeout | Retry request and check status afterwards. |
| R805 | 200 | Upstream timeout with accepted processing state | Poll status using get endpoint until terminal state. A request without Idempotency-Key keeps this result. |
| invalid_idempotency_key | 400 | Idempotency-Key is present but has the wrong shape | Use 16 to 128 characters: letters, numbers, ., _, :, or -. |
| 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. |
| — | 202 | Payment result is not known yet | Reuse the same Idempotency-Key and merchant_reference. Do not create a new payment. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
/api/public/payment_initiationInitiate PayTo Payment Request
Initiate a payment against an active payment agreement.
Idempotency-Key and merchant_reference are optional.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify payment_agreement_id and merchant ownership. |
| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |
| PAS_AGREEMENT_ENDED | 400 | Agreement end date has passed | Use a valid active agreement. |
| PAS_AGREEMENT_NOT_STARTED | 400 | Agreement start date is in future | Retry after agreement start date. |
| PAS_PAYMENT_TOO_SOON | 400 | Execution window/cooldown not met | Wait and retry after the cooldown window. |
| PAS_MAX_AMT_EXCEEDED | 400 | Amount exceeds agreement max amount | Lower amount or amend agreement limits. |
| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |
| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce amount to allowed limit. |
| R102 | 422 | Daily spend limit exceeded | Retry next cycle or reduce amount. |
| R100 | 422 | Daily transaction count limit exceeded | Retry next day or after account review. |
| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |
| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |
| PAS_NPP_GATEWAY_ERROR | 502 | Provider gateway returned an error | Retry with backoff; contact support if repeated. |
| PAS_NPP_GATEWAY_TIMEOUT | 504 | Provider gateway timeout | Retry request and check status afterwards. |
| R805 | 200 | Upstream timeout with accepted processing state | Poll status using get endpoint until terminal state. A request without Idempotency-Key keeps this result. |
| invalid_idempotency_key | 400 | Idempotency-Key is present but has the wrong shape | Use 16 to 128 characters: letters, numbers, ., _, :, or -. |
| 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. |
| — | 202 | Payment result is not known yet | Reuse the same Idempotency-Key and merchant_reference. Do not create a new payment. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
Servers
Staging: https://dev-api.shabaas.com
Production: https://api.shabaas.com
Authentication
Authorization: Bearer <token>Bearer token returned by /api/public/authorization.
Parameters
Idempotency-KeyheaderOptionalWhen sent, persist it and reuse the same value with the same body.
"payment-invoice-4201-v1"Request Body
Requiredapplication/jsonProperties
payment_initiationRequiredobjectRequest payload used to initiate a payment against an active agreement.
Properties
payment_agreement_idRequiredstringExisting active payment agreement identifier.
"3652PA20260428120000123"amountRequiredDebit amount to initiate for this request.
oneOf
"10.00"merchant_referenceOptionalstringOptional merchant reference for this payment. Send it with Idempotency-Key when the caller has one.
"invoice-4201"notesOptionalstringOptional note attached to the initiation.
"Invoice 1042"descriptionOptionalstringIgnored by the API; use notes for optional text.
"(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/jsonStandard success envelope for payment initiation APIs.
Properties
messageOptionalstringHuman-readable outcome message.
"Success"dataOptionalobjectPayment initiation object returned by create/get initiation APIs.
Properties
payment_initiation_idOptionalstringUnique payment initiation identifier.
"12345PI1714316400"payment_agreement_idOptionalstringLinked payment agreement identifier.
"3652PA20260428120000123"amountOptionalDebit amount for this initiation.
oneOf
"10.00"currencyOptionalstringCurrency of this initiation.
"AUD"operation_idOptionalstringPresent when the request included Idempotency-Key. Use it to retrieve the original operation.
"op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"merchant_referenceOptionalstringMerchant reference stored with the idempotency key. Null when the request omitted it.
"invoice-4201"state_versionOptionalintegerMonotonic version of this payment record.
1statusOptionalstringCurrent initiation processing status.
"accp"created_atOptionalstringInitiation creation timestamp in ISO8601 format.
"2026-04-28T13:45:00.000Z"settledOptionalbooleanIndicates whether the initiation has settled.
falsetransferOptionalstringTransfer state/classification when available.
nullfailure_codeOptionalstringProvider/business failure code.
"R803"messageOptionalstringFailure or status message supplied by processing system.
"Similar payment attempted within last 24 hours"split_percentage_feeOptionalnumberBookkeeper retain percentage when set (greater than 0 and less than 100). Retained share stays on the business ledger for end-of-day transfer.
20refund_amountOptionalstringTotal of Ok and Pending refunds reserved against this payment.
Null when no refund has reserved an amount.
"1.0"refundsOptionalarrayRefunds for this payment, oldest first. Empty when none exist.
Array item schema
One refund of a payment initiation.
Properties
idOptionalintegerRefund row id.
41amountOptionalstringDollars sent, or reserved, for this refund.
"1.0"statusOptionalstringOk is paid. Pending is still in progress. Failed did not pay the customer.
"Ok"notesOptionalstringCaller-supplied reason. Scheme errors are not stored here.
"Customer requested a refund"created_atOptionalstring"2026-04-28T15:00:00.000Z"completed_atOptionalstringReserved timestamp. Currently null even when status is Ok.
nulltransaction_idOptionalstringScheme transaction id once the refund is accepted.
"90010001"failure_codeOptionalstringScheme failure code. Null on Ok and Pending.
failure_messageOptionalstringScheme failure message. Null on Ok and Pending.
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/jsonStandard success envelope for payment initiation APIs.
Properties
messageOptionalstringHuman-readable outcome message.
"Success"dataOptionalobjectPayment initiation object returned by create/get initiation APIs.
Properties
payment_initiation_idOptionalstringUnique payment initiation identifier.
"12345PI1714316400"payment_agreement_idOptionalstringLinked payment agreement identifier.
"3652PA20260428120000123"amountOptionalDebit amount for this initiation.
oneOf
"10.00"currencyOptionalstringCurrency of this initiation.
"AUD"operation_idOptionalstringPresent when the request included Idempotency-Key. Use it to retrieve the original operation.
"op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"merchant_referenceOptionalstringMerchant reference stored with the idempotency key. Null when the request omitted it.
"invoice-4201"state_versionOptionalintegerMonotonic version of this payment record.
1statusOptionalstringCurrent initiation processing status.
"accp"created_atOptionalstringInitiation creation timestamp in ISO8601 format.
"2026-04-28T13:45:00.000Z"settledOptionalbooleanIndicates whether the initiation has settled.
falsetransferOptionalstringTransfer state/classification when available.
nullfailure_codeOptionalstringProvider/business failure code.
"R803"messageOptionalstringFailure or status message supplied by processing system.
"Similar payment attempted within last 24 hours"split_percentage_feeOptionalnumberBookkeeper retain percentage when set (greater than 0 and less than 100). Retained share stays on the business ledger for end-of-day transfer.
20refund_amountOptionalstringTotal of Ok and Pending refunds reserved against this payment.
Null when no refund has reserved an amount.
"1.0"refundsOptionalarrayRefunds for this payment, oldest first. Empty when none exist.
Array item schema
One refund of a payment initiation.
Properties
idOptionalintegerRefund row id.
41amountOptionalstringDollars sent, or reserved, for this refund.
"1.0"statusOptionalstringOk is paid. Pending is still in progress. Failed did not pay the customer.
"Ok"notesOptionalstringCaller-supplied reason. Scheme errors are not stored here.
"Customer requested a refund"created_atOptionalstring"2026-04-28T15:00:00.000Z"completed_atOptionalstringReserved timestamp. Currently null even when status is Ok.
nulltransaction_idOptionalstringScheme transaction id once the refund is accepted.
"90010001"failure_codeOptionalstringScheme failure code. Null on Ok and Pending.
failure_messageOptionalstringScheme failure message. Null on Ok and Pending.
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/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"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/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"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/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"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/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"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/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"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`."
}
}
}
}