--- title: Create Payment Link slug: api/create-payment-link docTags: createdAt: 2026-09-01T06:52:33.550Z --- { "id": "k8TlMs_UJMgTL8nmxAhUx", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api-pay.monoova.com/v1/api/payment-links", "servers": [ { "url": "https://api-pay.monoova.com/v1/api/payment-links", "description": "Production URL" }, { "url": "https://sand-api-pay.monoova.com/v1/sandbox/api/payment-links", "description": "Sandbox URL" } ], "name": "Create Payment Link", "description": "

Creates a new payment link for accepting payments via card and/or PayTo methods.\nReturns a URL the payer can visit to complete the payment.\nStores the bearer token from the Authorization header in the vault using the payment ID as the key.

", "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": "

At least one payment method (card or payTo) must be provided

", "customType": "CreatePaymentLinkRequest", "schema": [ { "name": "amount", "kind": "required", "type": "number", "description": "Amount to charge the payer", "example": 100.5, "format": "decimal", "minimum": 0.01 }, { "name": "currency", "kind": "optional", "type": "string", "description": "ISO 4217 currency code", "example": "AUD", "default": "AUD", "enum": [ "AUD" ] }, { "name": "narrative", "kind": "optional", "type": "string", "description": "Payment narrative shown on the payer's bank statement", "example": "Invoice" }, { "name": "payer", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/Payer", "customType": "Payer", "schema": [ { "name": "firstName", "kind": "optional", "type": "string", "nullable": false, "description": "

Payer first name. Max 60 characters, excludes special characters.

", "example": "John", "maxLength": 60, "pattern": "^[^#<>$%^_=[\\]\\\\{}|;~`]+$" }, { "name": "lastName", "kind": "optional", "type": "string", "nullable": false, "description": "

Payer last name. Max 60 characters, excludes special characters.

", "example": "Doe", "maxLength": 60, "pattern": "^[^#<>$%^_=[\\]\\\\{}|;~`]+$" }, { "name": "customerId", "kind": "optional", "type": "string", "nullable": true, "description": "

Unique customer identifier. 1-40 alphanumeric characters with underscore and hyphen. Required when card.paymentDetails.saveOnSuccess is true.

", "example": "cust_123", "pattern": "^[a-zA-Z0-9_-]{1,40}$" }, { "name": "emailAddress", "kind": "optional", "type": "string", "nullable": false, "description": "

Payer email address. Max 40 characters, must be valid email format.

", "example": "john@example.com", "format": "email", "maxLength": 40, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~ -]+[\\.a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]*@[a-zA-Z0-9-_]+[.a-zA-Z0-9-_]*\\.[a-zA-Z]{2,15}$" }, { "name": "phone", "kind": "optional", "type": "string", "nullable": true, "description": "

Phone number. 6-20 characters with optional +, spaces, hyphens, or parentheses.

", "example": "+61-412345678", "maxLength": 20, "pattern": "^\\+?[0-9\\s\\-\\(\\)]{6,20}$" } ] }, { "name": "branding", "kind": "optional", "type": "object", "description": "

White-label branding configuration for customising the payment page

", "modelRef": "#/components/schemas/WhiteLabelConfig", "customType": "WhiteLabelConfig", "schema": [ { "name": "merchantName", "kind": "optional", "type": "string", "nullable": true, "description": "", "example": "Acme Corp" }, { "name": "logo", "kind": "optional", "type": "string", "nullable": true, "description": "", "example": "https://example.com/logo.png", "format": "uri" } ] }, { "name": "card", "kind": "optional", "type": "object", "nullable": true, "description": "", "modelRef": "#/components/schemas/CardDetails", "customType": "CardDetails", "schema": [ { "name": "enabled", "kind": "optional", "type": "boolean", "description": "Whether card payment is enabled for this payment link.", "example": true }, { "name": "paymentDetails", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/CardPaymentDetails", "customType": "CardPaymentDetails", "schema": [ { "name": "description", "kind": "optional", "type": "string", "nullable": false, "description": "

Card payment description shown to payer, required when enabling card payments.

", "example": "Pay by credit/debit card" }, { "name": "saveOnSuccess", "kind": "optional", "type": "boolean", "description": "Save card details on successful payment", "example": false }, { "name": "allowCredit", "kind": "optional", "type": "boolean", "description": "Allow credit card payments", "example": false }, { "name": "applySurcharge", "kind": "optional", "type": "boolean", "description": "Apply surcharge to payment amount", "example": false }, { "name": "capturePayment", "kind": "optional", "type": "boolean", "description": "Automatically capture payment after authorization", "example": true } ] }, { "name": "ledgerAccountNumber", "kind": "optional", "type": "string", "nullable": true, "description": "

Ledger account number that the payment should be attributed to. Optional, only allowed if feature is enabled for the account.

", "example": "612345678901234", "pattern": "^6[0-9]{15}$" }, { "name": "cardMerchantId", "kind": "optional", "type": "string", "nullable": true, "description": "

Card merchant ID for this payment. Impacts merchant details that appear on customer statements. Optional, defaults to mAccount details.

", "example": "MERCHANT-001", "pattern": "^[ -~]{1,35}$" } ] }, { "name": "payTo", "kind": "optional", "type": "object", "nullable": true, "description": "

PayTo payment details for creating a payment link (request only)

", "modelRef": "#/components/schemas/PayToDetailsRequest", "customType": "PayToDetailsRequest", "schema": [ { "name": "agreement", "kind": "optional", "type": "object", "description": "required when enabling payTo", "modelRef": "#/components/schemas/PayToAgreementRequest", "customType": "PayToAgreementRequest", "schema": [ { "name": "paymentTerms", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/PayToPaymentTerms", "customType": "PayToPaymentTerms", "schema": [ { "name": "amount", "kind": "optional", "type": "number", "nullable": true, "description": "

Agreement amount. Required if agreementType is FIXE. Must be < maximumAmount.

", "example": 100, "format": "decimal", "minimum": 0.01 }, { "name": "maximumAmount", "kind": "optional", "type": "number", "nullable": true, "description": "

Maximum amount per transaction. Not allowed if agreementType is FIXE. Must be >= amount & default is payment link amount if empty.

", "example": 150, "format": "decimal", "minimum": 0.01 }, { "name": "numberOfTransactionsPermitted", "kind": "optional", "type": "integer", "nullable": true, "description": "

Number of transactions permitted under the agreement. Default is 1 (unlimited if null)

", "example": 12, "format": "int32" }, { "name": "frequency", "kind": "optional", "type": "string", "nullable": true, "description": "

Payment frequency - ADHO (Ad Hoc), DAIL (Daily), WEEK (Weekly), FRTN (Fortnightly), MNTH (Monthly), QURT (Quarterly), MIAN (Semi-Annual), YEAR (Annual)

", "example": "MNTH", "enum": [ "ADHO", "DAIL", "WEEK", "FRTN", "MNTH", "QURT", "MIAN", "YEAR" ] }, { "name": "pointInTime", "kind": "optional", "type": "string", "nullable": true, "description": "

Point in time for payment execution (e.g., end of month, specific day)

", "example": "EndOfMonth" }, { "name": "agreementType", "kind": "optional", "type": "string", "nullable": true, "description": "

Agreement type - FIXE (Fixed: amount is fixed), USGB (Usage-based: amount based on usage), VARI (Variable: amount is variable)

", "example": "VARI", "enum": [ "FIXE", "USGB", "VARI" ] } ] }, { "name": "paymentDetails", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/PayToAgreementPaymentDetails", "customType": "PayToAgreementPaymentDetails", "schema": [ { "name": "description", "kind": "optional", "type": "string", "nullable": true, "description": "

Agreement description (max 140 characters). Either description or shortDescription must be provided.

", "example": "Monthly subscription", "maxLength": 140 }, { "name": "shortDescription", "kind": "optional", "type": "string", "nullable": true, "description": "

Short description (max 35 characters). Either description or shortDescription must be provided.

", "example": "Sub", "maxLength": 35 }, { "name": "purpose", "kind": "optional", "type": "string", "description": "Payment purpose code", "example": "RETL", "enum": [ "MORT", "UTIL", "LOAN", "DEPD", "GAMP", "RETL", "SALA", "PERS", "GOVT", "PENS", "TAXS", "OTHR" ] }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

Start date in yyyy-MM-dd format - must be a future date

", "example": "2026-05-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "nullable": true, "description": "

End date in yyyy-MM-dd format - required if automaticRenewal is false; must be after startDate

", "example": "2026-12-31", "format": "date" }, { "name": "automaticRenewal", "kind": "optional", "type": "boolean", "description": "

Whether the mandate renews automatically. If false, endDate is required. If true, endDate is prohibited.

", "example": true } ] } ] }, { "name": "payeeDetails", "kind": "optional", "type": "object", "description": "required when enabling payTo", "modelRef": "#/components/schemas/Payee", "customType": "Payee", "schema": [ { "name": "payeeType", "kind": "optional", "type": "string", "description": "

Payee type - ORGN (Organization) or PERS (Person)

", "enum": [ "ORGN", "PERS" ] }, { "name": "payeeLinkedBsb", "kind": "optional", "type": "string", "nullable": true, "description": "

Bank-State-Branch code (XXX-XXX format)

", "example": "012-345" }, { "name": "payeeLinkedAccount", "kind": "optional", "type": "string", "nullable": true, "description": "

Account number (max 28 characters)

", "example": "123456789", "maxLength": 28 }, { "name": "payeeLinkedPayId", "kind": "optional", "type": "string", "nullable": true, "description": "

PayID value (phone or email)

", "example": "+61-422020901" }, { "name": "payeeLinkedPayIdType", "kind": "optional", "type": "string", "nullable": true, "description": "

PayID type - required if payeeLinkedPayId is provided

", "example": "PhoneNumber" }, { "name": "payeeAccountName", "kind": "optional", "type": "string", "nullable": true, "description": "

Payee account name (max 140 characters), required when using external BSB (not from Monoova)

", "example": "Acme Corp", "maxLength": 140 }, { "name": "ultimatePayee", "kind": "optional", "type": "string", "nullable": true, "description": "

Ultimate payee name (max 140 characters), required when using external BSB (not from Monoova)

", "example": "Acme Corporation", "maxLength": 140 } ] } ] } ], "modelRef": "#/components/schemas/CreatePaymentLinkRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "bearerAuth", "name": "bearerAuth", "kind": "optional", "type": "http", "description": "Bearer token authentication for API endpoints", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "201", "description": "Payment link successfully created", "jsonExample": "", "isExpanded": true, "headers": [ { "kind": "optional", "name": "Location", "type": "string", "description": "URL of the created payment link" } ], "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "CreatePaymentLinkResponse", "schema": [ { "name": "merchantReference", "kind": "required", "type": "string", "description": "Merchant reference ID", "example": "ref_123456" }, { "name": "paymentUrl", "kind": "required", "type": "string", "description": "URL the payer can visit to complete the payment", "example": "https://payment.example.com/pay/ref_123456", "format": "uri" }, { "name": "expiry", "kind": "required", "type": "string", "description": "

Payment link expiration time (linked to token expiration with max of 5 days)

", "example": "2026-05-30T12:00:00Z", "format": "date-time" } ], "modelRef": "#/components/schemas/CreatePaymentLinkResponse", "isExpanded": true } ] }, { "statusCode": "400", "description": "Validation error", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ValidationProblemDetails", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "", "example": "https://tools.ietf.org/html/rfc7231#section-6.5.1" }, { "name": "title", "kind": "optional", "type": "string", "description": "", "example": "One or more validation errors occurred." }, { "name": "status", "kind": "optional", "type": "integer", "description": "", "example": 400 }, { "name": "errors", "kind": "optional", "type": "map", "description": "", "example": "{\"amount\":[\"'Amount' must be greater than 0.\"],\"currency\":[\"Currency must be one of: AUD.\"]}", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ValidationProblemDetails", "isExpanded": true } ] }, { "statusCode": "401", "description": "Missing or invalid Bearer token", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ProblemDetails", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "", "example": "https://tools.ietf.org/html/rfc7231#section-6.5.1" }, { "name": "title", "kind": "optional", "type": "string", "description": "", "example": "Problem Details" }, { "name": "status", "kind": "optional", "type": "integer", "description": "", "example": 400 }, { "name": "detail", "kind": "optional", "type": "string", "description": "", "example": "Bearer token is required." } ], "modelRef": "#/components/schemas/ProblemDetails", "isExpanded": true } ] }, { "statusCode": "500", "description": "Server error", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ProblemDetails", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "", "example": "https://tools.ietf.org/html/rfc7231#section-6.5.1" }, { "name": "title", "kind": "optional", "type": "string", "description": "", "example": "Problem Details" }, { "name": "status", "kind": "optional", "type": "integer", "description": "", "example": 400 }, { "name": "detail", "kind": "optional", "type": "string", "description": "", "example": "Bearer token is required." } ], "modelRef": "#/components/schemas/ProblemDetails", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "bwnZphmm645Q7zeSZkWVU", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api-pay.monoova.com/v1/api/payment-links \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"amount\": 100.5,\n \"currency\": \"AUD\"\n }'" }, { "id": "ZiIwM8ukhxiyTLpaoXEfz", "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 \"amount\": 100.5,\n \"currency\": \"AUD\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api-pay.monoova.com/v1/api/payment-links\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "qcVty-uwhrqCFC-Q_zHTL", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api-pay.monoova.com/v1/api/payment-links\")\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 \"amount\": 100.5,\n \"currency\": \"AUD\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "uKhw8fAJoJbpBd1L8HhHJ", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api-pay.monoova.com/v1/api/payment-links\"\n\npayload = json.dumps({\n \"amount\": 100.5,\n \"currency\": \"AUD\"\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": "bwnZphmm645Q7zeSZkWVU" }, "results": { "languages": [ { "id": "C4WjHGCxCuVHLI-k0GcAO", "language": "201", "code": "// Payment link successfully created\n{\n \"merchantReference\": \"ref_123456\",\n \"paymentUrl\": \"https://payment.example.com/pay/ref_123456\",\n \"expiry\": \"2026-05-30T12:00:00Z\"\n}" }, { "id": "CCqU11STvnEdmUbpveP0U", "language": "400", "code": "// Validation error\n{\n \"type\": \"https://tools.ietf.org/html/rfc7231#section-6.5.1\",\n \"title\": \"One or more validation errors occurred.\",\n \"status\": 400,\n \"errors\": \"{\\\"amount\\\":[\\\"'Amount' must be greater than 0.\\\"],\\\"currency\\\":[\\\"Currency must be one of: AUD.\\\"]}\"\n}" }, { "id": "y8XNaXIvh4pZnzQS3FkLg", "language": "401", "code": "// Missing or invalid Bearer token\n{\n \"type\": \"https://tools.ietf.org/html/rfc7231#section-6.5.1\",\n \"title\": \"Problem Details\",\n \"status\": 400,\n \"detail\": \"Bearer token is required.\"\n}" }, { "id": "aZPCJGIy8Pxm66kh0P3gu", "language": "500", "code": "// Server error\n{\n \"type\": \"https://tools.ietf.org/html/rfc7231#section-6.5.1\",\n \"title\": \"Problem Details\",\n \"status\": 400,\n \"detail\": \"Bearer token is required.\"\n}" } ], "selectedLanguageId": "C4WjHGCxCuVHLI-k0GcAO" } }, "children": [ { "text": "" } ] }