This endpoint allows the registration of a PayID against an account number. We recommend leaving 10 seconds before registering a PayID on a new account to ensure the account has been enabled for NPP.
\nThe domains that can be used to register a PayID are restricted. Custom domains are supported but must first be approved — please contact us for configuration. The default domain is monoova.me; if the PayID field is left blank we will generate a check-digited PayID on the Monoova domain.
", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "Request body used to register a PayID against an account number.", "customType": "RegisterPayId_V1", "schema": [ { "name": "payId", "kind": "optional", "type": "string", "description": "Optional. Email address for the PayID. If this field is left blank, Monoova generates a check-digited PayID on the default monoova.me domain. Custom domains are supported but must be approved before use.
", "example": "jane.doe@monoova.me", "default": "jane.doe@monoova.me", "pattern": "^[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+$" }, { "name": "bankAccountNumber", "kind": "required", "type": "string", "description": "The bank account number for the account against which you are trying to register a PayID. Digits only — do not include spaces or separators.
", "example": "410000123", "default": "410000123", "pattern": "^[0-9]{6,10}$" }, { "name": "bsb", "kind": "optional", "type": "string", "description": "Optional. BSB parameter. If not specified, the service will use the MAccount's configured Default BSB. If a Default BSB has not been configured, then the Monoova Default BSB will be used. Six digits, with or without a hyphen.
", "example": "123-456", "default": "123-456", "pattern": "^[0-9]{3}-?[0-9]{3}$" }, { "name": "payIdName", "kind": "required", "type": "string", "description": "Name displayed to the payers in order to identify you. Shown to a payer when they resolve the PayID before sending funds.", "example": "Jane Doe Pty Ltd", "default": "Jane Doe Pty Ltd", "pattern": "^[A-Za-z0-9 &.,'\\-]{1,140}$" } ], "modelRef": "#/components/schemas/RegisterPayId_V1", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "basicAuth", "name": "basicAuth", "kind": "optional", "type": "http", "description": "To authenticate using basic authentication, generate an API key and pass it as the username. No password is required.
", "scheme": "basic" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Successful validation. The PayID was registered.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Response returned by the Register PayID endpoint.", "customType": "NppRegisterPayIdResponse_V1", "schema": [ { "name": "PayIdDetails", "kind": "optional", "type": "array", "description": "Details of the PayID that was registered, including the generated PayID where the payId field was left blank in the request.
", "modelRef": "#/components/schemas/payIdDetails_V1", "customType": "payIdDetails_V1[]", "schema": [ { "name": "PayId", "kind": "optional", "type": "string", "description": "Email address for the PayID.", "example": "jane.doe@monoova.me", "default": "jane.doe@monoova.me", "pattern": "^[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+$" }, { "name": "BankAccountNumber", "kind": "optional", "type": "string", "description": "The bank account number for the account against which you are trying to register a PayID.", "example": "410000123", "default": "410000123", "pattern": "^[0-9]{6,10}$" }, { "name": "Bsb", "kind": "optional", "type": "string", "description": "Optional. BSB parameter. If not specified, the service will use the MAccount's configured Default BSB. If a Default BSB has not been configured, then the Monoova Default BSB will be used.
", "example": "123-456", "default": "123-456", "pattern": "^[0-9]{3}-?[0-9]{3}$" }, { "name": "PayIdName", "kind": "optional", "type": "string", "description": "Name displayed to a payer in order to identify you.", "example": "Jane Doe Pty Ltd", "default": "Jane Doe Pty Ltd", "pattern": "^[A-Za-z0-9 &.,'\\-]{1,140}$" }, { "name": "PayIdStatus", "kind": "optional", "type": "string", "description": "Status of your PayID. Possible values: Enable, Disable, Deregister, Port.
", "example": "Enable", "default": "Enable", "pattern": "^(Enable|Disable|Deregister|Port)$" } ] }, { "name": "durationMs", "kind": "optional", "type": "integerThis is a description of the status. If an 'Ok' status is returned, then this will be 'Operation completed successfully'.
", "example": "Operation completed successfully", "default": "Operation completed successfully", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/NppRegisterPayIdResponse_V1", "isExpanded": true } ] }, { "statusCode": "400", "description": "Bad Request — the request could not be processed because one or more fields failed validation, or the PayID or account details supplied are not valid.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"durationMs\":18,\"status\":\"Fail\",\"statusDescription\":\"Request validation failed. bankAccountNumber is required and must contain digits only.\"}", "description": "Standard error payload returned for 400, 401 and 500 responses.
", "customType": "ErrorResponse", "schema": [ { "name": "durationMs", "kind": "optional", "type": "integerThis is a description of the status, explaining why the request was rejected or could not be completed.
", "example": "Request validation failed. bankAccountNumber is required and must contain digits only.", "default": "Request validation failed. bankAccountNumber is required and must contain digits only.", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "Unauthorized — the API key supplied in the basic authentication header is missing, invalid, or not permitted to access this resource.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"durationMs\":5,\"status\":\"Unauthorized\",\"statusDescription\":\"Authentication failed. Supply a valid API key as the basic authentication username.\"}", "description": "Standard error payload returned for 400, 401 and 500 responses.
", "customType": "ErrorResponse", "schema": [ { "name": "durationMs", "kind": "optional", "type": "integerThis is a description of the status, explaining why the request was rejected or could not be completed.
", "example": "Request validation failed. bankAccountNumber is required and must contain digits only.", "default": "Request validation failed. bankAccountNumber is required and must contain digits only.", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "500", "description": "Internal Server Error — an unexpected error occurred while processing the request. Retry the request; if the error persists, contact Monoova support and quote the statusDescription.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"durationMs\":3021,\"status\":\"Error\",\"statusDescription\":\"An unexpected error occurred while processing the request. Please try again later.\"}", "description": "Standard error payload returned for 400, 401 and 500 responses.
", "customType": "ErrorResponse", "schema": [ { "name": "durationMs", "kind": "optional", "type": "integerThis is a description of the status, explaining why the request was rejected or could not be completed.
", "example": "Request validation failed. bankAccountNumber is required and must contain digits only.", "default": "Request validation failed. bankAccountNumber is required and must contain digits only.", "pattern": "^.{1,500}$" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "KsJJtf4IK03bLWuogon2O", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.mpay.com.au/receivables/v1/payid/registerPayId \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data-raw '{\n \"payId\": \"jane.doe@monoova.me\",\n \"bankAccountNumber\": \"410000123\",\n \"bsb\": \"123-456\",\n \"payIdName\": \"Jane Doe Pty Ltd\"\n }'" }, { "id": "9aCClivT0d5k7ejrrYIz0", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"payId\": \"jane.doe@monoova.me\",\n \"bankAccountNumber\": \"410000123\",\n \"bsb\": \"123-456\",\n \"payIdName\": \"Jane Doe Pty Ltd\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.mpay.com.au/receivables/v1/payid/registerPayId\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "lN07yB5rBPt7C5RYzdyG7", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.mpay.com.au/receivables/v1/payid/registerPayId\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"payId\": \"jane.doe@monoova.me\",\n \"bankAccountNumber\": \"410000123\",\n \"bsb\": \"123-456\",\n \"payIdName\": \"Jane Doe Pty Ltd\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "PkpkXbkYWpcnsh4hurS3w", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.mpay.com.au/receivables/v1/payid/registerPayId\"\n\npayload = json.dumps({\n \"payId\": \"jane.doe@monoova.me\",\n \"bankAccountNumber\": \"410000123\",\n \"bsb\": \"123-456\",\n \"payIdName\": \"Jane Doe Pty Ltd\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "KsJJtf4IK03bLWuogon2O" }, "results": { "languages": [ { "id": "rp9w4kzPe5mZHO0JKnPE1", "language": "200", "code": "// Successful validation. The PayID was registered.\n{\n \"PayIdDetails\": [\n {\n \"PayId\": \"jane.doe@monoova.me\",\n \"BankAccountNumber\": \"410000123\",\n \"Bsb\": \"123-456\",\n \"PayIdName\": \"Jane Doe Pty Ltd\",\n \"PayIdStatus\": \"Enable\"\n }\n ],\n \"durationMs\": 126,\n \"status\": \"Ok\",\n \"statusDescription\": \"Operation completed successfully\"\n}" }, { "id": "SJu-mYppjLX2BVi8jI33k", "language": "400", "code": "// Bad Request — the request could not be processed because one or more fields failed validation, or the PayID or account details supplied are not valid.\n{\n \"durationMs\": 18,\n \"status\": \"Fail\",\n \"statusDescription\": \"Request validation failed. bankAccountNumber is required and must contain digits only.\"\n}" }, { "id": "TaKBBSyQ31BLOL7mmHBEA", "language": "401", "code": "// Unauthorized — the API key supplied in the basic authentication header is missing, invalid, or not permitted to access this resource.\n{\n \"durationMs\": 18,\n \"status\": \"Fail\",\n \"statusDescription\": \"Request validation failed. bankAccountNumber is required and must contain digits only.\"\n}" }, { "id": "46Z-eH7X4MOfAE1C5Zq0O", "language": "500", "code": "// Internal Server Error — an unexpected error occurred while processing the request. Retry the request; if the error persists, contact Monoova support and quote the statusDescription.\n{\n \"durationMs\": 18,\n \"status\": \"Fail\",\n \"statusDescription\": \"Request validation failed. bankAccountNumber is required and must contain digits only.\"\n}" } ], "selectedLanguageId": "rp9w4kzPe5mZHO0JKnPE1" } }, "children": [ { "text": "" } ] }