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