--- updatedAt: 2026-08-14T03:35:39.000Z agentTools: projectIndex: https://developer.moneris.com/moneris-api/llms.txt --- # Create KONEK Payment Consent Merchant request using KONEK SDK to create payment consent request # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "version": "2.15.1", "title": "Moneris API", "description": "Moneris API Platform\n\n\n[\"Run](https://god.gw.postman.com/run-collection/25575461-f04750a0-88e9-4c83-8b58-a3aff15eeea8?action=collection%2Ffork&collection-url=entityId%3D25575461-f04750a0-88e9-4c83-8b58-a3aff15eeea8%26entityType%3Dcollection%26workspaceId%3D5d2a9a0f-57a7-441c-b2af-fe6315e80a08)", "termsOfService": "https://www.moneris.com/en/legal/terms-of-use", "contact": { "url": "https://api-developer.moneris.com", "email": "api@moneris.com" }, "license": { "name": "Moneris", "url": "https://developer.moneris.com/Agreements/Terms%20of%20Use" }, "x-audience": "external-public" }, "servers": [ { "url": "https://api.sb.moneris.io", "description": "Sandbox server (uses test data)", "x-internal": false }, { "url": "https://api.moneris.io", "description": "Production server (uses live data)", "x-internal": false } ], "tags": [ { "name": "KONEK", "description": "KONEK APIs for Merchant - Consent Management" } ], "paths": { "/konek/payment-consents": { "parameters": [ { "$ref": "#/components/parameters/apiVersion" }, { "$ref": "#/components/parameters/correlationId" }, { "$ref": "#/components/parameters/merchantId" } ], "post": { "summary": "Create KONEK Payment Consent", "description": "Merchant request using KONEK SDK to create payment consent request", "operationId": "createKonekPaymentConsent", "security": [ { "OAuth2": [ "payment.write" ] }, { "ApiKeyAuth": [] } ], "tags": [ "KONEK" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createConsentRequest" }, "examples": { "createConsent": { "$ref": "#/components/examples/createConsentRequest" } } } } }, "responses": { "201": { "$ref": "#/components/responses/createConsentSuccessResponse" }, "400": { "$ref": "#/components/responses/badRequest" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "409": { "$ref": "#/components/responses/conflict" }, "422": { "$ref": "#/components/responses/createPaymentUnprocessableContentResponse" }, "429": { "$ref": "#/components/responses/tooManyRequests" }, "500": { "$ref": "#/components/responses/internalServer" }, "503": { "$ref": "#/components/responses/serviceUnavailable" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "An API key is a token that a client provides when making API calls.\n\nAPI keys are supposed to be a secret that only the client and server know about.\n" }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.\n\nOAuth relies on authentication scenarios, that allows the resource owner (user) to share the protected content from the server, hosting the resource, without sharing their credentials. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.\n\nMoneris recommends the use of OAuth 2.0 as it provides fine grained authorization levels.\n", "flows": { "clientCredentials": { "tokenUrl": "/oauth2/token", "scopes": { "payment.read": "Grants read access to payment related APIs", "payment.write": "Grants read & write access to payment related APIs", "refund.read": "Grants read access to refunds", "refund.write": "Grants read & write access to refunds", "customer.read": "Grants read access to customer data", "customer.write": "Grants read & write access to customer data", "kount.read": "Grants read access to Kount inquiries", "kount.write": "Grants read & write access to Kount inquiries", "onboarding.merchant.read": "Grants read access to merchant onboarding related APIs", "onboarding.merchant.write": "Grants read & write access to merchant onboarding related APIs", "onboarding.order.read": "Grants read access to onboarding orders related APIs", "onboarding.order.write": "Grants read & write access to onboarding orders related APIs", "dispute.read": "Grants read access to disputes", "dispute.write": "Grants read & write access to disputes", "payout.write": "Grants read & write access to payouts", "partner.account.write": "Grants read & write access to partner merchant accounts" } } } } }, "schemas": { "apiVersion": { "description": "The endpoint's API Version. Must be provided through headers.\n", "type": "string", "example": "2026-08-14", "default": "2026-08-14" }, "merchantId": { "type": "string", "description": "Thirteen character long identification provided to merchants by Moneris. \n", "minLength": 13, "maxLength": 13, "example": "0123456789101" }, "idempotencyKey": { "type": "string", "description": "A Unique Identifier that is required for handling idempotent requests. \n\nNote: Moneris encourages the use of UUID Version 4 in APIs as an idempotency key.\" \n", "minLength": 1, "maxLength": 36, "example": "b3e1f8c2-4d2a-4e6b-9c1a-2f3e4d5b6a7c" }, "konekMerchantId": { "type": "string", "description": "Unique Merchant ID assigned by Konek during merchant onboarding", "minLength": 10, "maxLength": 50, "example": "d0d9c3f92dad40328afa812a198510fc" }, "amount": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 999999999, "example": 10000, "description": "Amount" }, "currency": { "type": "string", "description": "Provides the three letter currency code according the ISO 4217 standard. \n\nFor a complete list of currency codes, visit: https://en.wikipedia.org/wiki/ISO_4217\n", "minLength": 3, "maxLength": 4, "example": "CAD", "format": "iso-4217" }, "orderItem": { "title": "orderItem", "description": "Transaction represents one-time purchase or recurring within an order", "type": "object", "properties": { "itemName": { "type": "string", "description": "the name of a item as specified by the Merchant.", "maxLength": 100, "nullable": true }, "itemReference": { "type": "string", "description": "A unique value to identify the transaction", "maxLength": 100, "nullable": true }, "itemPaymentType": { "description": "Type of transaction in the order, note that `SPLIT` is not valid in the order transaction", "type": "string", "enum": [ "SINGLE", "SPLIT", "RECURRING" ], "example": "SINGLE" }, "amount": { "description": "Amount of the transaction, in the case of RECURRING, this amount would be the recurring payment amount", "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } }, "quantity": { "description": "Quantity of the item", "type": "integer", "format": "int32", "nullable": true }, "description": { "description": "A short description of the line item", "type": "string", "nullable": true, "maxLength": 100 }, "recurringInformation": { "nullable": true, "title": "recurringInformation", "description": "Specifies the frequencies and limits for the recurring order and needs to be present if the `itemPaymentType is RECURRING`", "type": "object", "properties": { "amountCapped": { "description": "Specifies the max amount the customer can be charged per billing cycle for RECURRING. One of `amountCapped` and `amountVariance` must be specified. If `amountCapped` is specified:\n * The value must be greater than `amount` value\n * The value in `amountVariance` is ignored", "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } }, "amountVariance": { "type": "number", "format": "double", "description": "Specifies in % that the accepted variance in the amount per billing cycle for RECURRING. One of `amountCapped` and `amountVariance` must be specified. If `amountCapped` is specified this value is ignored.", "nullable": true, "minimum": 0.01, "maximum": 100, "example": 2.5 }, "dayOfMonth": { "description": "Day of month that the RECURRING payment occurs on. Required if both:\n * `frequencyType` is `MONTH`\n * `dayOfWeek` or `dayOfMonth` is not specified\nAllowed values are from 1 to 31, if a month has less then provided days then the payment will be accepted on the last day of the month.", "type": "integer", "format": "int32", "nullable": true, "minimum": 1 }, "dayOfWeek": { "type": "string", "description": "Day of week that the RECURRING payment occurs on. Required if either\n * `frequencyType` is `WEEK`\n * `frequencyType` is `MONTH` and `dayOfMonth` is not specified", "nullable": true, "enum": [ "SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT" ], "example": "SUN" }, "endDate": { "type": "string", "description": "End date of the RECURRING payment.", "format": "date-time", "nullable": true, "example": "2021-04-04T04:04:04Z" }, "frequencyRate": { "type": "integer", "format": "int32", "description": "The waiting interval between payments for the RECURRING transactions", "nullable": true, "minimum": 1, "maximum": 50 }, "frequencyType": { "type": "string", "description": "Frequency of the payments in the billing cycle for RECURRING.", "enum": [ "DAY", "WEEK", "MONTH", "END_OF_MONTH" ], "example": "DAY", "nullable": true }, "maxNumberOfPayments": { "type": "integer", "format": "int32", "description": "Total number of payments in the RECURRING setup.", "minimum": 1, "maximum": 99, "nullable": true }, "recurringType": { "type": "string", "description": "The specific nature of the recurring transaction that the customer is initiating. \n * `SUBSCRIPTION` - regular recurring setup with fixed frequency and fixed or variable amount. \n * `TOP_UP `- recurring setup where payment is requested only when the balance amount hit a threshold. This is fixed amount but frequency is variable. \n * `PAY_AS_YOU_GO` - recurring setup where payment is requested only when the customer uses a service. This is variable amount and frequency. \n * `EBP` - recurring setup with fixed amount and frequency, but the amount will be adjusted at the end of the year. ", "enum": [ "SUBSCRIPTION", "TOP_UP", "PAY_AS_YOU_GO", "EBP" ], "example": "SUBSCRIPTION", "nullable": true }, "startDate": { "type": "string", "description": "Start date of the RECURRING payment. Defaults to the current time if left blank.", "format": "date-time", "example": "2021-04-04T04:04:04Z", "nullable": true }, "weekOfMonth": { "type": "string", "description": "Week of month that the RECURRING payment occurs on. Required if both:\n * `frequencyType` is `MONTH`\n * `dayOfWeek` is specified and `dayOfMonth` is not specified", "enum": [ "FIRST", "SECOND", "THIRD", "FOURTH", "LAST" ], "nullable": true, "example": "FIRST" } }, "required": [ "frequencyType" ] }, "itemType": { "nullable": true, "type": "string", "description": "Type of item in the card; \n`GIFT_CARD` - Gift card \n`CRYPTO_CURRENCY` - Crypto currency \n`TOP_UP` - Digital Wallet top-up \n`OTHER` - Other items\n", "enum": [ "GIFT_CARD", "CRYPTO_CURRENCY", "TOP_UP", "OTHER" ], "example": "GIFT_CARD" } }, "required": [ "itemPaymentType", "amount" ] }, "orderDetails": { "title": "orderDetails", "description": "Order details from the merchant for the consent", "type": "object", "properties": { "merchantOrderReference": { "type": "string", "description": "A unique value to identify the order or cart", "maxLength": 100 }, "merchantCustomerReference": { "nullable": true, "type": "string", "description": "Unique Identification for the Customer. This can be an identifier generated from a merchant-defined identifier.", "example": "911677-212", "minLength": 1, "maxLength": 50 }, "placementMode": { "type": "string", "description": "Placement mode", "enum": [ "STANDARD", "EXPRESS" ], "example": "STANDARD" }, "shipmentType": { "type": "string", "description": "Indicates how the merchandise will be shipped to the customer.\n * SINGLE - order fulfillment with single shipment\n * SPLIT - order fulfillment with split shipments\n * NONE - order fulfillment without shipmment", "enum": [ "SINGLE", "SPLIT", "NONE" ], "example": "SINGLE" }, "items": { "type": "array", "description": "A list of order items and their recurring setups if available. Max 100 items permitted.", "items": { "$ref": "#/components/schemas/orderItem" }, "maxItems": 100 } }, "required": [ "shipmentType", "placementMode", "items", "merchantOrderReference" ], "x-ii18n-description-fr": "Détails de la commande du marchand pour le consentement." }, "dataField": { "description": "List of name/value pairs containing additional fee factors.", "type": "object", "required": [ "name", "amount" ], "properties": { "name": { "description": "Name", "type": "string", "maxLength": 100 }, "amount": { "description": "Any additional fee amount merchant included. The amount can range from the min value to the max value specified with the amount data element.", "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } } } }, "additionalFees": { "description": "List of additional fee elements.", "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/dataField" } }, "orderPayment": { "title": "orderPayment", "description": "Payment details of the order, in the case of recurring setups this field represents the first payment of the order.", "type": "object", "properties": { "subTotalAmount": { "description": "Sub total of the order", "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } }, "shippingCost": { "description": "Shipping cost of the order", "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } }, "totalTaxAmount": { "description": "Total tax calculated for the order", "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } }, "amount": { "description": "First payment amount of the order. The amount can be 0 if order item contains RECURRING to support a scenario where other payment methods such as Gift Cards may be used for the initial payment Otherwise it must be a value greater than 0.", "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" } }, "required": [ "amount", "currency" ], "example": { "amount": 16000, "currency": "CAD" } }, "additionalFees": { "$ref": "#/components/schemas/additionalFees" } }, "required": [ "amount" ], "x-ii18n-description-fr": "Détails de paiement de la commande, dans le cas de configurations récurrentes, ce champ représente le premier paiement de la commande." }, "consentCreate": { "title": "ConsentCreate", "type": "object", "properties": { "konekMerchantId": { "$ref": "#/components/schemas/konekMerchantId" }, "order": { "$ref": "#/components/schemas/orderDetails" }, "payment": { "$ref": "#/components/schemas/orderPayment" } }, "required": [ "konekMerchantId", "order", "payment" ] }, "contactFields": { "description": "Contact fields that can be requested by the merchant", "type": "string", "enum": [ "NAME", "EMAIL", "PHONE", "SHIPPING_ADDRESS", "IDENTITY_VERIFICATION_AGE", "IDENTITY_VERIFICATION_RESIDENCE_POSTAL_CODE" ], "example": "NAME" }, "accountType": { "type": "string", "description": "The type of account for the payment", "enum": [ "BANK_ACCOUNT_SAVINGS", "BANK_ACCOUNT_CHEQUING", "BANK_ACCOUNT_LINE_OF_CREDIT", "VISA_CREDIT", "VISA_DEBIT", "MASTERCARD_CREDIT", "MASTERCARD_DEBIT", "AMEX_CREDIT" ], "example": "BANK_ACCOUNT_SAVINGS" }, "createConsentRequest": { "allOf": [ { "type": "object", "properties": { "idempotencyKey": { "$ref": "#/components/schemas/idempotencyKey" } }, "required": [ "idempotencyKey" ] }, { "$ref": "#/components/schemas/consentCreate" }, { "type": "object", "title": "createConsentRequest", "description": "Consent Create request from Merchant", "required": [ "supportedPaymentMethods" ], "properties": { "requiredContactFields": { "type": "array", "description": "Specifies list of required contact fields of the customer", "items": { "$ref": "#/components/schemas/contactFields" }, "maxItems": 6, "uniqueItems": true }, "supportedPaymentMethods": { "type": "array", "description": "Specifies the list of payment method account types the merchant supports for the transaction", "items": { "$ref": "#/components/schemas/accountType" }, "minItems": 1, "maxItems": 12, "example": [ "BANK_ACCOUNT_SAVINGS", "VISA_CREDIT" ] } } } ] }, "paymentConsentId": { "type": "string", "description": "Unique identifier of the Payment Consent within KONEK. Assigned by KONEK.", "maxLength": 36, "example": "ada78940-643e-4d70-be14-3bbb36992095" }, "deviceProfileSessionId": { "type": "string", "description": "A unique identifier generated by the server for initiationg device profiling.", "maxLength": 50, "example": "ada78940-643e-4d70-be14-3bbb36992095" }, "address": { "type": "object", "description": "The postal address including street, town/city, province, and postal code.\nOptionally an unit number can be provided.\n", "properties": { "unitNumber": { "nullable": true, "type": "string", "description": "Unit number", "minLength": 1, "maxLength": 19, "example": "123A" }, "streetNumber": { "nullable": true, "type": "string", "description": "Street number", "minLength": 1, "maxLength": 19, "example": "3300" }, "streetName": { "nullable": true, "type": "string", "description": "Street name", "minLength": 1, "maxLength": 100, "example": "Bloor" }, "city": { "nullable": true, "type": "string", "description": "Identifies the city.\n", "minLength": 1, "maxLength": 50, "example": "Toronto" }, "province": { "nullable": true, "type": "string", "description": "Province or state ISO 3166-2 code ", "minLength": 1, "maxLength": 3, "format": "iso-3166-2", "example": "ON" }, "postalCode": { "nullable": true, "type": "string", "description": "Postal or zip code", "minLength": 1, "maxLength": 30, "example": "M8X 2X2" }, "country": { "nullable": true, "type": "string", "description": "Provides the two letter country code according the ISO 3166-1 alpha-2 standard. \nFor a complete list of country codes, visit: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.\n", "minLength": 2, "maxLength": 2, "example": "CA", "format": "iso-3166" } }, "example": { "unitNumber": "123A", "streetNumber": "3300", "streetName": "Bloor Street West", "city": "Toronto", "province": "ON", "postalCode": "M8X 2X2", "country": "CA" } }, "storeAddress": { "description": "Address of the store", "allOf": [ { "$ref": "#/components/schemas/address" }, { "type": "object", "properties": { "ruralPostalAddress": { "type": "string", "description": "Specifies Rural Route or PO Box number", "maxLength": 100, "nullable": true, "example": "PO BOX 4001 STN A" } } } ] }, "shippingAddress": { "allOf": [ { "$ref": "#/components/schemas/storeAddress" }, { "type": "object", "required": [ "recipientName" ], "properties": { "recipientName": { "type": "string", "description": "Name of the addressee", "minLength": 1, "maxLength": 100 }, "shippingAddressReference": { "description": "Unique identifier of the shipping address", "nullable": true, "type": "string", "format": "uuid" }, "addressLine1": { "description": "Refers to the first line of the address. This is added to support cases like 'C/O' etc.", "nullable": true, "type": "string", "maxLength": 100 } } } ] }, "userAuthMethod": { "type": "string", "description": "Specifies the method used to authenticate the user, valid values are; \n`FI_AUTH` - Customer is authenticated by FI \n`PARTNER_FI_AUTH` - Customer is authenticated by Partner FI \n`USER_SENSED_BIOMETRIC`- Customer is authenticated by KONEK \n`USER_SENSED_PASSCODE`- *DEPRECATED* Customer is authenticated using WebAuthN Passcode", "enum": [ "FI_AUTH", "PARTNER_FI_AUTH", "USER_SENSED_BIOMETRIC", "USER_SENSED_PASSCODE" ], "example": "FI_AUTH" }, "customerInfoForMerchant": { "description": "Customer information for merchant", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the user, available if merchant requested for it.", "nullable": true, "minLength": 1, "maxLength": 100 }, "email": { "nullable": true, "type": "string", "format": "email", "description": "Contains the customer's email address.\n\nFor standard email protocols, visit: https://www.rfc-editor.org/rfc/rfc5322\n", "minLength": 1, "maxLength": 320, "example": "moneris@moneris.com" }, "phoneNumber": { "nullable": true, "type": "string", "description": "Phone number.", "pattern": "^\\+[1-9]\\d{1,14}$", "minLength": 3, "maxLength": 16, "example": "+18663197450" }, "authMethod": { "$ref": "#/components/schemas/userAuthMethod" }, "userType": { "type": "string", "description": "Specifies the type of user within KONEK system, valid values are; `GUEST` - Customer chose to proceed as guest without creating profile. In this case, `auth_method` field must be `FI_AUTH` `REGISTERED` - Customer is a registered user within KONEK.", "enum": [ "GUEST", "REGISTERED" ], "example": "GUEST" }, "identityVerificationAge": { "description": "Age of the customer, present only if merchant requested for IDENTITY_VERIFICATION_AGE.", "type": "number", "nullable": true, "format": "float" }, "identityVerificationResidencePostalCode": { "description": "Residence postal code of the customer, present only if merchant requested for IDENTITY_VERIFICATION_RESIDENCE_POSTAL_CODE", "nullable": true, "type": "string" } }, "required": [ "authMethod", "userType" ] }, "modifiedAt": { "nullable": true, "description": "Time at which the object was modified", "type": "string", "format": "date-time", "example": "2019-07-30T06:43:40.252Z" }, "consentStatus": { "title": "consentStatus", "description": "Status of the consent within KONEK system", "type": "string", "enum": [ "REQUESTED", "DECLINED", "GRANTED", "STEPUP", "APPROVED", "DENIED", "TOKENIZED", "REVOKED" ], "example": "REQUESTED" }, "tokenState": { "description": "Token State", "enum": [ "REQUESTED", "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "example": "REQUESTED" }, "paymentConsent": { "description": "Payment-Consent data for merchant", "title": "paymentConsent", "allOf": [ { "type": "object", "properties": { "paymentConsentId": { "$ref": "#/components/schemas/paymentConsentId" }, "deviceProfileSessionId": { "$ref": "#/components/schemas/deviceProfileSessionId" } }, "required": [ "paymentConsentId", "deviceProfileSessionId" ] }, { "$ref": "#/components/schemas/consentCreate" }, { "type": "object", "properties": { "shippingAddress": { "$ref": "#/components/schemas/shippingAddress" }, "customerInfo": { "$ref": "#/components/schemas/customerInfoForMerchant" }, "createdAt": { "description": "UTC Date & time at which the consent was requested and created within KONEK system", "type": "string", "format": "date-time", "example": "2019-07-30T06:43:40.252Z" }, "modifiedAt": { "$ref": "#/components/schemas/modifiedAt" }, "consentStatus": { "$ref": "#/components/schemas/consentStatus" }, "tokenMetadata": { "nullable": true, "description": "Token metadata", "type": "object", "properties": { "tokenPrimaryAccountNumberLastDigits": { "nullable": true, "type": "string", "description": "Last 4 digits of token PAN", "maxLength": 4, "example": "3579" }, "accountLastDigits": { "type": "string", "description": "Last 4 digits of the card or account number", "nullable": true, "maxLength": 4, "example": "1234" }, "accountType": { "$ref": "#/components/schemas/accountType" }, "tokenState": { "$ref": "#/components/schemas/tokenState" } }, "required": [ "tokenState", "accountType" ] }, "cancellationReference": { "nullable": true, "type": "string", "description": "Uniquely identifying reference of consent cancellation request, available if status = REVOKED, assigned by either FI or Merchant", "maxLength": 36 }, "authOn": { "nullable": true, "description": "Date & time at which the consent was authorized", "type": "string", "format": "date-time", "example": "2019-07-30T06:43:40.252Z" }, "cancelledOn": { "nullable": true, "description": "Date & time at which the consent was cancelled by FI or Merchant", "type": "string", "format": "date-time", "example": "2019-07-30T06:43:40.252Z" }, "cancelledBy": { "nullable": true, "type": "string", "description": "Specifies the entity requested to delete the consent", "enum": [ "FI", "MERCHANT" ], "example": "FI" }, "merchantRequiredContactFields": { "type": "array", "description": "Specifies list of required contact fields of the customer", "items": { "$ref": "#/components/schemas/contactFields" }, "uniqueItems": true, "maxItems": 6 }, "merchantSupportedPaymentMethods": { "type": "array", "description": "Specifies the list of payment method account types the merchant supports for the transaction", "items": { "$ref": "#/components/schemas/accountType" }, "maxItems": 20, "example": [ "BANK_ACCOUNT", "VISA_CREDIT" ] } }, "required": [ "consentStatus", "createdAt", "modifiedAt", "customerInfo" ] } ] }, "parameterError": { "title": "Parameter error", "description": "Request property or header related error.", "type": "object", "properties": { "parameterName": { "type": "string", "description": "Property or header name. Can contain nested path separated by '.'", "example": "address.postalCode" }, "parameterValue": { "type": "string", "nullable": true, "description": "Property or header value string representation.", "example": "MAP3J8" }, "reasonCode": { "type": "string", "description": "Reason that triggered the error.", "enum": [ "INVALID_FORMAT", "REQUIRED_FIELD", "INVALID_VALUE" ], "example": "INVALID_FORMAT" }, "errorMessage": { "type": "string", "description": "Human readable description of the error.", "nullable": true, "example": "String 'MAP3J8' does not match the postal code pattern." } }, "required": [ "parameterName", "reasonCode" ] }, "error": { "description": "Error response details.", "properties": { "type": { "description": "A URI reference that identifies the problem type. Ideally it should be a stable URL to the documentation of the details about this type of error but it also can be a URN. If nothing can be provided, a \"about:blank\" value is returned.\n", "type": "string", "format": "uri", "example": "https://api-developer.moneris.com/responsehandling" }, "title": { "description": "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization\n", "type": "string", "example": "INSUFFICIENT_FUNDS", "nullable": true }, "status": { "description": "it conveys the HTTP status code used for the convenience of the consumer.\n", "type": "integer", "format": "int32", "minimum": 100, "maximum": 505, "nullable": true }, "detail": { "description": "A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.\n", "type": "string", "example": "Funds are insufficient to execute the operation.", "nullable": true }, "instance": { "description": "A URI reference that identifies the specific occurrence of the problem. Typically, this resolves to a resource that might include more details about the problem.\n", "type": "string", "example": "/payments/12f3e0a8-1d68-2b86-dd30-4ca51bb66e10", "format": "uri-reference", "nullable": true }, "category": { "description": "The type of error returned. \n - `API_ERROR`: This occurs due to an intermittent issue. \n - `IDEMPOTENCY_ERROR`: The idempotency key has already been used.\n - `INVALID_REQUEST_ERROR`: The data provided in the request is invalid.\n - `DECLINED_ERROR`: Transaction was declined by the issuer.\n - `UNAUTHORIZED_ERROR`: Caller not authenticated, or not allowed to execute the current operation.\n - `INTERNAL_SERVER_ERROR`: An internal issue with our servers has occured.\n", "enum": [ "API_ERROR", "IDEMPOTENCY_ERROR", "INVALID_REQUEST_ERROR", "DECLINED_ERROR", "UNAUTHORIZED_ERROR", "INTERNAL_SERVER_ERROR", null ], "type": "string", "nullable": true, "example": "DECLINED_ERROR" }, "errors": { "type": "array", "description": "List of validation errors when error category is INVALID_REQUEST_ERROR.", "items": { "type": "object", "$ref": "#/components/schemas/parameterError" }, "example": [ { "parameterName": "address.postalCode", "parameterValue": "MAP3J8", "errorMessage": "address.Postal code does not match regular expression", "reasonCode": "INVALID_FORMAT" } ] } }, "title": "API Error", "type": "object", "required": [ "type" ] } }, "parameters": { "apiVersion": { "in": "header", "name": "Api-Version", "required": true, "example": "2024-09-17", "description": "The endpoint's API Version. \n\nMust be provided through the headers section. \n", "schema": { "$ref": "#/components/schemas/apiVersion" } }, "correlationId": { "in": "header", "name": "X-Correlation-Id", "example": "06f1e47b-a1b5-4902-be9c-bccc506127c4", "description": "Correlates a series of requests within the same flow.\n\nNote: This ID is generated by Moneris with every request or response, if it doesn't exist. \nMerchants are to echo back the value with every request that is part of the call flow.\"\n", "required": false, "schema": { "type": "string", "example": "06f1e47b-a1b5-4902-be9c-bccc506127c4" } }, "merchantId": { "in": "header", "name": "X-Merchant-Id", "example": "0123456789101", "description": "Thirteen character identification code. \n\nNote: This code is provided by Moneris and is required to identify the Merchant executing the transaction.\n", "required": true, "schema": { "$ref": "#/components/schemas/merchantId" } } }, "examples": { "createConsentRequest": { "summary": "Create a KONEK payment consent", "description": "Create a KONEK payment consent using KONEK SDK", "value": { "idempotencyKey": "5d8f812e-9969-4885-85bb-d03948eccac1", "konekMerchantId": "CAM0000001", "orderDetails": { "merchantOrderReference": "1695401825L1CLwAJ98p7JwAc", "merchantCustomerReference": "CUST-001", "placementMode": "STANDARD", "shipmentType": "SINGLE", "items": [ { "itemName": "Wireless Mouse", "itemReference": "ITEM-001", "itemPaymentType": "RECURRING", "amount": { "amount": 1000, "currency": "CAD" }, "quantity": 1, "description": "Ergonomic wireless mouse", "recurringInformation": { "amountCapped": { "amount": 1000, "currency": "CAD" }, "amountVariance": 0.01, "dayOfMonth": 2, "dayOfWeek": "SUN", "endDate": "2021-04-04T04:04:04Z", "frequencyRate": 1, "frequencyType": "DAY", "maxNumberOfPayments": 99, "recurringtype": "SUBSCRIPTION", "startDate": "2021-04-04T04:04:04Z", "weekOfMonth": "FIRST" }, "itemType": "GIFT_CARD" } ] }, "paymentDetails": { "amount": { "amount": 600, "currency": "CAD" }, "subTotalAmount": { "amount": 100, "currency": "CAD" }, "shippingCost": { "amount": 100, "currency": "CAD" }, "totalTaxAmount": { "amount": 100, "currency": "CAD" }, "additionalFees": [ { "name": "Add 1", "amount": { "amount": 100, "currency": "CAD" } }, { "name": "Add 2", "amount": { "amount": 200, "currency": "CAD" } } ] }, "requiredContactFields": [ "NAME", "EMAIL" ], "supportedAccountTypes": [ "BANK_ACCOUNT_SAVINGS", "VISA_CREDIT" ] } }, "RequestConsentResponse": { "summary": "New Consent With Requested Status", "value": { "paymentConsentId": "3c62c0ba-945b-4d54-9da8-677067943afc", "deviceProfileSessionId": "5808...8385f", "konekMerchantId": "CAM0000001", "order": { "merchantOrderReference": "1695401825L1CLwAJ98p7JwAc", "merchantCustomerReference": "CUST-001", "placementMode": "STANDARD", "shipmentType": "SINGLE", "items": [ { "itemName": "Wireless Mouse", "itemReference": "ITEM-001", "itemPaymentType": "RECURRING", "amount": { "amount": 1000, "currency": "CAD" }, "quantity": 1, "description": "Ergonomic wireless mouse", "recurringInformation": { "amountCapped": { "amount": 1000, "currency": "CAD" }, "amountVariance": 0.01, "dayOfMonth": 2, "dayOfWeek": "SUN", "endDate": "2021-04-04T04:04:04Z", "frequencyRate": 1, "frequencyType": "DAY", "maxNumberOfPayments": 99, "recurringtype": "SUBSCRIPTION", "startDate": "2021-04-04T04:04:04Z", "weekOfMonth": "FIRST" }, "itemType": "GIFT_CARD" } ] }, "paymentDetails": { "amount": { "amount": 600, "currency": "CAD" }, "subTotalAmount": { "amount": 100, "currency": "CAD" }, "shippingCost": { "amount": 100, "currency": "CAD" }, "totalTaxAmount": { "amount": 100, "currency": "CAD" }, "additionalFees": [ { "name": "Add 1", "amount": { "amount": 100, "currency": "CAD" } }, { "name": "Add 2", "amount": { "amount": 200, "currency": "CAD" } } ] }, "shippingAddress": { "unitNumber": "24", "streetNumber": "200", "streetName": "Bay Street", "ruralPostalAddress": "PO BOX 4001 STN A", "city": "Toronto", "province": "ON", "postalCode": "A1AB0B", "country": "CA", "recipientName": "John Doe", "shippingAddressReference": "ship-001", "addressLine1": "123 Main St" }, "customerInfo": { "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "1-416-555-1212", "authMethod": "FI_AUTH", "userType": "REGISTERED", "identityVerificationAge": 35, "identityVerificationResidencePostalCode": "A1A1A1" }, "createdAt": "2025-11-05T10:00:00Z", "modifiedAt": "2025-11-05T10:05:00Z", "consentStatus": "REQUESTED", "tokenMetadata": { "tokenPrimaryAccountNumberLastDigits": "3579", "accountLastDigits": "1234", "accountType": "BANK_ACCOUNT_SAVINGS", "tokenState": "REQUESTED" }, "cancellationReference": null, "authOn": "2025-11-05T10:01:00Z", "cancelledOn": null, "cancelledBy": null, "merchantRequiredContactFields": [ "NAME", "EMAIL" ], "merchantSupportedAccountTypes": [ "BANK_ACCOUNT_SAVINGS", "VISA_CREDIT" ] } }, "IdempotencyRequestErrorResponse": { "value": { "type": "https://developer.moneris.com/en/More/Testing/Response%20Codes", "title": "IDEMPOTENCY_KEY_ALREADY_EXISTS", "status": 409, "detail": null, "instance": null, "category": "IDEMPOTENCY_ERROR", "errors": [] } }, "DeclineErrorResponse": { "value": { "type": "https://developer.moneris.com/en/More/Testing/Response%20Codes", "title": "EXCESS PIN TRIES", "status": 400, "detail": "052-38 - PIN retries exceeded", "instance": "/payments/20c3ee41-2560-4645-b84f-631fb08819de", "category": "DECLINED_ERROR", "errors": [] } } }, "headers": { "apiVersion": { "description": "The endpoint's API Version.", "example": "2026-08-14", "schema": { "type": "string" } }, "correlationId": { "example": "06f1e47b-a1b5-4902-be9c-bccc506127c4", "description": "Correlates a series of requests within the same flow. \n\nNote: This ID is generated by Moneris with every request or response, if it doesn't exist, and the Merchant is recommended to echo back the value.\" \n", "schema": { "type": "string", "example": "06f1e47b-a1b5-4902-be9c-bccc506127c4" } }, "sunset": { "example": "2025-07-30T06:43:40.252Z", "description": "Optional.\n\nIndicates that the resource URI will be decommissioned, and put out of service at the specified point in the future. \nMore details are available at [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)\n", "schema": { "type": "string", "format": "date-time", "example": "2025-07-30T06:43:40.252Z" } }, "rateLimitCount": { "description": "The maximum number of requests that the client can make in this window.", "schema": { "type": "integer", "format": "int64" }, "example": 1000 }, "rateLimitRemaining": { "description": "The number of requests allowed in the current window.", "schema": { "type": "integer", "format": "int64" }, "example": 0 }, "rateLimitReset": { "description": "The relative time in seconds when the rate limit window will be reset.", "schema": { "type": "integer", "format": "int32" }, "example": 3600 }, "retryAfter": { "description": "Indicates how long clients should wait before retrying.", "schema": { "type": "integer", "format": "int32" }, "example": 60 } }, "responses": { "createConsentSuccessResponse": { "description": "Payment consent created successfully.", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentConsent" }, "examples": { "requestedConsent": { "$ref": "#/components/examples/RequestConsentResponse" } } } } }, "badRequest": { "description": "Bad Request.", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "unauthorized": { "description": "Not authorized. The user does not have a valid API Key or Access Token.", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" }, "WWW-Authenticate": { "schema": { "type": "string", "example": "Bearer, error=\"invalid_token\"" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" }, "example": { "type": "https://developer.moneris.com/en/More/Testing/Response%20Codes", "title": "UNAUTHORIZED_REQUEST", "status": 401, "detail": null, "instance": null, "category": "UNAUTHORIZED_ERROR", "errors": [] } } } }, "forbidden": { "description": "Forbidden. The user does not have permission to access the requested resource.", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" }, "WWW-Authenticate": { "schema": { "type": "string", "example": "Bearer, error=\"insufficient_scope\"" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" }, "example": { "type": "https://developer.moneris.com/en/More/Testing/Response%20Codes", "title": "FORBIDDEN_REQUEST", "status": 403, "detail": null, "instance": null, "category": "UNAUTHORIZED_ERROR", "errors": [] } } } }, "conflict": { "description": "Request could not be completed due to a conflict with resource state or existing idempotency key.", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "idempotency_error": { "$ref": "#/components/examples/IdempotencyRequestErrorResponse" } } } } }, "createPaymentUnprocessableContentResponse": { "description": "Failed Payment operation result response", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "declined": { "$ref": "#/components/examples/DeclineErrorResponse" } } } } }, "tooManyRequests": { "description": "Too Many Requests", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/rateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/rateLimitReset" } } }, "internalServer": { "description": "Unexpected error.", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/rateLimitCount" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/rateLimitRemaining" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" }, "example": { "type": "https://api-developer.moneris.com/responsehandling/", "title": "INTERNAL_SERVER_ERROR", "status": 500, "detail": null, "instance": null, "category": "INTERNAL_SERVER_ERROR", "errors": [] } } } }, "serviceUnavailable": { "description": "Service Temporarily Unavailable", "headers": { "Api-Version": { "$ref": "#/components/headers/apiVersion" }, "X-Correlation-Id": { "$ref": "#/components/headers/correlationId" }, "Sunset": { "$ref": "#/components/headers/sunset" }, "Retry-After": { "$ref": "#/components/headers/retryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/error" }, "example": { "type": "https://api-developer.moneris.com/responsehandling/", "title": "SERVICE_UNAVAILABLE", "status": 503, "detail": null, "instance": null, "category": "INTERNAL_SERVER_ERROR", "errors": [] } } } } } } } ```