{"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":{"get":{"tags":["Payment Initiation"],"summary":"Show Payment Request Status","description":"Retrieve a payment initiation by `id` (payment_initiation_id).\n\nThe response includes `refund_amount` and `refunds`. Use this call to see whether a `Pending` refund later became `Ok` or `Failed`. `refunds` is an empty array when the payment has no refunds.\n\nStatus values: [Payment Initiation Status Values](https://shabaaspay-pay.readme.io/reference/payment-initiation-status-values).\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| GN-0000 | 404 | Payment initiation not found | Verify the `id` belongs to this merchant and retry. |\n| PAS_PAM_TIMEOUT_ERROR | 500 | Timeout while calling agreement service | Retry later and contact support if persistent. |\n","parameters":[{"in":"query","name":"id","required":true,"schema":{"type":"string"},"description":"payment_initiation_id"}],"responses":{"200":{"description":"Payment initiation details retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessPaymentInitiationResponse"},"examples":{"found":{"summary":"Payment initiation found","value":{"message":"Success","data":{"payment_initiation_id":"12345PI1714316400","settled":false,"status":"inpr","transfer":null,"created_at":"2026-04-28T13:30:00.000Z"}}},"with_refund":{"summary":"Payment that has a completed refund","value":{"message":"Success","data":{"payment_initiation_id":"12345PI1714316400","settled":true,"status":"return_complete","transfer":"transferred","created_at":"2026-04-28T13:30:00.000Z","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}]}}}}}}},"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:30:00.000Z"}}}}}}},"404":{"description":"Payment initiation id not found for this merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"value":{"message":"Payment Initiation not found","error_code":"GN-0000","data":{"response_time":"2026-04-10T12:00:00.000Z"}}}}}}},"408":{"description":"Upstream timeout while retrieving payment initiation details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"timeout":{"summary":"Upstream timeout","value":{"message":"Request Timeout","error_code":"GN-0000","data":{"response_time":"2026-04-28T13:30:00.000Z"}}}}}}}}}}},"components":{"schemas":{"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`."}}}}