{"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 Agreement","x-displayName":"Payment Agreement","description":"Create, retrieve, amend, resend, and cancel PayTo payment agreements."}],"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_agreement/one_time":{"post":{"tags":["Payment Agreement"],"summary":"Create one-time payment agreement","description":"Create a one-time payment agreement flow linked to checkout.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| GN-0000 | 400 | Request payload is empty | Provide `payment_agreement` object with required fields. |\n| PAM_NPP_GATEWAY_ERROR | 422 | Upstream processing error | Retry request; if repeated, contact support with request details. |\n| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff and poll status. |\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_agreement"],"properties":{"payment_agreement":{"$ref":"#/components/schemas/CreateOneTimePaymentAgreementRequest"},"destination":{"$ref":"#/components/schemas/DestinationAccount"}}}}}},"responses":{"200":{"description":"One-time payment agreement created and submitted for payer authorization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessPaymentAgreementResponse"},"examples":{"created":{"summary":"One-time agreement created","value":{"message":"Payment Agreement created successfully, Please authorized payment agreement from your banking app.","data":{"payment_agreement_id":"4469PA20260707111156522","status":"created","end_date":"2027-07-07","created_at":"2026-07-07T11:11:56.522Z","maximum_amount":"100.0"}}}}}}},"422":{"description":"Validation or business-rule error while creating one-time agreement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"Invalid payload","value":{"message":"Invalid request payload","error_code":"VALIDATION_ERROR","data":{"response_time":"2026-04-28T13:15:00.000Z"}}},"provider_error":{"summary":"Upstream provider error","value":{"message":"MONOOVA-monoova.PAM_NPP_GATEWAY_ERROR","error_code":"GN-0000","data":{"response_time":"2026-04-28T13:15:00.000Z"}}}}}}}}}}},"components":{"schemas":{"CreateOneTimePaymentAgreementRequest":{"type":"object","description":"Request payload used to create a one-time payment agreement flow.","required":["name","amount","type","pay_id"],"properties":{"phone_number":{"type":"string","description":"Optional payer mobile number used to look up or create a payer profile.","example":"+61422020901"},"name":{"type":"string","minLength":2,"maxLength":140,"description":"Payer display name shown in agreement flow.","example":"John Smith"},"amount":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"One-time debit amount for this agreement flow.","example":"100.00"},"notes":{"type":"string","maxLength":140,"description":"Optional short note/description attached to the one-time flow.","example":"Invoice 1042"},"bsb":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Optional BSB when account-based payer details are used.","example":"123456"},"account_number":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Optional account number when account-based payer details are used.","example":"987654321"},"type":{"type":"string","description":"Identifier type hint for payer details.\nSandbox `pay_id` suggestions for each type are listed on Create PayTo Agreement and on the `pay_id` field.\n","enum":["email","phone","abn","org","bsb"],"default":"email","example":"email"},"pay_id":{"type":"string","description":"Required PayID value for payer authorization context.\n\nSandbox suggestions (Staging). Production requires a real PayID.\n- `email`: `sample@shabaas.com`, `sample@sbpay.au`\n- `phone`: `61491570006`, `61491570156`\n- `abn`: `12345678901`, `13579246810`\n- `org`: `123456789`, `135792468`\n"},"agreement_type":{"type":"string","description":"Optional agreement type code used by downstream provider.","example":"VARI"},"start_date":{"type":"string","format":"date","description":"Optional agreement start date in `YYYY-MM-DD`.","example":"2026-05-01"},"end_date":{"type":"string","format":"date","description":"Optional agreement end date in `YYYY-MM-DD`.","example":"2026-05-31"}}},"DestinationAccount":{"type":"object","description":"Destination payout account details used when instant payout is enabled.","properties":{"bsb":{"type":"string","minLength":6,"maxLength":6,"description":"Destination BSB (6 digits).","example":"123456"},"account_number":{"type":"string","minLength":4,"maxLength":12,"description":"Destination account number.","example":"12345678"}}},"SuccessPaymentAgreementResponse":{"type":"object","description":"Standard success envelope for payment agreement APIs.","properties":{"message":{"type":"string","description":"Message for the request response.","example":"Payment Agreement created successfully, Please authorized payment agreement from your banking app."},"data":{"$ref":"#/components/schemas/PaymentAgreement"}}},"PaymentAgreement":{"type":"object","description":"Payment agreement object returned by create/get agreement APIs.","properties":{"payment_agreement_id":{"type":"string","description":"Unique agreement identifier. Use this value to retrieve, amend, resend, or cancel the agreement.","example":"3652PA20260428120000123"},"status":{"type":"string","description":"Current agreement state in the processing lifecycle.","example":"initiated"},"end_date":{"type":"string","format":"date","description":"Agreement end date when set; null/omitted when open-ended.","example":"2026-12-31"},"created_at":{"type":"string","format":"date-time","description":"Agreement creation timestamp in ISO8601 format.","example":"2026-04-28T12:00:00.000Z"},"maximum_amount":{"type":"string","description":"Maximum debit amount allowed per agreement.","example":"500.00"},"maximum_overall_allowed_amount":{"type":"string","description":"Overall collection cap for the agreement when set (cumulative amount across all payment initiations).\n","example":"2000.00"},"extented_status":{"type":"string","description":"Compact composite status string used by existing clients.","example":"500-WEEK-10-initiated"},"message":{"type":"string","description":"Present when agreement has a failure message from scheme","example":"Payee account cannot receive NPP Payments"},"failure_code":{"type":"string","description":"Provider/business failure code when the agreement fails.","example":"M100"}}},"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`."}}}}