{"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":{"post":{"tags":["Payment Agreement"],"summary":"Create PayTo Agreement","description":"Create a PayTo payment agreement.\n\n### Sandbox PayID suggestions\nOn Staging, use one of these `pay_id` values for the matching `type`. Production requires a real PayID.\n\n| type | Suggested `pay_id` |\n| ---- | ------------------ |\n| email | `sample@shabaas.com`, `sample@sbpay.au` |\n| phone | `61491570006`, `61491570156` |\n| abn | `12345678901`, `13579246810` |\n| org | `123456789`, `135792468` |\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| PAM_PAYER_ID_TYPE_FORBIDDEN | 400 | LinkedPayIdType prohibited without linkedPayID| Include `pay_id`|\n| PAM_PAYER_BSB_REQUIRED | 400 | Payer BSB required when not using a PayID | Use `bsb` + `account_number` for bank payers, or switch to `type: email` / phone with `pay_id` for PayID. |\n| PAM_REQUEST_EMPTY | 400 | Request payload is empty | Send `payment_agreement` object with required fields. |\n| PAM_VALIDATION_ERROR | 400 | Request validation failed | Correct invalid/missing fields and retry. |\n| PAM_PAYEE_MISSING | 400 | Payee details are missing | Provide PayID or valid account details. |\n| PAM_PAYEE_ACCT_MISSING | 400 | Payee account details are missing | Include both BSB and account number when required. |\n| PAM_PAYEE_BSB_INVALID | 400 | Payee BSB is invalid | Use a valid 6-digit BSB. |\n| PAM_PAYEE_ACCT_INVALID | 400 | Payee account number is invalid | Provide a valid account number. |\n| PAM_PMT_FREQ_INVALID | 400 | Frequency value is invalid | Use one of supported frequency values. |\n| PAM_PAG_LIMIT_EXCEEDED | 400 | Merchant agreement limit exceeded | Reduce request volume or increase limit. |\n| M101 | 422 | Amount exceeds platform single-agreement threshold | Reduce `maximum_amount` to supported threshold. |\n| M100 | 422 | Amount exceeds merchant agreement limit | Update merchant limits or lower `maximum_amount`. |\n| MOV_NPP_PAYMENT_NOT_SUPPORTED | 422 | Payee account cannot receive NPP payments | Use a valid PayID/account that can receive NPP payments. |\n| MOV_PAYEE_DETAIL_ERROR | 404 | Payee details are incorrect | Correct PayID/BSB/account details. |\n| MOV_INVALID_BSB | 400 | BSB is invalid | Provide a valid BSB and retry. |\n| MOV_REQUEST_TIMEOUT | 408 | Provider request timed out | Retry with backoff and poll status if needed. |\n| VALIDATION_ERROR | 422 | Invalid request fields (for example frequency) | Correct payload format and accepted enum values. |\n| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_agreement"],"properties":{"payment_agreement":{"$ref":"#/components/schemas/CreatePaymentAgreementRequest"}}},"examples":{"valid":{"summary":"Valid request (stored frequency code)","value":{"payment_agreement":{"name":"John Smith","type":"email","maximum_amount":"500","maximum_overall_allowed_amount":"2000","frequency":"ADHO","number_of_transactions_permitted":10}}},"frequency_alias":{"summary":"Alias normalized by API (DAILY→DAIL, ADHOC→ADHO)","value":{"payment_agreement":{"name":"John Smith","type":"email","maximum_amount":"500","frequency":"DAILY","number_of_transactions_permitted":10}}},"invalid_frequency":{"summary":"Invalid frequency (e.g. DAY is not a valid code or alias)","value":{"payment_agreement":{"name":"Hamza Amin","type":"email","maximum_amount":"500","frequency":"DAY","number_of_transactions_permitted":10}}}}}}},"responses":{"200":{"description":"Payment agreement created and submitted for payer authorization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessPaymentAgreementResponse"},"examples":{"created":{"summary":"Agreement created successfully","value":{"message":"Payment Agreement created successfully, Please authorized payment agreement from your banking app.","data":{"payment_agreement_id":"3652PA20260428120000123","status":"initiated","end_date":"2026-12-31","created_at":"2026-04-28T12:00:00.000Z","maximum_amount":"500.00","extented_status":"500-WEEK-10-initiated"}}}}}}},"400":{"description":"PayTo / payer validation error returned by the upstream provider.\nExamples: missing `pay_id` for email/phone type, or missing bank details for `type: bsb`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"payer_id_type_without_linked_pay_id":{"summary":"linkedPayIdType without linkedPayId (e.g. only type + frequency)","value":{"message":".linkedPayIdType prohibited without linkedPayId","error_code":"PAM_PAYER_ID_TYPE_FORBIDDEN","data":{"response_time":"2026-05-04T10:52:05.218Z"}}},"payer_bsb_required":{"summary":"type bsb without bsb/account (e.g. pay_id used like email)","value":{"message":".linkedBsb required if no linkedPayId","error_code":"PAM_PAYER_BSB_REQUIRED","data":{"response_time":"2026-05-04T11:10:56.372Z"}}}}}}},"401":{"description":"Invalid or missing authorization context.","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-28T12:00:00.000Z"}}}}}}},"402":{"description":"Developer credits exhausted","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":"Related resource not found in current merchant context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"agreement_context_not_found":{"summary":"Referenced entity not found","value":{"message":"MONOOVA-monoova.PAM_SB_PAG_NOT_FOUND_ERROR","error_code":"GN-0000","data":{"response_time":"2026-04-28T12:00:00.000Z"}}}}}}},"408":{"description":"Upstream provider timeout while processing agreement creation.","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-28T12:00:00.000Z"}}}}}}},"422":{"description":"Validation or business-rule failure for agreement creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_frequency":{"summary":"Frequency not accepted after normalization","value":{"message":"Invalid frequency value","error_code":"VALIDATION_ERROR","data":{"field":"frequency","stored_codes":["ADHO","DAIL","FRTN","INDA","MIAN","MNTH","QURT","WEEK","YEAR"],"aliases":{"DAILY":"DAIL","ADHOC":"ADHO"}}}},"monoova_payee":{"summary":"Payee cannot receive NPP (example)","value":{"message":"Payee account cannot receive NPP Payments","error_code":"MOV_NPP_PAYMENT_NOT_SUPPORTED","data":{"response_time":"2026-04-08T12:28:26.759Z"}}}}}}}}}}},"components":{"schemas":{"CreatePaymentAgreementRequest":{"type":"object","description":"Request payload used to create a recurring payment agreement for a payer.","required":["name","type","maximum_amount","frequency","number_of_transactions_permitted","pay_id"],"properties":{"phone_number":{"type":"string","description":"Optional payer phone number. When provided, the payer profile is looked up/created against this number.","example":"+61422020901"},"name":{"type":"string","minLength":2,"maxLength":140,"description":"Payer display name used in agreement records and authorization flow.","example":"John Smith"},"type":{"type":"string","description":"Identifier type for payer/payee details.\nSandbox `pay_id` suggestions for each type are listed on this endpoint and on the `pay_id` field.\n","example":"email","enum":["email","phone","abn","org","bsb"]},"maximum_amount":{"type":"string","description":"Maximum debit amount allowed per transaction under this agreement.","example":"500.00"},"maximum_overall_allowed_amount":{"type":"string","description":"Optional. Overall collection cap for the agreement (cumulative amount that may be collected across all payment initiations).\nWhen provided, it must be greater than or equal to `maximum_amount`. Once this total is reached, further payment initiations are rejected.\nLeave empty for no overall cap.\n","example":"2000.00"},"frequency":{"type":"string","description":"Stored codes (after normalization): ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR.\nAliases before save: DAILY→DAIL, ADHOC→ADHO.\n","example":"ADHO","enum":["ADHO","DAIL","FRTN","INDA","MIAN","MNTH","QURT","WEEK","YEAR","DAILY","ADHOC"]},"number_of_transactions_permitted":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of debits permitted under this agreement.","example":10},"pay_id":{"type":"string","description":"PayID used for payer authorization.\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"},"bsb":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"BSB value when bank-account based setup is used.","example":"123456"},"account_number":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Account number when bank-account based setup is used.","example":"987654321"},"agreement_type":{"type":"string","description":"Agreement variation/type code used by downstream provider where applicable.","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`. Leave empty for open-ended agreement.","example":"2026-12-31"}}},"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`."}}}}