{"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":"Webhooks","x-displayName":"Webhooks","description":"Configure notification endpoints for agreement and payment events."}],"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/webhooks":{"post":{"tags":["Webhooks"],"summary":"Register Webhook","description":"Create or update webhook callback endpoints for merchant event notifications.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| VALIDATION_ERROR | 422 | Webhook payload is invalid | Ensure all webhook URLs and auth key values are valid. |\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpsertRequest"},"examples":{"upsert_webhooks":{"summary":"Save all webhook endpoints","value":{"auth_key":"whsec_7f9d2b84c1f2","payment_agreement":"https://staging.abc.co/payment_agreement","payment_initiation":"https://staging.abc.co/payment_initiation","direct_debit_accepted":"https://staging.abc.co/direct_debit_accepted","direct_debit_rejected":"https://staging.abc.co/direct_debit_rejected"}}}}}},"responses":{"200":{"description":"Webhook endpoints saved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"},"examples":{"saved":{"summary":"Webhook configuration saved","value":{"message":"Webhook saved successfully","data":{}}}}}}},"422":{"description":"Invalid webhook payload (missing fields or invalid URLs).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_payload":{"summary":"Invalid webhook body","value":{"message":"Validation failed","error_code":"VALIDATION_ERROR","data":{"response_time":"2026-04-29T08:00:00.000Z"}}}}}}}}}}},"components":{"schemas":{"WebhookUpsertRequest":{"type":"object","description":"Request payload to create or update merchant webhook endpoints.","required":["auth_key","payment_agreement","payment_initiation","direct_debit_accepted","direct_debit_rejected"],"properties":{"auth_key":{"type":"string","description":"Shared secret value sent with webhook requests for receiver-side verification.","minLength":8,"maxLength":200,"example":"whsec_7f9d2b84c1f2"},"payment_agreement":{"type":"string","format":"uri","description":"HTTPS endpoint that receives payment agreement status callbacks.","example":"https://staging.abc.co/payment_agreement"},"payment_initiation":{"type":"string","format":"uri","description":"HTTPS endpoint that receives payment initiation callbacks.","example":"https://staging.abc.co/payment_initiation"},"direct_debit_accepted":{"type":"string","format":"uri","description":"HTTPS endpoint invoked when direct debit is accepted.","example":"https://staging.abc.co/direct_debit_accepted"},"direct_debit_rejected":{"type":"string","format":"uri","description":"HTTPS endpoint invoked when direct debit is rejected/dishonoured.","example":"https://staging.abc.co/direct_debit_rejected"}}},"MessageResponse":{"type":"object","properties":{"message":{"type":"string","example":"Success"},"data":{"type":"object","additionalProperties":true}}},"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`."}}}}