# Create transaction Start an authentication or information request # OpenAPI definition ```json { "openapi": "3.0.0", "security": [ { "userAgent": [] } ], "info": { "version": "1.0.6", "title": "iDIN api", "description": "[iDIN](https://idin.nl) is a service by the banks, that allows customers to identify themselves with websites, using the same secure methods as their own bank uses. It is similar to the iDEAL system in how it works and operates.\n\nIn addition to identification, it can also provide the connecting website with information about name, address and age of the consumer, if the consumer agrees to provide these.\n\nCM provides a simple API to integrate these options into your website. If you have not yet received a merchant token, you can request one via [this link](https://www.cm.com/app/idin-registration).\n\n### How does it work ?\n- The merchant asks the customer to select his bank\n- Start the request for authentication/information\n- The customer is redirected to this bank\n- The customer logs into his bank and approves the transaction\n- The bank sends the customer back to the merchants (your) landing page\n- The merchant rejoins the customer to his session and retrieves the transaction.\n- You check with the CM iDIN system if the transaction was successful and receive the requested customer information.\n\n### Usage\nThe iDIN system allows you to service several use cases\n* Checking if someone is known with a bank.\n * To see if the user is a legal entity known to a bank\n * To be able to trace the user in case of fraud.\n* Being guaranteed that this is always the same person. For instance\n * To log a user into your system\n * To avoid people registering multiple (fake) accounts in your system.\n* To check if a user is above a certain age limit\n* Retrieving name, address and age information of that person.\n * You should always allow the user to override or change this information,\n because it is not guaranteed that the information is always correct or complete\n (someone could have moved but not yet have informed his bank).\n * Match this against your own information and trigger audit signals\n\n### Things you should not do:\n* Matching an account in your system on the basis of name/address attributes.\n * Either create a new account after a user identified with iDIN\n * or have the user log into your system before coupling with an iDIN identity\n\n### Things you cannot do:\n* Check if an IBAN exists\n* Check if an IBAN belongs to an iDIN user\n" }, "tags": [ { "name": "Transaction" } ], "paths": { "/transaction": { "post": { "summary": "Create transaction", "description": "Start an authentication or information request\n", "tags": [ "Transaction" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" } } }, "description": "Start", "required": true }, "responses": { "200": { "description": "Successful transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "default": { "description": "Any non-compliant request will return an error object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "servers": [ { "url": "https://api.cm.com/idin/v1.0" } ], "components": { "securitySchemes": { "userAgent": { "in": "header", "name": "User-Agent", "type": "apiKey", "description": "Please add a recognizable user-agent to your requests, like MyImplementation/1.0.0" } }, "schemas": { "MerchantToken": { "type": "string", "format": "guid", "description": "a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 3c01abeb-b031-4fea-9f2d-c55c283cd78e", "example": "3c01abeb-b031-4fea-9f2d-c55c283cd78e" }, "TokenizedRequest": { "type": "object", "title": "TokenRequestParameters", "discriminator": { "propertyName": "baseRequest" }, "required": [ "merchant_token" ], "properties": { "merchant_token": { "$ref": "#/components/schemas/MerchantToken" } } }, "DirectoryRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TokenizedRequest" } ] }, "TransactionRequest": { "title": "Transaction request", "type": "object", "description": "Use one or more of identity, name, address, date_of_birth and 18y_or_older to request information\n", "allOf": [ { "$ref": "#/components/schemas/TokenizedRequest" }, { "type": "object", "properties": { "identity": { "type": "boolean", "description": "Retrieve an identifying token (bin) with the bank for this consumer that is consistent across multiple\nsessions. When false returns a transient_id that will differ per transaction.\n" }, "name": { "type": "boolean", "description": "Retrieve the name information associated with this consumer" }, "gender": { "type": "boolean", "description": "Retrieve the gender of this consumer" }, "address": { "type": "boolean", "description": "Retrieve address information associated with this consumer" }, "date_of_birth": { "type": "boolean", "description": "Retrieve the birthdate of the user" }, "18y_or_older": { "type": "boolean", "description": "Retrieve if this user is known to be 18 years or older." }, "email_address": { "type": "boolean", "description": "Retrieve the email address associated with this consumer." }, "telephone_number": { "type": "boolean", "description": "Retrieve the telephone number associated with this consumer." }, "issuer_id": { "$ref": "#/components/schemas/IssuerID" }, "entrance_code": { "type": "string", "description": "This is a token that will allow you to rejoin the user to his session when he returns. It can be a maximum of 40 characters and should only contain the characters a-z, A-z and 0-9. It should only be valid once and needs to be random enough (best use a cryptographically secure random generator), to avoid the possibility of replay attacks,.\n", "pattern": "[a-zA-Z0-9]+", "minLength": 1, "maxLength": 40 }, "merchant_return_url": { "type": "string", "description": "The place where the bank should redirect the user to at the end of the flow. The bank will append two query parameters to this url when returning the user to you, `trxid` and `ec`. The latter will contain the value of entrance_code, trxid is the `transaction_id` that you will receive in this request. When not specified, a default can you be used which you specified with CM.\n", "maxLength": 512 }, "language": { "type": "string", "description": "The 2 character language code in which to return the results. Can be either 'nl' or 'en' for Dutch or English. This is a preferred language, not all banks support all languages.\n", "minLength": 2, "maxLength": 2, "enum": [ "en|nl" ], "example": "nl" }, "transaction_reference": { "type": "string", "description": "A custom reference you can provide that we will add to the transaction, making it possible for you to distinguish transactions.\n", "maxLength": 255, "example": "7defa5c6-7651-45cd-9016-f9027dc4dda9" } }, "required": [ "issuer_id", "entrance_code", "merchant_return_url" ] } ] }, "TransactionResponse": { "title": "Transaction response", "type": "object", "properties": { "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "issuer_authentication_url": { "type": "string", "description": "The location with the issuing bank to which you should now forward the customer\n", "maxLength": 512, "example": "https://issuerserver/transaction" }, "merchant_reference": { "type": "string", "description": "A reference id for accounting purposes", "pattern": "[a-zA-Z0-9]+", "maxLength": 35 }, "transaction_reference": { "$ref": "#/components/schemas/TransactionReference" } }, "required": [ "transaction_id", "issuer_authentication_url", "merchant_reference" ] }, "StatusRequest": { "title": "StatusRequest", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TokenizedRequest" }, { "type": "object", "title": "StatusRequestParameters", "properties": { "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "merchant_reference": { "type": "string", "description": "The private reference of the transaction", "pattern": "[a-zA-Z0-9]+", "maxLength": 35 } }, "required": [ "merchant_token", "transaction_id", "merchant_reference" ] } ] }, "ErrorResponse": { "title": "Error Response", "description": "Whenever an error occurs, you are expected to show the message to the user\nand to give the user the option of trying again. Errors can happen for a variety of reasons,\nbut a common reason is because the issuer the user chose is temporarily not available.\n", "type": "object", "properties": { "status": { "type": "number", "format": "int32", "description": "Response status code, should match HTTP error code" }, "message": { "type": "string", "description": "High level description of the error that occured. This description, when present, can be shown to the end user. It might describe that a bank is not available or that the system is offline, or that an unexpected error occured. In test mode, the API will return more information (targeted at the developer) here then in production mode." }, "code": { "type": "number", "format": "int32", "description": "Low level and/or internal error code describing the error." } } }, "TransactionID": { "type": "string", "description": "A token for this transaction. You should store this with your session data, so that at any point, you can make a callback to the CM api and retrieve the status and/or results. Note that it is not guaranteed that your user will return to you via your merchant_return_url. A connection might be dropped, a user might accidently close a window, or he might trigger the back button and return that way. This id is the only way you can retrieve any information in that case.\n", "minLength": 16, "maxLength": 16, "pattern": "[0-9]+" }, "TransactionReference": { "type": "string", "description": "The optional custom reference you provided when creating the transaction. If not provided, will return null.\n", "maxLength": 255, "example": "7defa5c6-7651-45cd-9016-f9027dc4dda9" }, "IssuerID": { "type": "string", "description": "An identifier for the bank. Used as the value of the