--- updatedAt: 2026-09-03T21:21:46.000Z agentTools: projectIndex: https://docs.clik2pay.com/llms.txt --- # Create Payment Request Returns a unique {paymentRequestId} for a payment request transaction. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Open APIs", "version": "1.0", "description": "The public facing APIs to interact with the our system\n\nVersioning of endpoints in this specification will increase when there are breaking changes made to the implementation. For this purpose, adding properties to resources will not be considered a breaking change, so implementations must have the flexibility to ignore unspecified properties when deserializing resources.\n\nOther structural changes, such as removal or renaming of properties and parameters will be considered breaking and cause a version increase. Older versions will be deprecated and only supported for a limited period after a version increase.", "contact": { "name": "Clik2pay", "email": "admin@clik2pay.com", "url": "https://www.clik2pay.com/" } }, "servers": [ { "url": "https://api.clik2pay.com/open/v1", "description": "production" }, { "url": "https://api.sandbox.clik2pay.com/open/v1", "description": "sandbox" } ], "tags": [ { "name": "Payment Requests API" } ], "paths": { "/payment-requests": { "post": { "summary": "Create Payment Request", "tags": [ "Payment Requests API" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post-v1-merchants-merchantId-payment-requests", "description": "Returns a unique {paymentRequestId} for a payment request transaction.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "security": [ { "JWT": [], "APIKey": [] } ], "parameters": [] } } }, "components": { "schemas": { "PaymentRequest": { "description": "Represents the structure of a payment request", "type": "object", "x-examples": {}, "x-internal": false, "title": "Payment Request resource definition", "properties": { "id": { "type": "string", "description": "The unique identifier for a payment request transaction assigned by us. This value is a resource identifier and is used for further reference to the transaction (eg. GET Payment Request Status or a Webhook).", "example": "e6a16402-fade-4fb2-8bfc-27194d3e3f87", "readOnly": true }, "merchantTransactionId": { "type": "string", "description": "Optional value to allow tracking a transaction back to your system. The ID must be unique across transactions for a merchant.", "pattern": "^[a-zA-Z0-9\\-\\.]+$", "minLength": 6, "maxLength": 32, "example": "f87ebbed8c0a437585a462d36227f821" }, "amount": { "type": "number", "description": "The payment amount in Canadian dollars. (Use “null” when type is FLEX.)", "example": 50.25, "format": "double", "multipleOf": 0.01, "minimum": 0.01, "maximum": 10000 }, "type": { "type": "string", "enum": [ "ECOMM", "MOBIL", "EBILL", "SMART", "FLEX" ], "description": "The type of transaction for the payment request:\n\n * ECOMM For web-based applications where the payment is initiated directly from your website or online platform. This type is ideal for standard e-commerce checkouts.\n * MOBIL This type has been deprecated.\n * EBILL Designed for scenarios where you need to send payment links externally. This includes generating payment links for distribution via email, SMS, QR codes, or embedding directly into your merchant-managed pages.\n * SMART Read only. Creates reusable payment links. This is suitable for general payment collection where you can set certain parameters to be filled out by the customer prior to making a payment.\n * FLEX Allows the customer to pay an amount within a dynamic range you define, enabling partial payments towards a total. You can specify minimum and/or maximum payment thresholds, giving the customer control over the immediate payment amount until the full balance is paid.\n", "example": "EBILL" }, "paymentMethod": { "type": "string", "enum": [ "INTERAC", "EFT" ], "description": "The payment method of the payment request.", "example": "INTERAC", "readOnly": true }, "status": { "$ref": "#/components/schemas/PaymentRequestStatus" }, "deliveryDate": { "type": "string", "format": "date", "description": "The date on which the payment request is delivered to the payer." }, "deliveryMode": { "type": "string", "description": "The method to use to notify the payer of the request.", "enum": [ "SMS", "EMAIL", "NONE" ] }, "estimatedSettlementDate": { "type": "string", "format": "date", "description": "The date on which settlement is expected to occur.", "readOnly": true }, "merchant": { "type": "object", "description": "Details of the merchant that owns the payment request.", "properties": { "id": { "type": "string", "description": "A unique identifier for a merchant within Clik2pay’s environment.", "format": "uuid", "example": "3c1fe80f-e068-420e-9fc1-428b4fbd21af" }, "name": { "type": "string", "description": "The name of the merchant.", "example": "Merchant Inc", "readOnly": true }, "brand": { "type": "object", "description": "Details of the merchant brand for the payment request.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the merchant brand for the payment request. Will default to the merchant’s default brand.", "example": "e6a16402-fade-4fb2-8bfc-27194d3e3f87" }, "refundWindowDays": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 731, "description": "The number of days in which refunds are allowed.", "readOnly": true }, "links": { "type": "array", "description": "Links to resources related to the brand.", "items": { "$ref": "#/components/schemas/HATEOASLink" } } }, "readOnly": true }, "paymentMethods": { "type": "array", "description": "The methods of payment allowed for the merchant.", "items": { "type": "string", "enum": [ "INTERAC", "EFT" ], "readOnly": true } }, "links": { "type": "array", "description": "Links to resources related to the merchant.", "items": { "$ref": "#/components/schemas/HATEOASLink" } } } }, "payer": { "type": "object", "description": "The customer fulfilling the payment.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The first and last name of the payer.", "example": "Jane Doe", "minLength": 3, "pattern": "^([a-zA-Z0-9àâäèéêëîïôùûüÿçœÀÂÄÈÉÊËÎÏÔÙÛÜŸÇŒ'\\-.,]+ )+[a-zA-Z0-9àâäèéêëîïôùûüÿçœÀÂÄÈÉÊËÎÏÔÙÛÜŸÇŒ'\\-.,]+$", "maxLength": 100 }, "merchantAccountId": { "type": "string", "description": "Account ID of the payer within the merchant’s system.", "example": "AA6789", "pattern": "^[a-zA-Z0-9]+$", "minLength": 4, "maxLength": 50 }, "email": { "type": "string", "format": "email", "description": "The email address to contact the payer. Required when deliveryMode is EMAIL.", "maxLength": 64 }, "mobileNumber": { "type": "string", "description": "The mobile number to contact the payer. Required when deliveryMode is SMS. Must be an active Canadian mobile number.", "example": "4165551234", "pattern": "^\\d+$", "minLength": 10, "maxLength": 10 }, "preferredLanguage": { "type": "string", "example": "en", "description": "The language presented to the payer on Interac\\'s Gateway page. Should be a 2 character language code, as per the ISO 639-1 standard. Currently, only English and French are supported.", "enum": [ "en", "fr" ] } } }, "flexDetails": { "$ref": "#/components/schemas/PaymentRequestFlexDetails" }, "dueDate": { "type": "string", "format": "date", "description": "The date (ISO 8601) on which payment is due. Informational field only; no further action is taken by our systems if the date is surpassed." }, "createdDateTime": { "type": "string", "minLength": 1, "format": "date-time", "description": "The date and time (displayed in UTC) the payment request was created.", "readOnly": true }, "shortCode": { "type": "string", "description": "A short code used to identify the transaction. Reflected in URL in the paymentLink and qrCodeLink fields.", "example": "ABCDEFG", "readOnly": true }, "paymentLink": { "type": "string", "format": "uri", "description": "The direct URL the payer can use to complete the payment.", "example": "https://pay.clik2pay.com/r/ABCDEFG", "readOnly": true }, "qrCodeLink": { "type": "string", "format": "uri", "description": "The link to a QR code image that reflects the payment link.", "example": "https://pay.clik2pay.com/qr/ABCDEFG", "readOnly": true }, "displayMessage": { "type": "string", "minLength": 3, "maxLength": 250, "example": "The message displayed to the payer.", "pattern": "^[a-zA-Z0-9àâäèéêëîïôùûüÿçœÀÂÄÈÉÊËÎÏÔÙÛÜŸÇŒ '\\-.,*:%()]+$", "description": "The message presented to the payer on Interac\\'s Gateway page. If not set, a default message will be displayed." }, "invoiceNumber": { "type": "string", "example": "ABC#12389865433", "maxLength": 50, "description": "Merchant’s invoice number to apply to the transaction for tracking purposes.", "pattern": "^[a-zA-Z0-9 \\-*()_#;&/]*$" }, "businessUnit": { "type": "string", "description": "Merchant-defined value. Allows a merchant to refer to their internal business unit, department, division, etc.", "maxLength": 50, "example": "Mobility", "pattern": "^[a-zA-Z0-9àâäèéêëîïôùûüÿçœÀÂÄÈÉÊËÎÏÔÙÛÜŸÇŒ '\\-.,*:%()_&/]*$" }, "emailTemplate": { "type": "object", "description": "Email notification to the payer will be sent with this template.", "properties": { "id": { "type": "string", "description": "The unique identifier for an email template. Not used with ECOMM transactions.", "example": "f1887355-c876-4c17-b0f3-53d5ebd1b293" } } }, "createdBy": { "type": "string", "description": "The user or merchant API request that created the payment request.", "example": "example@clik2pay.com", "readOnly": true }, "events": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "A list of events for a payment request, reflecting changes in status.", "items": { "type": "object", "description": "An event representing a change in status.", "properties": { "status": { "$ref": "#/components/schemas/PaymentRequestStatus" }, "dateTime": { "type": "string", "description": "The date and time of the event.", "format": "date-time", "readOnly": true } }, "readOnly": true }, "readOnly": true }, "refunds": { "type": "array", "description": "Details of any refunds that have been initiated for the payment request.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for a refund payment.", "readOnly": true }, "amount": { "type": "number", "format": "double", "minimum": 0.01, "multipleOf": 0.01, "example": 50.25, "description": "The amount in Canadian dollars.", "readOnly": true }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "links": { "type": "array", "description": "Links to the refund resource.", "items": { "$ref": "#/components/schemas/HATEOASLink" }, "readOnly": true } }, "readOnly": true }, "readOnly": true }, "links": { "type": "array", "description": "Links to resources related to the payment.", "items": { "$ref": "#/components/schemas/HATEOASLink" }, "readOnly": true } }, "required": [ "amount", "type", "payer" ] }, "PaymentRequestStatus": { "type": "string", "title": "Payment Request Status", "enum": [ "CREATED", "SCHEDULED", "EMAIL_SENT", "SMS_SENT", "ACTIVE", "PROCESSING", "PAID", "SETTLED", "FAILED", "CANCELLED", "DECLINED", "EXPIRED", "DEPOSIT_FAILED", "LINK_FOLLOWED" ], "description": "The status of a payment request.", "readOnly": true }, "PaymentRequestFlexDetails": { "title": "Amount Range", "type": "object", "description": "Data used for flexible payments. Required only if payment type is FLEX.", "properties": { "requested": { "type": "number", "format": "double", "minimum": 0.01, "maximum": 10000, "multipleOf": 0.01, "description": "The payment amount requested by the merchant.", "example": 40.75 }, "minimum": { "type": "number", "format": "double", "multipleOf": 0.01, "maximum": 10000, "minimum": 0.01, "description": "The minimum payment amount set by the merchant.", "example": 30.25 }, "maximum": { "type": "number", "minimum": 0.01, "maximum": 10000, "multipleOf": 0.01, "format": "double", "description": "The maximum payment amount set by the merchant.", "example": 80.75 } } }, "PaymentStatus": { "type": "string", "title": "Refunds, payouts, reimbursements & returns status", "enum": [ "CREATED", "READY", "ACTIVE", "PAID", "FAILED", "SETTLED", "CANCELLED", "EXPIRED", "DECLINED", "SECURITY-FAILED" ], "description": "The status of a payment transaction.", "readOnly": true }, "Error": { "title": "Error", "type": "object", "description": "Error response body provided on a failed request", "properties": { "message": { "type": "string", "description": "A message describing the reason for the error response", "example": "Failed to parse resource" }, "errors": { "type": "array", "description": "A list of detailed errors that indicate problems with the request. Usually empty unless the response was a Bad Request (400)", "items": { "type": "object", "description": "An error produced by the request input", "properties": { "property": { "type": "string", "description": "The property or object name that failed to be read", "example": "email" }, "error": { "type": "string", "example": "must be a well-formed email address", "description": "A descriptive message describing the reason for the failure" } } } } } }, "HATEOASLink": { "title": "HATEOAS Link", "type": "object", "description": "", "readOnly": true, "properties": { "rel": { "type": "string", "description": "The relation of the linked resource", "example": "payment-request" }, "href": { "type": "string", "example": "https://api.clik2pay.com/open/v1/payment-requests/e6a16402-fade-4fb2-8bfc-27194d3e3f87", "format": "uri", "description": "The target URL of the linked resource" } } } }, "securitySchemes": { "JWT": { "type": "http", "scheme": "bearer" }, "APIKey": { "type": "apiKey", "name": "x-api-key", "in": "header", "x-amazon-apigateway-api-key-source": "HEADER" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true } } ```