---
title: Create payment instruction
slug: api/create-payment-instruction
docTags:
createdAt: 2025-01-12T22:58:57.989Z
---
{
"id": "P3zDtr6h1R8pMmv4uzIxW",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://sand-api.monoova.com/au/payto/pas-v1/PaymentInstruction",
"servers": [
{
"url": "https://sand-api.monoova.com/au/payto/pas-v1/PaymentInstruction",
"description": "Sandbox URL"
},
{
"url": "https://api.monoova.com/au/payto/pas-v1/PaymentInstruction",
"description": "Production URL"
}
],
"name": "Create payment instruction",
"description": "Once a valid payment agreement has approved by the payer this endpoint is used to create a payment instruction, which creates real time pull payments.
\nYou are allowed a maximum of 5 failed instructions in a 24 hour period, if you reach this limit you will need to wait until the next day to retry.
",
"contentType": "application/json-patch+json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "optional",
"name": "body",
"type": "object",
"description": "",
"customType": "InitiateMandatePaymentDto",
"schema": [
{
"name": "paymentAgreementUID",
"kind": "required",
"type": "string",
"description": "Id to uniquely Identify a payment agreement.",
"example": ""
},
{
"name": "paymentInitiationUID",
"kind": "required",
"type": "string",
"description": "Id to uniquely identify payment.",
"example": ""
},
{
"name": "payeeDetails",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/PayeeDetailsDto",
"customType": "PayeeDetailsDto",
"schema": [
{
"name": "payeeType",
"kind": "optional",
"type": "string",
"description": "Identifies the type of a party.",
"example": ""
},
{
"name": "payeeLinkedBsb",
"kind": "optional",
"type": "string",
"description": "BSB number.\n\nRequired if 'payeeLinkedPayId' and 'payeeLinkedPayIdType' are not provided. e.g. '999-999 or 999999'",
"example": ""
},
{
"name": "payeeLinkedAccount",
"kind": "optional",
"type": "string",
"description": "Bank Account Number.\n\nRequired if 'payeeLinkedPayId' and 'payeeLinkedPayIdType' are not provided. Cannot be all zeros or spaces",
"example": ""
},
{
"name": "payeeLinkedPayId",
"kind": "optional",
"type": "string",
"description": "PayID.\n\nEmail, phone number, ABN, ACN or Organisation name.\n\nRequired if 'payeeLinkedBsb' and 'payeeLinkedAccount' are not provided.\n\nRequired format depends on the payeeLinkedPayIdType",
"example": ""
},
{
"name": "payeeLinkedPayIdType",
"kind": "optional",
"type": "string",
"description": "PayID Type.\n\nRequired if 'linkedBsb' and 'linkedAccount' are not provided.",
"example": ""
},
{
"name": "payeeAccountName",
"kind": "optional",
"type": "string",
"description": "Bank Account Name.\n\nCan only provide payeeAccountName in the payload if crediting an external BSB. Mandatory if crediting a PayID.",
"example": ""
},
{
"name": "ultimatePayee",
"kind": "optional",
"type": "string",
"description": "Name by which the party is known, and which is usually used to identify that party.\n\nCan only provide ultimatePayee in the payload if crediting an external BSB.",
"example": ""
}
]
},
{
"name": "paymentDetails",
"kind": "required",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/PaymentInitiationDetailsDto",
"customType": "PaymentInitiationDetailsDto",
"schema": [
{
"name": "amount",
"kind": "required",
"type": "string",
"description": "Amount to be transferred. Amount must be >= 0.01",
"example": ""
},
{
"name": "isLastPayment",
"kind": "optional",
"type": "boolean",
"description": "Set to true to indicate this is the last payment initiation request associated with the mandate. Possible values - True, False.",
"example": ""
},
{
"name": "lodgementReference",
"kind": "optional",
"type": "string",
"description": "Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.",
"example": ""
},
{
"name": "uniqueSuperAnnuationCode",
"kind": "optional",
"type": "string",
"description": "UniqueSuperAnnuationCode\n\nName of the Identification scheme, in a free text form.\n\nRequired when uniqueSuperAnnuationIdentification is provided",
"example": ""
},
{
"name": "uniqueSuperAnnuationIdentification",
"kind": "optional",
"type": "string",
"description": "UniqueSuperAnnuationIdentification\n\nIdentification assigned by an institution.\n\nRequired when uniqueSuperAnnuationCode is provided",
"example": ""
}
]
}
],
"modelRef": "#/components/schemas/InitiateMandatePaymentDto",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "BearerAuth",
"name": "BearerAuth",
"kind": "optional",
"type": "http",
"scheme": "bearer"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "OK",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "InitiateMandatePaymentResponseDto",
"schema": [
{
"name": "traceId",
"kind": "optional",
"type": "string",
"description": "Unique id for logging",
"example": ""
},
{
"name": "paymentAgreementUID",
"kind": "optional",
"type": "string",
"description": "Id to uniquely Identify a payment agreement.",
"example": ""
},
{
"name": "paymentInitiationUID",
"kind": "optional",
"type": "string",
"description": "Id to uniquely Identify a payment initiation.",
"example": ""
},
{
"name": "nppInstructionId",
"kind": "optional",
"type": "string",
"description": "Unique identifier for the NPP instruction.",
"example": ""
},
{
"name": "paymentInitiationStatus",
"kind": "optional",
"type": "string",
"description": "This is the status of the payment agreement.",
"example": ""
},
{
"name": "paymentInitiationStatusDescription",
"kind": "optional",
"type": "string",
"description": "This describes the status. For example, a status of ‘created’ will have a description of ‘Pending Payer Approval’",
"example": ""
},
{
"name": "statusReasonCode",
"kind": "optional",
"type": "string",
"description": "Reason code for current instruction status.",
"example": ""
},
{
"name": "statusReasonDescription",
"kind": "optional",
"type": "string",
"description": "Description of reason code for current instruction status.",
"example": ""
},
{
"name": "mmsId",
"kind": "optional",
"type": "string",
"description": "This is the unique ID that identifies this payment agreement.",
"example": ""
}
],
"modelRef": "#/components/schemas/InitiateMandatePaymentResponseDto",
"isExpanded": true
}
]
},
{
"statusCode": "201",
"description": "Created",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "InitiateMandatePaymentResponseDto",
"schema": [
{
"name": "traceId",
"kind": "optional",
"type": "string",
"description": "Unique id for logging",
"example": ""
},
{
"name": "paymentAgreementUID",
"kind": "optional",
"type": "string",
"description": "Id to uniquely Identify a payment agreement.",
"example": ""
},
{
"name": "paymentInitiationUID",
"kind": "optional",
"type": "string",
"description": "Id to uniquely Identify a payment initiation.",
"example": ""
},
{
"name": "nppInstructionId",
"kind": "optional",
"type": "string",
"description": "Unique identifier for the NPP instruction.",
"example": ""
},
{
"name": "paymentInitiationStatus",
"kind": "optional",
"type": "string",
"description": "This is the status of the payment agreement.",
"example": ""
},
{
"name": "paymentInitiationStatusDescription",
"kind": "optional",
"type": "string",
"description": "This describes the status. For example, a status of ‘created’ will have a description of ‘Pending Payer Approval’",
"example": ""
},
{
"name": "statusReasonCode",
"kind": "optional",
"type": "string",
"description": "Reason code for current instruction status.",
"example": ""
},
{
"name": "statusReasonDescription",
"kind": "optional",
"type": "string",
"description": "Description of reason code for current instruction status.",
"example": ""
},
{
"name": "mmsId",
"kind": "optional",
"type": "string",
"description": "This is the unique ID that identifies this payment agreement.",
"example": ""
}
],
"modelRef": "#/components/schemas/InitiateMandatePaymentResponseDto",
"isExpanded": true
}
]
},
{
"statusCode": "202",
"description": "Accepted",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "400",
"description": "Bad Request",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "ErrorResponse",
"schema": [
{
"name": "traceId",
"kind": "optional",
"type": "string",
"description": "Unique id for logging",
"example": ""
},
{
"name": "errors",
"kind": "optional",
"type": "array",
"description": "",
"modelRef": "#/components/schemas/ErrorDto",
"customType": "ErrorDto[]",
"schema": [
{
"name": "errorCode",
"kind": "optional",
"type": "string",
"description": "Monoova error code",
"example": ""
},
{
"name": "errorMessage",
"kind": "optional",
"type": "string",
"description": "More detailed description of the specific error which may include information from the specific request.",
"example": ""
}
]
}
],
"modelRef": "#/components/schemas/ErrorResponse",
"isExpanded": true
}
]
},
{
"statusCode": "403",
"description": "Forbidden",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "ErrorResponse",
"schema": [
{
"name": "traceId",
"kind": "optional",
"type": "string",
"description": "Unique id for logging",
"example": ""
},
{
"name": "errors",
"kind": "optional",
"type": "array",
"description": "",
"modelRef": "#/components/schemas/ErrorDto",
"customType": "ErrorDto[]",
"schema": [
{
"name": "errorCode",
"kind": "optional",
"type": "string",
"description": "Monoova error code",
"example": ""
},
{
"name": "errorMessage",
"kind": "optional",
"type": "string",
"description": "More detailed description of the specific error which may include information from the specific request.",
"example": ""
}
]
}
],
"modelRef": "#/components/schemas/ErrorResponse",
"isExpanded": true
}
]
},
{
"statusCode": "404",
"description": "Not Found",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "ErrorResponse",
"schema": [
{
"name": "traceId",
"kind": "optional",
"type": "string",
"description": "Unique id for logging",
"example": ""
},
{
"name": "errors",
"kind": "optional",
"type": "array",
"description": "",
"modelRef": "#/components/schemas/ErrorDto",
"customType": "ErrorDto[]",
"schema": [
{
"name": "errorCode",
"kind": "optional",
"type": "string",
"description": "Monoova error code",
"example": ""
},
{
"name": "errorMessage",
"kind": "optional",
"type": "string",
"description": "More detailed description of the specific error which may include information from the specific request.",
"example": ""
}
]
}
],
"modelRef": "#/components/schemas/ErrorResponse",
"isExpanded": true
}
]
},
{
"statusCode": "422",
"description": "Unprocessable Content",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "ErrorResponse",
"schema": [
{
"name": "traceId",
"kind": "optional",
"type": "string",
"description": "Unique id for logging",
"example": ""
},
{
"name": "errors",
"kind": "optional",
"type": "array",
"description": "",
"modelRef": "#/components/schemas/ErrorDto",
"customType": "ErrorDto[]",
"schema": [
{
"name": "errorCode",
"kind": "optional",
"type": "string",
"description": "Monoova error code",
"example": ""
},
{
"name": "errorMessage",
"kind": "optional",
"type": "string",
"description": "More detailed description of the specific error which may include information from the specific request.",
"example": ""
}
]
}
],
"modelRef": "#/components/schemas/ErrorResponse",
"isExpanded": true
}
]
},
{
"statusCode": "500",
"description": "Internal Server Error",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "502",
"description": "Bad Gateway",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "504",
"description": "Gateway Timeout",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "GyixEwZoN69NNJzsTC0pM",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://sand-api.monoova.com/au/payto/pas-v1/PaymentInstruction \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json-patch+json' \\\n --data '{\n \"paymentAgreementUID\": \"\",\n \"paymentInitiationUID\": \"\",\n \"paymentDetails\": {\n \"amount\": \"\"\n }\n }'"
},
{
"id": "myESPv0VkPkXyMYRpmnEC",
"language": "csharp",
"label": "C#",
"code": "var options = new RestClientOptions(\"https://sand-api.monoova.com\")\n{\n MaxTimeout = -1,\n};\nvar client = new RestClient(options);\nvar request = new RestRequest(\"/au/payto/pas-v1/PaymentInstruction\", Method.Post);\nrequest.AddHeader(\"accept\", \"application/json\");\nrequest.AddHeader(\"content-type\", \"application/json-patch+json\");\nvar body = @\"{\" + \"\\n\" +\n@\" \"\"paymentAgreementUID\"\": \"\"\"\",\" + \"\\n\" +\n@\" \"\"paymentInitiationUID\"\": \"\"\"\",\" + \"\\n\" +\n@\" \"\"paymentDetails\"\": {\" + \"\\n\" +\n@\" \"\"amount\"\": \"\"\"\"\" + \"\\n\" +\n@\" }\" + \"\\n\" +\n@\"}\";\nrequest.AddStringBody(body, DataFormat.Json);\nRestResponse response = await client.ExecuteAsync(request);\nConsole.WriteLine(response.Content);"
},
{
"id": "ayTpeq20s5uiFY3vUW4c-",
"language": "javascript",
"label": "JavaScript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json-patch+json\");\n\nvar raw = JSON.stringify({\n \"paymentAgreementUID\": \"\",\n \"paymentInitiationUID\": \"\",\n \"paymentDetails\": {\n \"amount\": \"\"\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://sand-api.monoova.com/au/payto/pas-v1/PaymentInstruction\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "WJRllSPnX8_DmRKa_EFoE",
"language": "php",
"label": "PHP",
"code": " 'https://sand-api.monoova.com/au/payto/pas-v1/PaymentInstruction',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => '',\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 0,\n CURLOPT_FOLLOWLOCATION => true,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_POSTFIELDS =>'{\n \"paymentAgreementUID\": \"\",\n \"paymentInitiationUID\": \"\",\n \"paymentDetails\": {\n \"amount\": \"\"\n }\n}',\n CURLOPT_HTTPHEADER => array(\n 'accept: application/json',\n 'content-type: application/json-patch+json'\n ),\n));\n\n$response = curl_exec($curl);\n\ncurl_close($curl);\necho $response;\n"
}
],
"selectedLanguageId": "GyixEwZoN69NNJzsTC0pM"
},
"results": {
"languages": [
{
"id": "SlQoal8Cmz4rOST6qvYd_",
"language": "200",
"code": "// OK\n{\n \"traceId\": \"\",\n \"paymentAgreementUID\": \"\",\n \"paymentInitiationUID\": \"\",\n \"nppInstructionId\": \"\",\n \"paymentInitiationStatus\": \"\",\n \"paymentInitiationStatusDescription\": \"\",\n \"statusReasonCode\": \"\",\n \"statusReasonDescription\": \"\",\n \"mmsId\": \"\"\n}"
},
{
"id": "cNIvquIKzKKQQyOLzpqLA",
"language": "201",
"code": "// Created\n{\n \"traceId\": \"\",\n \"paymentAgreementUID\": \"\",\n \"paymentInitiationUID\": \"\",\n \"nppInstructionId\": \"\",\n \"paymentInitiationStatus\": \"\",\n \"paymentInitiationStatusDescription\": \"\",\n \"statusReasonCode\": \"\",\n \"statusReasonDescription\": \"\",\n \"mmsId\": \"\"\n}"
},
{
"id": "HvZ1LCkaPH6PcbyMrsUgR",
"language": "202",
"code": "// Accepted\n"
},
{
"id": "2l08gflie-OQsaOgM0w7x",
"language": "400",
"code": "// Bad Request\n{\n \"traceId\": \"\",\n \"errors\": [\n {\n \"errorCode\": \"\",\n \"errorMessage\": \"\"\n }\n ]\n}"
},
{
"id": "8H7o6NclLfId3BrzRQXn5",
"language": "403",
"code": "// Forbidden\n{\n \"traceId\": \"\",\n \"errors\": [\n {\n \"errorCode\": \"\",\n \"errorMessage\": \"\"\n }\n ]\n}"
},
{
"id": "gwxx8nAbUqbXFztf6kD2w",
"language": "404",
"code": "// Not Found\n{\n \"traceId\": \"\",\n \"errors\": [\n {\n \"errorCode\": \"\",\n \"errorMessage\": \"\"\n }\n ]\n}"
},
{
"id": "SjGpk6hp3YOM4RCw2gLxI",
"language": "422",
"code": "// Unprocessable Content\n{\n \"traceId\": \"\",\n \"errors\": [\n {\n \"errorCode\": \"\",\n \"errorMessage\": \"\"\n }\n ]\n}"
},
{
"id": "3RDAjbOSKicTg0sXH1BjH",
"language": "500",
"code": "// Internal Server Error\n"
},
{
"id": "QjUS6u626OGZuf3wN-xCV",
"language": "502",
"code": "// Bad Gateway\n"
},
{
"id": "KZwBVMxeX_cfibOFTr8f9",
"language": "504",
"code": "// Gateway Timeout\n"
}
],
"selectedLanguageId": "SlQoal8Cmz4rOST6qvYd_"
}
},
"children": [
{
"id": "D99YxpdM_uxm-hIrqz_wi",
"type": "paragraph",
"children": [
{
"text": "Once a valid payment agreement has approved by the payer this endpoint is used to create a payment instruction, which creates real time pull payments."
}
]
},
{
"id": "KxsFIFc0GcmCMVnshkZHN",
"type": "paragraph",
"children": [
{
"text": "You are allowed a maximum of 5 failed instructions in a 24 hour period, if you reach this limit you will need to wait until the next day to retry."
}
]
}
]
}