{ "openapi": "3.1.1", "info": { "title": "Payments", "description": "The Payments API acts as a gateway to external payment service providers and provides endpoints to create, process and credit payment transactions. \nTo be able to provide these services, the following data is stored and made available:\n\n * Payments\n * PaymentTransactions\n * PaymentMethods\n * Credits\n * CreditTransactions\n * RecurringPayments\n * PaymentConfigurations.\n\nThis API is intended for partners who want to utilize Entur's platform to take payment for public transport tickets, as well as internal financial reporting tools.", "contact": { "name": "Entur", "url": "https://developer.entur.org" }, "version": "2026.06.1" }, "servers": [ { "url": "https://api.entur.io/sales", "description": "Entur's Production environment" }, { "url": "https://api.staging.entur.io/sales", "description": "Entur's Staging environment" }, { "url": "https://api.dev.entur.io/sales", "description": "Entur's Development environment" } ], "security": [ { "jwt": [] } ], "tags": [ { "name": "Payments", "description": "Create, update, deactivate and retrieve payments. Create, initiate, capture, cancel, and retrieve payment transactions" }, { "name": "Credits", "description": "Create and update credits. Create and execute credit transactions." }, { "name": "Recurring Payments", "description": "Set up and manage stored payment methods." }, { "name": "Configurations", "description": "Configurations directly configurable by partners. E.g. Webhooks." }, { "name": "API Documentation", "description": "OpenAPI specification endpoints." }, { "name": "Payment Agreements", "description": "Register and manage payment agreements for recurring billing." } ], "paths": { "/v1/credits": { "get": { "tags": [ "Credits" ], "summary": "Search credits", "description": "Returns matching credits with all its transactions. Query params are able to used expression like gt:1 for searching. Other expressions can contain eq, ne, gt, gte, lt, lte.", "operationId": "searchCredits", "parameters": [ { "name": "creditId", "in": "query", "description": "ID of Credit entity", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "customerNumber", "in": "query", "description": "Internal numeric ID of customer which Credit is linked to", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "orderId", "in": "query", "description": "ID of Order entity that Credit is linked to", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:ABCD1234" ] }, "not equals": { "value": [ "ne:ABCD1234" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "ABCD1234" ] } } }, { "name": "orderVersion", "in": "query", "description": "Version of Credit entity", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "less than": { "value": [ "lt:3" ] }, "not equals": { "value": [ "ne:1" ] }, "greater than": { "value": [ "gt:1" ] }, "less than or equals": { "value": [ "lte:3" ] }, "greater than or equal": { "value": [ "gte:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "organisationId", "in": "query", "description": "ID of organisation Credit entity is linked to", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "less than": { "value": [ "lt:3" ] }, "not equals": { "value": [ "ne:1" ] }, "greater than": { "value": [ "gt:1" ] }, "less than or equals": { "value": [ "lte:3" ] }, "greater than or equal": { "value": [ "gte:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "page", "in": "query", "description": "Selects a specific page in the collection", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "perPage", "in": "query", "description": "Selects the number of elements per page", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 30 } }, { "name": "reimbursementMethod", "in": "query", "description": "Which specific payment transfer type is used for the CreditTransactions linked to the Credit. E.g. VIPPS, VISA, MASTERCARD", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:VIPPS" ] }, "not equals": { "value": [ "ne:VIPPS" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "VIPPS" ] } } }, { "name": "reimbursementTypeGroup", "in": "query", "description": "Which of the several groups of ways to transfer payment the CreditTransactions linked to the Credit entity is. E.g. MOBILE, PAYMENTCARD, CASH", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:MOBILE" ] }, "not equals": { "value": [ "ne:MOBILE" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "MOBILE" ] } } }, { "name": "rrn", "in": "query", "description": "Retrieval Reference Number of CreditTransaction linked to Credit entity", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:00001234567890" ] }, "not equals": { "value": [ "ne:00001234567890" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "00001234567890" ] } } }, { "name": "settlementId", "in": "query", "required": false, "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1234" ] }, "not equals": { "value": [ "ne:1234" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1234" ] } } }, { "name": "status", "in": "query", "description": "Either CREATED or CREDITED depending on whether the actual credit action has been performed", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:CREDITED" ] }, "not equals": { "value": [ "ne:CREDITED" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "CREDITED" ] } } }, { "name": "totalCreditAmount", "in": "query", "description": "Total amount of credit, with one or more credit transactions", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:100" ] }, "less than": { "value": [ "lt:300" ] }, "not equals": { "value": [ "ne:100" ] }, "greater than": { "value": [ "gt:100" ] }, "less than or equals": { "value": [ "lte:300" ] }, "greater than or equal": { "value": [ "gte:100" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "100" ] } } }, { "name": "transactionId", "in": "query", "description": "Id of (one of) the PaymentTransaction(s) performed as part of the credit", "required": false, "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } } ], "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PageOfCredit" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "post": { "tags": [ "Credits" ], "summary": "Create credit transactions.", "description": "Creates credit transactions for all the payment transactions specified. The total credit amount must match the sum of the individual transactions, and each transaction cannot be higher than the paid amount.", "operationId": "createCredit", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-On-Behalf-Of", "in": "header", "description": "Identifier of the organisation on whose behalf the request is made. Use of this header requires a separate agreement before use.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditRequest" } } }, "required": true }, "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/CreditResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments": { "get": { "tags": [ "Payments" ], "summary": "Search for payments.", "description": "Returns matching payments with all its transactions. Query params are able to used expression like gt:1 for searching. Other expressions can contain eq, ne, gt, gte, lt, lte.", "operationId": "searchPayments", "parameters": [ { "name": "cardNumber", "in": "query", "description": "Last 4 digits in card number used in transaction for payment", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1234" ] }, "not equals": { "value": [ "ne:1234" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "100" ] } } }, { "name": "createdAt", "in": "query", "required": false, "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:2025-09-30T22:00:00.000Z" ] }, "less than": { "value": [ "lt:2025-09-30T22:00:00.000Z" ] }, "not equals": { "value": [ "ne:2025-09-30T22:00:00.000Z" ] }, "greater than": { "value": [ "gt:2025-09-30T22:00:00.000Z" ] }, "less than or equals": { "value": [ "lte:2025-09-30T22:00:00.000Z" ] }, "greater than or equal": { "value": [ "gte:2025-09-30T22:00:00.000Z" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "2025-09-30T22:00:00.000Z" ] } } }, { "name": "currency", "in": "query", "description": "Currencies", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:NOK" ] }, "not equals": { "value": [ "ne:NOK" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "NOK" ] } } }, { "name": "customerNumber", "in": "query", "description": "Numeric id of customer", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "externalTransactionId", "in": "query", "description": "Transaction ID from 3rd party payment provider", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:123" ] }, "not equals": { "value": [ "ne:123" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "123" ] } } }, { "name": "orderId", "in": "query", "description": "Order IDs", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:ABCD1234" ] }, "not equals": { "value": [ "ne:ABCD1234" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "ABCD1234" ] } } }, { "name": "orderVersion", "in": "query", "description": "Order version", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "less than": { "value": [ "lt:3" ] }, "not equals": { "value": [ "ne:1" ] }, "greater than": { "value": [ "gt:1" ] }, "less than or equals": { "value": [ "lte:3" ] }, "greater than or equal": { "value": [ "gte:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "organisationId", "in": "query", "description": "organisationId of the customer company", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "page", "in": "query", "description": "Selects a specific page in the collection", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "paymentId", "in": "query", "description": "Payment IDs", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "paymentTransactionId", "in": "query", "description": "Id of (one of) the PaymentTransaction(s) performed as part of the payment", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:1" ] }, "not equals": { "value": [ "ne:1" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "1" ] } } }, { "name": "paymentType", "in": "query", "description": "Type of payment transaction", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:VISA" ] }, "not equals": { "value": [ "ne:MASTERCARD" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "VISA" ] } } }, { "name": "paymentTypeGroup", "in": "query", "description": "The PaymentTypeGroup the payment type belongs to", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:PAYMENTCARD" ] }, "not equals": { "value": [ "ne:MOBILE" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "PAYMENTCARD" ] } } }, { "name": "perPage", "in": "query", "description": "Selects the number of elements per page", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 30 } }, { "name": "rrn", "in": "query", "description": "Reconciliation reference number used to track a transaction through different economy systems.", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:000012345678" ] }, "not equals": { "value": [ "ne:000012345678" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "000012345678" ] } } }, { "name": "settlementId", "in": "query", "required": false, "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:123" ] }, "not equals": { "value": [ "ne:123" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "123" ] } } }, { "name": "status", "in": "query", "description": "Status of transaction relating to payment", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:CAPTURED" ] }, "not equals": { "value": [ "ne:CAPTURED" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "CAPTURED" ] } } }, { "name": "totalAmount", "in": "query", "description": "Total amounts", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:100" ] }, "less than": { "value": [ "lt:300" ] }, "not equals": { "value": [ "ne:100" ] }, "greater than": { "value": [ "gt:100" ] }, "less than or equals": { "value": [ "lte:300" ] }, "greater than or equal": { "value": [ "gte:100" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "100" ] } } }, { "name": "updatedAt", "in": "query", "required": false, "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "equals": { "value": [ "eq:2025-09-30T22:00:00.000Z" ] }, "less than": { "value": [ "lt:2025-09-30T22:00:00.000Z" ] }, "not equals": { "value": [ "ne:2025-09-30T22:00:00.000Z" ] }, "greater than": { "value": [ "gt:2025-09-30T22:00:00.000Z" ] }, "less than or equals": { "value": [ "lte:2025-09-30T22:00:00.000Z" ] }, "greater than or equal": { "value": [ "gte:2025-09-30T22:00:00.000Z" ] }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": [ "2025-09-30T22:00:00.000Z" ] } } } ], "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PageOfPayment" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "post": { "tags": [ "Payments" ], "summary": "Create a new payment. ", "description": "Create a new payment. You may either create the payment without transactions and add them later, or include an initial transaction whose amount matches the payment total. Note that Entur can deactivate a payment method temporarily. If you include a transaction in this request, make sure its payment method is available by retrieving all current available methods first via GET /v1/payment-methods.", "operationId": "createPayment", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-On-Behalf-Of", "in": "header", "description": "Identifier of the organisation on whose behalf the request is made. Use of this header requires a separate agreement before use.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/webhooks": { "get": { "tags": [ "Configurations" ], "summary": "Get all webhook configurations", "description": "Partners can call this endpoint to get all the webhook configurations they have registered.", "operationId": "getWebhooks", "parameters": [ { "name": "page", "in": "query", "description": "Selects a specific page in the collection", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "perPage", "in": "query", "description": "Selects the number of elements per page", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 30 } } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOfWebhookConfiguration" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "post": { "tags": [ "Configurations" ], "summary": "Register one or more webhook events.", "description": "Partners can call this endpoint to register where they want to receive webhook events. They register a base url, and a list of events and what path the partner want to receive webhooks for that particular event.", "operationId": "registerWebhook", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigurationRequest" } } }, "required": true }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigurationResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/api-docs": { "get": { "tags": [ "API Documentation" ], "summary": "Api spec OAS3", "description": "Return the OpenApi Specification for the Payment API.", "operationId": "getOpenApiAsJson", "parameters": [ { "name": "group", "in": "query", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "Payments", "Credits", "Recurring Payments" ] }, "examples": { "default": { "value": "Payments" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payment-methods": { "get": { "tags": [ "Payments" ], "summary": "Find all Payment Methods.", "description": "Find all Payment Methods for a specific clientId. This method uses the Entur-Distribution-Channel header as a filter to show only those payment methods with the distributionChannelId matching this header.", "operationId": "findAllPaymentMethods", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentType", "in": "query", "description": "Filter by PaymentType", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "$ref": "#/components/schemas/PaymentType" }, "examples": { "default": { "value": "VISA" } } }, { "name": "paymentTypeGroup", "in": "query", "description": "Filter by PaymentTypeGroup", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "$ref": "#/components/schemas/PaymentTypeGroup" }, "examples": { "default": { "value": "PAYMENTCARD" } } } ], "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodResponse" } } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/api-docs-internal": { "get": { "tags": [ "API Documentation" ], "summary": "Api spec OAS3", "description": "Return the OpenApi Specification for the Payment Internal API.", "operationId": "getInternalOpenApiAsJson", "parameters": [ { "name": "group", "in": "query", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "Payment Mending", "Cache", "Payment Configuration", "Kafka" ] }, "examples": { "default": { "value": "Payment Mending" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/credits/{creditId}": { "get": { "tags": [ "Credits" ], "summary": "Find a credit.", "description": "Returns the credit with all its credit transactions. The credit transactions have each backreferences to their corresponding payment transaction.", "operationId": "findCredit", "parameters": [ { "name": "creditId", "in": "path", "description": "creditId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/CreditResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "patch": { "tags": [ "Credits" ], "summary": "Update the credit", "description": "The credit will be patched with specified fields. NULL values specifically set is considered as removing the field. In other words, only included fields will be modified. For more information about the PATCH endpoint and the merge-patch content-type, please refer to RFC7396.", "operationId": "mergePatchCredit", "parameters": [ { "name": "creditId", "in": "path", "description": "creditId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditMergePatch" } }, "application/merge-patch+json;charset=UTF-8": { "schema": { "$ref": "#/components/schemas/CreditMergePatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/CreditResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payment-agreements": { "get": { "tags": [ "Payment Agreements" ], "summary": "Query payment agreements", "description": "Returns payment agreements for a given customer across all organisations the caller has access to. Optionally filter by one or more statuses.", "operationId": "queryPaymentAgreements", "parameters": [ { "name": "customerNumber", "in": "query", "description": "Customer number to query agreements for. Required.", "required": true, "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Optional. Filter by one or more agreement statuses.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CREATED", "PENDING", "ACTIVE", "STOPPED", "EXPIRED" ] } } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAgreementResponse" } }, "examples": { "no-agreements": { "summary": "Kunde uten avtaler (tom liste)", "value": [] }, "single-active-agreement": { "summary": "Kunde med én aktiv Vipps-avtale", "value": [ { "status": "ACTIVE", "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "FIXED" }, "agreementId": 42, "productName": "Månedlig reisekort Oslo", "providerData": { "agreementProvider": "VIPPS" } } ] }, "multiple-agreements-mixed-status": { "summary": "Kunde med flere avtaler i ulike statuser", "value": [ { "status": "ACTIVE", "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "FIXED" }, "agreementId": 42, "productName": "Månedlig reisekort Oslo", "providerData": { "agreementProvider": "VIPPS" } }, { "status": "PENDING", "pricing": { "currency": "NOK", "agreementType": "FLEXIBLE" }, "agreementId": 51, "productName": "Fleksibelt reisekort", "providerData": { "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", "agreementProvider": "VIPPS" } } ] } } } } }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "post": { "tags": [ "Payment Agreements" ], "summary": "Register a new payment agreement", "description": "Registers a payment agreement with the specified provider. For Vipps, this drafts the agreement and returns a confirmation URL to redirect the customer to.", "operationId": "createPaymentAgreement", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentAgreementRequest" }, "examples": { "vipps-fixed-pricing": { "summary": "Vipps-avtale med fast pris", "value": { "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "FIXED" }, "productName": "Månedlig reisekort Oslo", "providerData": { "phoneNumber": "4791234567", "agreementProvider": "VIPPS", "merchantRedirectUrl": "https://entur.no/avtaler/bekreftelse", "merchantAgreementUrl": "https://entur.no/avtaler/123" }, "customerNumber": "12345678" } }, "vipps-flexible-pricing": { "summary": "Vipps-avtale med fleksibel pris", "value": { "pricing": { "currency": "NOK", "agreementType": "FLEXIBLE" }, "productName": "Reisekortkonto", "providerData": { "agreementProvider": "VIPPS", "merchantRedirectUrl": "https://entur.no/avtaler/bekreftelse", "merchantAgreementUrl": "https://entur.no/avtaler/123" }, "customerNumber": "12345678" } }, "vipps-variable-pricing": { "summary": "Vipps-avtale med variabel pris", "value": { "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "VARIABLE", "suggestedMaxAmount": 100000 }, "productName": "Fleksibelt reisekort", "providerData": { "agreementProvider": "VIPPS", "merchantRedirectUrl": "https://entur.no/avtaler/bekreftelse", "merchantAgreementUrl": "https://entur.no/avtaler/123" }, "customerNumber": "12345678" } } } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentAgreementResponse" }, "examples": { "vipps-fixed-pricing": { "summary": "Vipps-avtale opprettet med fast pris", "value": { "status": "PENDING", "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "FIXED" }, "agreementId": 42, "productName": "Månedlig reisekort Oslo", "providerData": { "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", "agreementProvider": "VIPPS" } } }, "vipps-flexible-pricing": { "summary": "Vipps-avtale opprettet med fleksibel pris", "value": { "status": "PENDING", "pricing": { "currency": "NOK", "agreementType": "FLEXIBLE" }, "agreementId": 44, "productName": "Reisekortkonto", "providerData": { "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", "agreementProvider": "VIPPS" } } }, "vipps-variable-pricing": { "summary": "Vipps-avtale opprettet med variabel pris", "value": { "status": "PENDING", "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "VARIABLE", "suggestedMaxAmount": 100000 }, "agreementId": 43, "productName": "Fleksibelt reisekort", "providerData": { "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", "agreementProvider": "VIPPS" } } } } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/recurring-payments": { "get": { "tags": [ "Recurring Payments" ], "summary": "Get recurring payments.", "description": "Get recurring payments, which are not CANCELLED, for a customer. By default, EXPIRED are not included.", "operationId": "queryRecurringPayments", "parameters": [ { "name": "customerNumber", "in": "query", "description": "Query for a given customer number", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "string" }, "examples": { "equals": { "value": "eq:1" }, "not equals": { "value": "ne:1" }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": "1" } } }, { "name": "includeExpired", "in": "query", "description": "Whether or not to include expired recurring payments. Default false.", "required": false, "style": "form", "explode": true, "allowReserved": true, "schema": { "type": "boolean" }, "examples": { "equals": { "value": true }, "not equals": { "value": false }, "equals without operator": { "summary": "When operation is omitted it is treated as equals.", "value": true } } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringPaymentResponse" } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "post": { "tags": [ "Recurring Payments" ], "summary": "Create a recurring payment.", "description": "Creates a new recurring payment with status CREATED and couples it to the customer number sent in the request. If this is the first recurring payment coupled to the customer number it is made to be the primary recurring payment for the customer number. If it is not the first recurring payment, it defaults to not primary. However, if the requests makes it primary, the customers other recurring payment with primary status is set to not primary.", "operationId": "createRecurringPayment", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-On-Behalf-Of", "in": "header", "description": "Identifier of the organisation on whose behalf the request is made. Use of this header requires a separate agreement before use.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}": { "get": { "tags": [ "Payments" ], "summary": "Get a payment.", "description": "Returns the payment with all its transactions.", "operationId": "findPayment", "parameters": [ { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "patch": { "tags": [ "Payments" ], "summary": "Update a payment.", "description": "The payment will be patched with specified fields. NULL values specifically set is considered as removing the field. In other words, only included fields will be modified. As of now, the only editable field is 'totalAmount' and 'active' (only for activation, not deactivation). For more information about the PATCH endpoint and the merge-patch content-type, please refer to RFC7396.", "operationId": "mergePatchPayment", "parameters": [ { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMergePatch" } }, "application/merge-patch+json;charset=UTF-8": { "schema": { "$ref": "#/components/schemas/PaymentMergePatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "409": { "$ref": "#/components/responses/conflictValidationError" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/credits/{creditId}/execute": { "post": { "tags": [ "Credits" ], "summary": "Execute credit.", "description": "Executes a credit operation on all the payment transactions referenced in this credit. The operation will execute sequentially for all payment transactions. If one of the operations fails, this call responds with the specific error response for that payment transaction. Any previous successful credit operation cannot be undone, and for this reason it is highly recommended to check the status of each credit transaction after en error response is returned. More detail on the individual payment transaction can be found in the transaction summary by calling GET on the specific payment transaction. This call is idempotent, which means it is safe to repeatedly retry without any creditTransactions being executed more than once.", "operationId": "executeCredit", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "creditId", "in": "path", "description": "creditId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/CreditResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/deactivate": { "post": { "tags": [ "Payments" ], "summary": "Deactivate a payment", "description": "The payment will be deactivated. Any previously captured transactions will be credited (as long as it is not an imported transaction), and all other transactions will be cancelled.", "operationId": "deactivatePayment", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "409": { "$ref": "#/components/responses/conflict" }, "500": { "$ref": "#/components/responses/internalServerError" }, "501": { "$ref": "#/components/responses/notImplemented" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payment-agreements/{agreementId}": { "get": { "tags": [ "Payment Agreements" ], "summary": "Get payment agreement status", "description": "Returns the current status and details of a payment agreement. The Vipps confirmation URL is only included while the agreement is pending customer confirmation (CREATED or PENDING status).", "operationId": "getPaymentAgreement", "parameters": [ { "name": "agreementId", "in": "path", "description": "agreementId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentAgreementResponse" }, "examples": { "vipps-active": { "summary": "Vipps-avtale som er aktiv (uten signeringslenke)", "value": { "status": "ACTIVE", "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "FIXED" }, "agreementId": 42, "productName": "Månedlig reisekort Oslo", "providerData": { "agreementProvider": "VIPPS" } } }, "vipps-pending": { "summary": "Vipps-avtale som venter på kundebekreftelse", "value": { "status": "PENDING", "pricing": { "amount": 49900, "currency": "NOK", "interval": { "unit": "MONTH", "count": 1 }, "agreementType": "FIXED" }, "agreementId": 42, "productName": "Månedlig reisekort Oslo", "providerData": { "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", "agreementProvider": "VIPPS" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions": { "post": { "tags": [ "Payments" ], "summary": "Create a new transaction and add to payment.", "description": "Add a transaction to an existing payment. Provide either a payment method or a recurring payment ID (at least one must be present). A payment can have more than one transaction. This operation can be seen in the operation log of the transaction as CREATE. Note that Entur can deactivate a payment method temporarily, retrieve all available payment methods first via GET /v1/payment-methods.", "operationId": "addTransaction", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-On-Behalf-Of", "in": "header", "description": "Identifier of the organisation on whose behalf the request is made. Use of this header requires a separate agreement before use.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/webhooks/{webhookConfigurationId}": { "get": { "tags": [ "Configurations" ], "summary": "Get webhook by ID", "description": "Get a webhook by the ID of the webhook.", "operationId": "getWebhook", "parameters": [ { "name": "webhookConfigurationId", "in": "path", "description": "The id of a webhook", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Webhook found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigurationResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "put": { "tags": [ "Configurations" ], "summary": "Update a webhook", "description": "Partners can update a webhook configuration by using this endpoint. All the same values the partner input when creating a webhook can be changed using this endpoint", "operationId": "updateWebhook", "parameters": [ { "name": "webhookConfigurationId", "in": "path", "description": "The id of a webhook", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigurationRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigurationResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "delete": { "tags": [ "Configurations" ], "summary": "Delete a webhook", "description": "Delete a specific webhook configuration by id.", "operationId": "deleteWebhook", "parameters": [ { "name": "webhookConfigurationId", "in": "path", "description": "The id of a webhook", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Webhook deleted" }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/recurring-payments/{recurringPaymentId}": { "delete": { "tags": [ "Recurring Payments" ], "summary": "End recurring payment.", "description": "Ends a recurring payment, the recurring payment is no longer usable after this call.", "operationId": "endRecurringPayment", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "recurringPaymentId", "in": "path", "description": "recurringPaymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "patch": { "tags": [ "Recurring Payments" ], "summary": "Update recurring payment.", "description": "Updates a recurring payment's nickname and/or isPrimary status. If the recurring payment is set to be the primary recurring payment, the last primary recurring payment is no longer the primary recurring payment.", "operationId": "updateRecurringPayment", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "recurringPaymentId", "in": "path", "description": "recurringPaymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/webhooks/{webhookConfigurationId}/rotate-secret": { "post": { "tags": [ "Configurations" ], "summary": "Rotate the webhook secret", "description": "If the current secret has been compromised, this endpoint offers a simple way to rotate the secret.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "webhookConfigurationId", "in": "path", "description": "The id of a webhook", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Secret rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigurationResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/recurring-payments/{recurringPaymentId}/terminal": { "post": { "tags": [ "Recurring Payments" ], "summary": "Create terminal.", "description": "Registers the transaction with Nets and returns the location of the payment terminal where the user will provide card information. The terminal is available for 15min before the transaction times out. If this happens a new terminal must be created.", "operationId": "createRecurringPaymentTerminal", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "recurringPaymentId", "in": "path", "description": "recurringPaymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TerminalResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}": { "get": { "tags": [ "Payments" ], "summary": "Get a single transaction.", "description": "Returns the transaction including an operation log showing everything that happened to the transaction.", "operationId": "findTransaction", "parameters": [ { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/recurring-payments/{recurringPaymentId}/authorize": { "put": { "tags": [ "Recurring Payments" ], "summary": "Authorize a recurring payment.", "description": "Authorize the card details provided by the customers in the terminal were valid and accepted by Nets and by calling Nets with a process call. If valid, the recurring payment has its status set to ACTIVE and the returned pan hash is stored. This pan hash is later used when paying with a recurring payment.", "operationId": "authorizeRecurringPayment", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "recurringPaymentId", "in": "path", "description": "recurringPaymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/cancel": { "post": { "tags": [ "Payments" ], "summary": "Cancel a transaction which is already CREATED/INITIATED.", "description": "To be able to continue using the same payment (for the same order and order version), but with a new transaction, cancel needs to be called to not have it be included when summing up the total amount. There are several cases where this can be necessary, i.e. customer wants to use another payment method, or something goes wrong with the transaction before it is CAPTURED. This also takes care of cleaning up with the 3rd party payment provider if necessary.", "operationId": "cancelTransaction", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "409": { "$ref": "#/components/responses/conflict" }, "500": { "$ref": "#/components/responses/internalServerError" }, "501": { "$ref": "#/components/responses/notImplemented" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/import": { "post": { "tags": [ "Payments" ], "summary": "Import transaction data from external client.", "description": "This endpoint is to be used to fill an existing PaymentTransaction with predetermined data from a completed PaymentTransaction. This should only be used by certain privileged clients.", "operationId": "importTransaction", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionImportRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/wallet": { "post": { "tags": [ "Payments" ], "summary": "Register wallet-transaction in order to send payments to Netaxept by use of virtual wallets like ApplePay", "description": "Register with data regarding payment and wallet provider in order to make payments with e.g. ApplePay. Clients must ask Entur to activate agreements for your merchant before using this endpoint.", "operationId": "registerWalletTransaction", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterWalletTransactionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterWalletTransactionResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/capture": { "put": { "tags": [ "Payments" ], "summary": "Capture the transaction.", "description": "Updates the state of the transaction to CAPTURED, and returns the state of the whole payment. After this operation, the transaction is considered to be paid, and a credit is needed to revert it. This operation can be seen in the operation log of the transaction as CAPTURE.", "operationId": "captureTransaction", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "404": { "$ref": "#/components/responses/notFound" }, "409": { "description": "Conflict", "content": { "application/xml": { "schema": { "type": "object", "properties": {} } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaymentError" }, "examples": { "example-1": { "value": { "path": "string", "error": "string", "status": 0, "message": "string", "exception": "string", "timestamp": "2019-08-24T14:15:22Z" } }, "soft_decline": { "value": { "path": "string", "error": "string", "status": 0, "message": "string", "exception": "string", "timestamp": "2019-08-24T14:15:22Z", "errorReason": "SOFT_DECLINE" } } } } } }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/invoice": { "put": { "tags": [ "Payments" ], "summary": "Change the content of an Invoice", "description": "Change the contents and/or amount of an invoice. Only valid for COLLECTOR_B2B, and only before invoice has been confirmed by customer.", "operationId": "changeInvoice", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "post": { "tags": [ "Payments" ], "summary": "Create or replace an invoice for an order", "description": "Initiate a payment by creating or replacing an invoice based on orderId and PaymentType.", "operationId": "createOrReplaceInvoice", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/terminal": { "post": { "tags": [ "Payments" ], "summary": "Create payment terminal.", "description": "Registers the transaction with a 3rd party PSP and returns the location of the payment terminal where the user will provide card information. The terminal is available for 15min before the transaction times out. After this, a new transaction must be created. This operation can be seen in the operation log of the transaction as INITIATE.", "operationId": "createPaymentTerminal", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TerminalResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/app-claim": { "post": { "tags": [ "Payments" ], "summary": "Create payment claim in mobile app.", "description": "Register the transaction with Vipps, which will present payment information to the customer in the Vipps app. Note that the receipt of confirmation in the payment app will not serve as payment confirmation, as this action will only reserve the money on the customer's bank account. When the payment is accepted by the customer, a callback will be sent to the location provided in the request. This operation can be seen in the operation log of the transaction as INITIATE.\n\nThe response depends on how the transaction was created:\n- **Standard Vipps payment** (no agreement): returns **201** with an `appClaimUrl` the client uses to open the Vipps app and present the payment to the customer.\n- **New agreement** (`createAgreement=true`): returns **201** with a confirmation URL the customer must visit to approve the new agreement.\n- **Existing agreement** (`paymentAgreementId` set): returns **204 No Content**. The charge is initiated directly against the existing agreement; no redirect or customer interaction is required. Clients implementing `paymentAgreementId` support must handle both 201 and 204 responses.", "operationId": "createAppClaim", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppClaimRequest" } } }, "required": true }, "responses": { "201": { "description": "Created. Returned for standard Vipps payments and new agreements (`createAgreement=true`). Contains an `appClaimUrl` used to direct the customer to Vipps.", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/AppClaimResponse" } } } }, "204": { "description": "No Content. Returned when the transaction was created with `paymentAgreementId` (existing agreement). The charge has been initiated in Vipps; no redirect URL is needed." }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/authorize": { "put": { "tags": [ "Payments" ], "summary": "Pre-authorization and authorization adjustments of a transaction", "description": "Authorize a transaction pre-capture. The initial authorization, also called a pre-authorization is to reserve the total you think the transaction will amount to. If the total changes between the initial authorization and the time of capture, initial authorization-calls can be made to either increment or reduce the authorized amount. To trigger this just change the totalAmount in the authorizeRequest accordingly to your needs.\n\nNote: An incremental authorization must be directly preceeded by either a pre-authorization or another incremental authorization.\nNote: A reductional authorization can only be performed once per transaction. Once a reductional authorization has been done, it is no longe possible to alter the totalAmount of the transaction.", "operationId": "authorizeTransaction", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/AuthorizeResponse" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/gift-card-claim": { "post": { "tags": [ "Payments" ], "summary": "Claim a gift-card", "description": "The gift-card will be claimed", "operationId": "captureWithGiftCard", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GiftCardRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/internal-terminal": { "post": { "tags": [ "Payments" ], "summary": "Create an internal payment terminal.", "description": "Returns a terminal-url where the user can provide further information and complete the payment process.", "operationId": "createInternalPaymentTerminal", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTerminalRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/InternalTerminalResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/payments/{paymentId}/transactions/{transactionId}/pan-hash-terminal": { "post": { "tags": [ "Payments" ], "summary": "Create payment terminal.", "description": "Registers the transaction with a 3rd party PSP and returns the location of the payment terminal. This operation can be seen in the operation log of the transaction as INITIATE.", "operationId": "createTerminalWithPanHash", "parameters": [ { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanHashTerminalRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TerminalResponse" } } } }, "400": { "$ref": "#/components/responses/badRequestValidationError" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" }, "503": { "$ref": "#/components/responses/serviceUnavailableError" } } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] } }, "components": { "schemas": { "Operation": { "type": "string", "description": "A transaction has a list of operations performed on a transaction. These operations can have one of the values in this enum.", "enum": [ "AUTHENTICATE", "CANCEL", "CAPTURE", "CREATE", "CREDIT", "IMPORT", "INITIATE", "REJECT", "SOFT_DECLINE", "ON_HOLD", "AUTHORIZE", "AUTHORIZE_INCREMENT", "AUTHORIZE_REVERSE" ], "examples": [ "CREATE" ] }, "PaymentType": { "type": "string", "description": "The actual type of payment.", "enum": [ "AMEX", "BANKAXEPT", "COLLECTOR", "GIFTCARD", "MASTERCARD", "PAYPAL", "VIPPS", "VISA", "XLEDGER", "COLLECTOR_B2B", "INTERNAL", "TWO_B2B" ], "examples": [ "VISA" ] }, "FixedPricing": { "description": "Fixed pricing charges a set amount each interval.", "allOf": [ { "$ref": "#/components/schemas/AgreementPricing" }, { "required": [ "amount", "currency", "interval" ], "type": "object", "properties": { "amount": { "type": "integer", "description": "The fixed amount to charge per interval, in minor units, e.g: øre." }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "ISO 4217 currency code." }, "interval": { "$ref": "#/components/schemas/AgreementInterval" } } } ] }, "PageOfCredit": { "title": "PageOfCredit", "required": [ "items", "totalItems", "totalPages" ], "type": "object", "properties": { "items": { "type": "array", "description": "Items on a specific page", "readOnly": true, "items": { "$ref": "#/components/schemas/CreditResponse" }, "examples": [ [ { "active": true, "orderId": "ABCD1234", "creditId": 1, "currency": "NOK", "orderVersion": 1, "settlementId": 1245, "customerNumber": "123456789", "organisationId": 1, "totalCreditAmount": "450.00", "creditTransactions": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "creditedAt": "2025-01-12T16:13:13Z", "newGiftCardId": "0068a450-066f-442d-8117-1543fe2b1e0e", "transactionData": { "extraData": "any extra data you want to add" }, "reimbursementMethod": "VISA", "paymentTransactionId": 10, "reimbursementTypeGroup": "PAYMENTCARD" } ] } ] ] }, "totalItems": { "type": "integer", "description": "Total number of items", "format": "int64", "readOnly": true, "examples": [ 72 ] }, "totalPages": { "type": "integer", "description": "Total number of pages available to browse", "format": "int64", "readOnly": true, "examples": [ 9 ] } }, "description": "Page displays a subset of a list of entities", "examples": [ { "items": [ { "active": true, "orderId": "ABCD1234", "creditId": 1, "currency": "NOK", "orderVersion": 1, "settlementId": 1245, "customerNumber": "123456789", "organisationId": 1, "totalCreditAmount": "450.00", "creditTransactions": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "creditedAt": "2025-01-12T16:13:13Z", "newGiftCardId": "0068a450-066f-442d-8117-1543fe2b1e0e", "transactionData": { "extraData": "any extra data you want to add" }, "reimbursementMethod": "VISA", "paymentTransactionId": 10, "reimbursementTypeGroup": "PAYMENTCARD" } ] } ], "totalItems": 1, "totalPages": 1 } ] }, "PaymentError": { "title": "PaymentError", "required": [ "error", "exception", "message", "path", "status", "timestamp" ], "type": "object", "properties": { "path": { "type": "string", "description": "The url path that was accessed when the error happenened.", "examples": [ "/v1/payments/1/transactions/1/capture" ] }, "error": { "type": "string", "description": "The error that occurred.", "examples": [ "Internal Server Error" ] }, "status": { "type": "integer", "description": "The http status of the response.", "format": "int32", "examples": [ 500 ] }, "message": { "type": "string", "description": "A message detailing the error.", "examples": [ "An internal error occurred in the PSP. message='Unable to sale', errorCode='91', errorSource='Issuer', errorText='Refused by issuer'" ] }, "exception": { "type": "string", "description": "What exception caused the error.", "examples": [ "org.entur.payment.faulthandling.exceptions.psp.InternalPSPFailureException" ] }, "timestamp": { "type": "string", "description": "When the error occurred", "format": "date-time", "examples": [ "2025-01-12T16:13:13Z" ] }, "errorReason": { "type": "string", "description": "In some cases, the client is required to act upon getting a PaymentError. When action is required from the client, this field will be populated. Valid values: SOFT_DECLINE, REFUSED_BY_ISSUER, RESOURCE_BUSY.", "examples": [ "SOFT_DECLINE" ] } }, "x-examples": {}, "examples": [ { "path": "/v1/payments/1/transactions/1/capture", "error": "Internal Server Error", "status": 500, "message": "An internal error occurred in the PSP. message='Unable to sale', errorCode='91', errorSource='Issuer', errorText='Refused by issuer'", "exception": "org.entur.payment.faulthandling.exceptions.psp.InternalPSPFailureException", "timestamp": "2025-08-24T14:15:22Z" } ] }, "ScaExemption": { "title": "ScaExemption", "type": "string", "description": "The type of SCA (secure customer authentication) Exemption for a transaction. Defaults to NO_EXEMPTION. Other available values are: LOW_VALUE.", "examples": [ "NO_EXEMPTION" ] }, "CreditRequest": { "title": "CreditRequest", "required": [ "creditTransactions", "orderId", "orderVersion", "totalCreditAmount" ], "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order this credit belongs to.", "examples": [ "HE8NDS7XY" ] }, "currency": { "pattern": "[A-Z]{3}", "type": "string", "description": "The currency used for this credit. Default value is 'NOK'", "default": "NOK", "examples": [ "NOK" ] }, "orderVersion": { "type": "integer", "description": "Version of the order this credit belongs to.", "format": "int32", "examples": [ 1 ] }, "settlementId": { "type": "integer", "description": "Supplied to the client by an external system for handling settlements. For Internal Entur Clients this is Entur’s Electronic Journal.", "format": "int64", "examples": [ 1873 ] }, "customerNumber": { "type": "string", "description": "Customer who owns this credit. This value is only considered for privileged client (internal and partner tenants.", "examples": [ "123456789" ] }, "totalCreditAmount": { "maxLength": 19, "pattern": "^[1-9][0-9]{0,17}\\.[0-9]{1,5}$|^([1-9])[0-9]{0,17}$|^[0]\\.[1-9][0-9]{1,5}$", "type": "string", "description": "Amount to credit, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] }, "creditTransactions": { "type": "array", "description": "List of individual transactions to credit.", "items": { "$ref": "#/components/schemas/CreditTransactionRequest" } } }, "description": "Information used to create a Credit.", "examples": [ { "orderId": "ABCD1234", "currency": "NOK", "orderVersion": 1, "settlementId": 1723, "customerNumber": "123456789", "totalCreditAmount": "450.00", "creditTransactions": [ { "amount": "450.00", "currency": "NOK", "paymentTransactionId": 1, "reimbursementTypeGroup": "PAYMENTCARD" } ] } ] }, "ErrorResponse": { "title": "Error", "type": "object", "properties": { "code": { "type": "string", "description": "The error code. Used in combination with the error source to find more information about the error.", "examples": [ "25" ] }, "source": { "type": "string", "description": "Where the error originates from.", "examples": [ "Netaxept" ] }, "message": { "type": "string", "description": "A description of the error that occurred.", "examples": [ "Transaction not found." ] } }, "description": "Information about an error that occurred.", "examples": [ { "code": "25", "source": "Netaxept", "message": "Transaction not found." } ] }, "PageOfPayment": { "title": "PageOfPayment", "required": [ "items", "totalItems", "totalPages" ], "type": "object", "properties": { "items": { "type": "array", "description": "Items on a specific page", "readOnly": true, "items": { "$ref": "#/components/schemas/PaymentResponse" } }, "totalItems": { "type": "integer", "description": "Total number of items", "format": "int64", "readOnly": true, "examples": [ 72 ] }, "totalPages": { "type": "integer", "description": "Total number of pages available to browse", "format": "int64", "readOnly": true, "examples": [ 9 ] } }, "description": "Page displays a subset of a list of entities", "examples": [ { "items": [ { "active": true, "orderId": "ABCD1234", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "totalAmount": "450.00", "orderVersion": 1, "settlementId": 1245, "customerNumber": "123456789", "organisationId": 1, "transactionHistory": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "summary": { "capturedAmount": "450.00", "creditedAmount": "450.00", "remainingAmountToCredit": "0.00", "remainingAmountToCapture": "0.00" }, "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "updatedAt": "2025-01-12T16:13:13Z", "cardNumber": "0004", "paymentType": "VISA", "operationLog": [ { "pos": "18930345", "error": { "code": "25", "source": "Netaxept", "message": "Transaction not found." }, "amount": "450.00", "operation": "CREATE", "timestamp": "2025-08-24T14:15:22Z", "distributionChannelId": "ENT:DistributionChannel:Test" } ], "transactionId": 10, "paymentTypeFee": { "name": "ENT:PaymentTypeFee:Collector", "amount": "450.00", "reason": "Walley Invoice", "taxCode": "3", "taxRate": "25.00", "currency": "NOK", "taxAmount": "25.00" }, "transactionData": { "extraData": "any extra data you want to add" }, "paymentTypeGroup": "PAYMENTCARD", "recurringPaymentId": 1 } ] } ], "totalItems": 1, "totalPages": 1 } ] }, "CreditResponse": { "title": "Credit", "required": [ "creditId", "creditTransactions", "orderId", "orderVersion", "totalCreditAmount" ], "type": "object", "properties": { "active": { "type": "boolean", "description": "If active is false, credit is considered uneditable. The only way to change this property is through an internal Admin endpoint or the mergePatch endpoint. Editable: true", "examples": [ false ] }, "orderId": { "type": "string", "description": "ID of the order this payment belongs to.", "examples": [ "HE8NDS7XY" ] }, "creditId": { "type": "integer", "description": "Identification of this credit resource.", "format": "int64", "examples": [ 1 ] }, "currency": { "type": "string", "description": "The currency used for this credit.", "examples": [ "NOK" ] }, "orderVersion": { "type": "integer", "description": "Version of the order this credit belongs to.", "format": "int32", "examples": [ 1 ] }, "settlementId": { "type": "integer", "description": "Supplied to the client by an external system for handling settlements. For Internal Entur Clients this is Entur’s Electronic Journal.", "format": "int64" }, "customerNumber": { "type": "string", "description": "ID of the customer who owns this credit.", "examples": [ "123456789" ] }, "organisationId": { "type": "integer", "description": "ID of the organisation who created this credit.", "format": "int64", "examples": [ 1 ] }, "totalCreditAmount": { "type": "string", "description": "Total amount to credit, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] }, "creditTransactions": { "type": "array", "description": "List of individual transactions to credit.", "items": { "$ref": "#/components/schemas/CreditTransactionResponse" }, "examples": [ [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "creditedAt": "2025-01-12T16:13:13Z", "newGiftCardId": "0068a450-066f-442d-8117-1543fe2b1e0e", "transactionData": { "extraData": "any extra data you want to add" }, "reimbursementMethod": "VISA", "paymentTransactionId": 10, "reimbursementTypeGroup": "PAYMENTCARD" } ] ] } }, "description": "Information about credits performed on an order.", "examples": [ { "active": true, "orderId": "ABCD1234", "creditId": 1, "currency": "NOK", "orderVersion": 1, "settlementId": 1245, "customerNumber": "123456789", "organisationId": 1, "totalCreditAmount": "450.00", "creditTransactions": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "creditedAt": "2025-01-12T16:13:13Z", "newGiftCardId": "0068a450-066f-442d-8117-1543fe2b1e0e", "transactionData": { "extraData": "any extra data you want to add" }, "reimbursementMethod": "VISA", "paymentTransactionId": 10, "reimbursementTypeGroup": "PAYMENTCARD" } ] } ] }, "InvoiceRequest": { "title": "InvoiceRequest", "type": "object", "properties": { "invoiceId": { "type": "integer", "description": "Id of Invoice. Only set in request for PUT", "format": "int64", "examples": [ 1 ] }, "redirectUrl": { "pattern": "^(https?://).{0,1024}", "type": "string", "description": "Location to be redirected to from the payment terminal. Required for Collector", "examples": [ "https://www.entur.org" ] }, "languageCode": { "type": "string", "description": "Language code to override terminal language and invoice if possible. Overrides customer preferences. ISO 639-3 format. ", "default": "NOB", "examples": [ "NOB" ] }, "externalInvoiceNumber": { "type": "string", "description": "An external invoice number that is generated outside the sales system. This number is the invoice number on the written invoice, and must be sent to Xledger", "examples": [ "21000557302577563" ] }, "customerIdentificationNumber": { "type": "string", "description": "Customer identification number to identify customer information on electronic banking transactions. Used for penalty fare invoices in Xledger. Has absolutely nothing to do with Entur customers.", "examples": [ "12345678" ] } }, "description": "Information used to customize an invoice.", "examples": [ { "invoiceId": 1, "redirectUrl": "https://www.entur.org", "languageCode": "NOB", "externalInvoiceNumber": "21000557302577563", "customerIdentificationNumber": "12345678" } ] }, "PaymentRequest": { "title": "PaymentRequest", "required": [ "orderId", "orderVersion", "totalAmount" ], "type": "object", "properties": { "orderId": { "type": "string", "description": "Id of the order this payment belongs to.", "examples": [ "HE8NDS7XY" ] }, "currency": { "pattern": "[A-Z]{3}", "type": "string", "description": "3-letter ISO 4217 currency code. Default is NOK.", "default": "NOK", "examples": [ "NOK" ] }, "totalAmount": { "maxLength": 19, "pattern": "^[1-9][0-9]{0,17}\\.[0-9]{1,5}$|^([1-9])[0-9]{0,17}$|^[0]\\.[1-9][0-9]{1,5}$", "type": "string", "description": "Amount to pay, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] }, "transaction": { "$ref": "#/components/schemas/TransactionRequest" }, "orderVersion": { "type": "integer", "description": "Version of the order this payment belongs to.", "format": "int32", "examples": [ 1 ] }, "settlementId": { "type": "integer", "description": "Supplied to the client by an external system for handling settlements. For Internal Entur Clients this is Entur’s Electronic Journal.", "format": "int64", "examples": [ 18234 ] }, "customerNumber": { "type": "string", "description": "Customer who owns this payment. This value is only considered for privileged client (internal and partner tenants.", "examples": [ "123456789" ] } }, "description": "Information used to create a Payment.", "examples": [ { "orderId": "ABCD1234", "currency": "NOK", "totalAmount": "450.00", "transaction": { "amount": "450.00", "currency": "NOK", "isImport": false, "paymentType": "VISA", "scaExemption": "LOW_VALUE", "with3DSecure": true, "paymentTypeGroup": "PAYMENTCARD", "recurringPaymentId": 1 }, "orderVersion": 1, "settlementId": 1245, "customerNumber": "123456789" } ] }, "PaymentTypeFee": { "title": "PaymentTypeFee", "required": [ "amount", "currency", "name", "taxAmount" ], "type": "object", "properties": { "name": { "pattern": "[A-Z]{3}:[^:]+:[^:]+", "type": "string", "description": "Name of the fee in NeTEX format identifying a fee.", "examples": [ "ENT:PaymentTypeFee:Collector" ] }, "amount": { "maxLength": 19, "pattern": "^[1-9][0-9]{0,17}\\.[0-9]{1,5}$|^([1-9])[0-9]{0,17}$|^[0]\\.[1-9][0-9]{1,5}$", "type": "string", "description": "Total amount including taxes", "examples": [ "100.00" ] }, "reason": { "type": "string", "description": "The reason for the fee, if applicable.", "examples": [ "Walley Invoice" ] }, "taxCode": { "type": "string", "description": "The tax code for the tax rate, if applicable", "examples": [ "3" ] }, "taxRate": { "type": "string", "description": "The tax rate of this fee, if applicable", "examples": [ "25.00" ] }, "currency": { "type": "string", "description": "The currency in 3-letter ISO-4217 standard codes", "default": "NOK", "examples": [ "NOK" ] }, "taxAmount": { "type": "string", "description": "The total amount of taxes this fee consists of", "examples": [ "25.00" ] } }, "description": "Fee related to a payment method.", "deprecated": true, "examples": [ { "name": "ENT:PaymentTypeFee:Collector", "amount": "450.00", "reason": "Walley Invoice", "taxCode": "3", "taxRate": "25.00", "currency": "NOK", "taxAmount": "25.00" } ] }, "WalletProvider": { "type": "string", "description": "Examples of providers are ApplePay and GooglePay. Both of these are supported.", "enum": [ "APPLE_PAY", "GOOGLE_PAY" ], "examples": [ "APPLE_PAY" ] }, "AppClaimRequest": { "title": "AppClaimRequest", "type": "object", "properties": { "description": { "type": "string", "description": "Customize the text to be presented to the end-user in the payment app. This often involves some kind of product information.", "examples": [ "Train ticket(s) from entur.org" ] }, "phoneNumber": { "pattern": "^([0-9]{8}|\\+?[0-9]{10,15})$", "type": "string", "description": "Phone number where the claim should be presented. Accepted formats: 8-digit Norwegian number (country code 47 is added automatically if not provided), MSISDN (digits only, country code included, 10–15 digits), or E.164 (leading +, 10–15 digits). Supported country codes: Norway (47), Denmark (45), Sweden (46), Finland (358).", "examples": [ "4791234567" ] }, "redirectUrl": { "minLength": 1, "type": "string", "description": "Location to be redirected to from the 3rd party landing page/app.", "examples": [ "https://www.entur.org or my-app://my-url" ] } }, "description": "Information used to create a payment claim in a mobile app where end-user can accept payment.", "examples": [ { "description": "Train ticket(s) from entur.org", "phoneNumber": "12345678", "redirectUrl": "https://www.entur.org or my-app://my-url" } ] }, "FlexiblePricing": { "description": "Flexible pricing with no fixed interval or amount.", "allOf": [ { "$ref": "#/components/schemas/AgreementPricing" }, { "required": [ "currency" ], "type": "object", "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "ISO 4217 currency code." } } } ] }, "GiftCardRequest": { "title": "GiftCardRequest", "required": [ "giftCardCode" ], "type": "object", "properties": { "giftCardCode": { "type": "string", "description": "The code identifying a gift card.", "nullable": false, "examples": [ "1927bd54-4cc4" ] } }, "description": "Information used to create a payment claim with a gift card.", "examples": [ { "giftCardCode": "1927bd54-4cc4" } ] }, "InvoiceResponse": { "title": "InvoiceResponse", "required": [ "invoiceId", "paymentId", "transactionId" ], "type": "object", "properties": { "invoiceId": { "type": "integer", "description": "ID of the invoice connected to the payment. Used to lookup invoice in the invoice api", "format": "int64", "examples": [ 1 ] }, "paymentId": { "type": "integer", "description": "ID of the payment the transaction belongs to. Used with the transactionId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "expiryDate": { "type": "string", "description": "If paymentType is COLLECTOR_B2B: Expiry date for when invoice is no longer payable", "format": "date-time", "examples": [ "2025-09-30T22:00:00Z" ] }, "publicToken": { "type": "string", "description": "If paymentType is COLLECTOR_B2B: Token used in creation of payment iframe", "examples": [ "public-SE-0a94436dba53edc468584935e7da524eb8d5d8feab85ed03" ] }, "terminalUri": { "type": "string", "description": "If paymentType is COLLECTOR: Location of the payment terminal, else null", "examples": [ "https://epayment.nets.eu/Terminal/default.aspx?merchantId=1234567&transactionId=77770fb3a53347777071cd6f4a3e7777" ] }, "transactionId": { "type": "integer", "description": "ID of the transaction this terminal belongs to. Used with the paymentId to later capture transaction.", "format": "int64", "examples": [ 1 ] } }, "description": "Information about the invoice payment", "examples": [ { "invoiceId": 1, "paymentId": 1, "expiryDate": "2025-09-30T22:00:00.000Z", "publicToken": "public-SE-0a94436dba53edc468584935e7da524eb8d5d8feab85ed03", "terminalUri": "https://epayment.nets.eu/Terminal/default.aspx?merchantId=1234567&transactionId=77770fb3a53347777071cd6f4a3e7777", "transactionId": 10 } ] }, "PaymentResponse": { "title": "Payment", "required": [ "createdAt", "currency", "orderId", "orderVersion", "organisationId", "paymentId", "totalAmount" ], "type": "object", "properties": { "active": { "type": "boolean", "description": "This is to block any transactions after the corresponding order version is reset. Clients importing transactions need to either cancel or credit each transaction externally, and the credit the transaction directly using the transaction's credit endpoint. To continue using the same order id, the payment has to be reactivated with the correct total amount before any new actions can be made to this payment. Editable: true", "examples": [ false ] }, "orderId": { "type": "string", "description": "Id of the order this payment belongs to.", "examples": [ "HE8NDS7XY" ] }, "currency": { "type": "string", "description": "3-letter ISO 4217 currency code. Default is NOK.", "default": "NOK", "examples": [ "NOK" ] }, "createdAt": { "type": "string", "description": "Timestamp for when payment was created.", "format": "date-time", "examples": [ "2025-01-12T16:13:13Z" ] }, "paymentId": { "type": "integer", "description": "Id of payment", "format": "int64", "examples": [ 123 ] }, "updatedAt": { "type": "string", "description": "Timestamp for when payment was last updated.", "format": "date-time", "examples": [ "2025-01-12T16:13:13Z" ] }, "totalAmount": { "type": "string", "description": "Amount to pay, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. Editable: true", "examples": [ "450.00" ] }, "orderVersion": { "type": "integer", "description": "Version of the order this payment belongs to.", "format": "int32", "examples": [ 1 ] }, "settlementId": { "type": "integer", "description": "Supplied to the client by an external system for handling settlements. For Internal Entur Clients this is Entur’s Electronic Journal.", "format": "int64", "examples": [ 18234 ] }, "customerNumber": { "type": "string", "description": "ID of the customer who owns this payment.", "examples": [ "123456789" ] }, "organisationId": { "type": "integer", "description": "Id of the organisation who created this payment.", "format": "int64", "examples": [ 1 ] }, "transactionHistory": { "type": "array", "description": "List of all transactions belonging to this payment.", "items": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": [ [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "summary": { "capturedAmount": "450.00", "creditedAmount": "450.00", "remainingAmountToCredit": "0.00", "remainingAmountToCapture": "0.00" }, "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "updatedAt": "2025-01-12T16:13:13Z", "cardNumber": "0004", "paymentType": "VISA", "operationLog": [ { "pos": "18930345", "error": { "code": "25", "source": "Netaxept", "message": "Transaction not found." }, "amount": "450.00", "operation": "CREATE", "timestamp": "2025-08-24T14:15:22Z", "distributionChannelId": "ENT:DistributionChannel:Test" } ], "transactionId": 10, "paymentTypeFee": { "name": "ENT:PaymentTypeFee:Collector", "amount": "450.00", "reason": "Walley Invoice", "taxCode": "3", "taxRate": "25.00", "currency": "NOK", "taxAmount": "25.00" }, "transactionData": { "extraData": "any extra data you want to add" }, "paymentTypeGroup": "PAYMENTCARD", "recurringPaymentId": 1 } ] ] } }, "description": "Information about an order's payment.", "examples": [ { "active": true, "orderId": "ABCD1234", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "totalAmount": "450.00", "orderVersion": 1, "settlementId": 1245, "customerNumber": "123456789", "organisationId": 1, "transactionHistory": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "summary": { "capturedAmount": "450.00", "creditedAmount": "450.00", "remainingAmountToCredit": "0.00", "remainingAmountToCapture": "0.00" }, "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "updatedAt": "2025-01-12T16:13:13Z", "cardNumber": "0004", "paymentType": "VISA", "operationLog": [ { "pos": "18930345", "error": { "code": "25", "source": "Netaxept", "message": "Transaction not found." }, "amount": "450.00", "operation": "CREATE", "timestamp": "2025-08-24T14:15:22Z", "distributionChannelId": "ENT:DistributionChannel:Test" } ], "transactionId": 10, "paymentTypeFee": { "name": "ENT:PaymentTypeFee:Collector", "amount": "450.00", "reason": "Walley Invoice", "taxCode": "3", "taxRate": "25.00", "currency": "NOK", "taxAmount": "25.00" }, "transactionData": { "extraData": "any extra data you want to add" }, "paymentTypeGroup": "PAYMENTCARD", "recurringPaymentId": 1 } ] } ] }, "RecurringStatus": { "type": "string", "description": "Status of this recurring payment", "enum": [ "ACTIVE", "CANCELLED", "CREATED", "DEFAULTED", "EXPIRED" ], "examples": [ "ACTIVE" ] }, "TerminalRequest": { "title": "TerminalRequest", "required": [ "redirectUrl" ], "type": "object", "properties": { "autoSale": { "type": "boolean", "description": "If this flag is set to true, the capture call after a customer returns from the terminal is not needed. The processing starts automatically. This is only compatible with payments done with payment cards.", "default": false }, "singlePage": { "type": "boolean", "description": "If this flag is set to true, we will attempt to generate a single-page terminal. If false, multi-page terminal might be used.", "default": false, "examples": [ false ] }, "callbackUrl": { "type": "string", "description": "Location where notification of payment completion will be sent. If this is not provided, then the client will have to check for completion manually by getting the transaction and checking its status. The callback will be repeated until the server receives an HTTP 202 response.", "examples": [ "https://entur.org" ] }, "countryCode": { "$ref": "#/components/schemas/TerminalCountryCode" }, "redirectUrl": { "pattern": "^(https?://).{0,1024}", "type": "string", "description": "Location to be redirected to from the payment terminal.", "examples": [ "https://www.entur.org" ] }, "storePayment": { "type": "boolean", "description": "Should the card be stored for recurring payments. If customer is not logged in, the value of this will be disregarded.", "default": false, "examples": [ false ] }, "customerNumber": { "type": "string", "description": "Customer number used with recurring payment creation. This field is optional and will only be considered for certain privileged clients.", "examples": [ "123456789" ] }, "transactionType": { "$ref": "#/components/schemas/TransactionType" }, "terminalLanguage": { "$ref": "#/components/schemas/TerminalLanguage" } }, "description": "Information used to customize the payment terminal.", "examples": [ { "autoSale": true, "singlePage": true, "callbackUrl": "https://entur.org", "countryCode": "NO", "redirectUrl": "https://www.entur.org", "storePayment": true, "customerNumber": "123456789", "terminalLanguage": "no_NO" } ] }, "TransactionType": { "type": "string", "description": "Set the type of transaction. Only set this field to MIT_UCOF if you want to create a Merchant Initiated Transaction (MIT) which refers to a card payment started by a merchant without the customer being actively involved. If this value is not set, a payment terminal will be created as normal.", "enum": [ "MIT_UCOF" ], "examples": [ "MIT_UCOF" ] }, "ValidationError": { "title": "ValidationError", "description": "An error that is returned when the input from the client was not validated. It's an extension of the PaymentError", "allOf": [ { "$ref": "#/components/schemas/PaymentError" }, { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } ], "examples": [ { "path": "/v1/payments/", "error": "Bad request", "errors": [ "Payment amount '200.00' does not equal order balance '250.00'" ], "status": 400, "message": "Payment amount '200.00' does not equal order balance '250.00'", "exception": "org.entur.payment.faulthandling.exceptions.ValidationError", "timestamp": "2025-08-24T14:15:22Z" } ] }, "VariablePricing": { "description": "Variable pricing charges a varying amount each interval and requires a suggested maximum amount.", "allOf": [ { "$ref": "#/components/schemas/AgreementPricing" }, { "required": [ "amount", "currency", "interval", "suggestedMaxAmount" ], "type": "object", "properties": { "amount": { "type": "integer", "description": "The amount to charge per interval, in minor units, e.g: øre." }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "ISO 4217 currency code." }, "interval": { "$ref": "#/components/schemas/AgreementInterval" }, "suggestedMaxAmount": { "type": "integer", "description": "A suggested maximum amount per charge, in minor units." } } } ] }, "AgreementPricing": { "required": [ "agreementType" ], "type": "object", "properties": { "agreementType": { "type": "string", "description": "The pricing model type.", "enum": [ "FIXED", "VARIABLE", "FLEXIBLE" ] } }, "description": "Base pricing model for a payment agreement.", "discriminator": { "propertyName": "agreementType", "mapping": { "FIXED": "#/components/schemas/FixedPricing", "FLEXIBLE": "#/components/schemas/FlexiblePricing", "VARIABLE": "#/components/schemas/VariablePricing" } } }, "AppClaimResponse": { "title": "AppClaim", "required": [ "appClaimUrl", "paymentId", "transactionId" ], "type": "object", "properties": { "paymentId": { "type": "integer", "description": "ID of the payment the transaction belongs to. Used with the transactionId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "appClaimUrl": { "type": "string", "description": "Location of the payment terminal.", "examples": [ "https://landing.vipps.no/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni" ] }, "transactionId": { "type": "integer", "description": "ID of the transaction this terminal belongs to. Used with the transactionId to later capture transaction.", "format": "int64", "examples": [ 10 ] } }, "description": "Information about how to access mobile app \"terminal\".", "examples": [ { "paymentId": 1, "appClaimUrl": "https://landing.vipps.no/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni", "transactionId": 10 } ] }, "AuthorizeRequest": { "title": "AuthorizeRequest", "required": [ "totalAmount" ], "type": "object", "properties": { "totalAmount": { "type": "string", "description": "Amount to pay, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] } }, "description": "Information used to update a transaction and payment with correct amount and authorize the new amount to Nets.", "examples": [ { "totalAmount": "450.00" } ] }, "CreditMergePatch": { "title": "CreditMergePatch", "required": [ "totalCreditAmount" ], "properties": { "active": { "type": "boolean", "description": "Active is used during activation of credit", "examples": [ true ] }, "totalCreditAmount": { "type": "string", "description": "Amount to credit, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] }, "creditTransactions": { "type": "array", "description": "List of individual transactions to credit.", "items": { "$ref": "#/components/schemas/CreditTransactionRequest" }, "examples": [ [ { "amount": "450.00", "currency": "NOK", "paymentTransactionId": 1, "reimbursementTypeGroup": "PAYMENTCARD" } ] ] } }, "description": "Request body used to update a credit. The properties described here are the only properties that can be updated on a credit.", "examples": [ { "active": true, "totalCreditAmount": "450.00", "creditTransactions": [ { "amount": "450.00", "currency": "NOK", "paymentTransactionId": 1, "reimbursementTypeGroup": "PAYMENTCARD" } ] } ] }, "PaymentTypeGroup": { "type": "string", "description": "A PaymentTypeGroup used to override which kind of method to use for reimbursement, instead of using same as used for the payment transaction.This will only take effect if the payment method on the payment transaction allows for overriding.", "enum": [ "AGENT", "CASH", "ECARD", "GIFTCARD", "INVOICE", "MOBILE", "PAYMENTCARD", "PAYPAL", "REMITTED", "REQUISITION", "TRAVELACCOUNT" ], "examples": [ "CASH" ] }, "TerminalLanguage": { "type": "string", "description": "Language used in the payment terminal. Default is 'no_NO'.", "enum": [ "da_DK", "de_DE", "en_GB", "es_ES", "et_EE", "fi_FI", "fr_FR", "it_IT", "lt_LT", "lv_LV", "nl_NL", "no_NO", "pl_PL", "ru_RU", "sv_SE" ], "examples": [ "no_NO" ] }, "TerminalResponse": { "title": "Terminal", "required": [ "terminalUri" ], "type": "object", "properties": { "paymentId": { "type": "integer", "description": "ID of the payment the transaction belongs to. Used with the transactionId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "terminalUri": { "type": "string", "description": "Location of the payment terminal.", "examples": [ "https://epayment.nets.eu/Terminal/default.aspx?merchantId=700000&transactionId=8841532204d4426da913a5abfbg322f0" ] }, "transactionId": { "type": "integer", "description": "ID of the transaction this terminal belongs to. Used with the paymentId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "recurringPaymentId": { "type": "integer", "description": "ID of the recurring payment this terminal belongs to.", "format": "int64", "examples": [ 1 ] } }, "description": "Information about how to access the terminal.", "examples": [ { "paymentId": 1, "terminalUri": "https://epayment.nets.eu/Terminal/default.aspx?merchantId=1234567&transactionId=77770fb3a53347777071cd6f4a3e7777", "transactionId": 1, "recurringPaymentId": 1 } ] }, "AgreementInterval": { "required": [ "count", "unit" ], "type": "object", "properties": { "unit": { "type": "string", "description": "The time unit for the interval.", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "count": { "minimum": 1, "type": "integer", "description": "The number of time units per interval." } }, "description": "Defines the billing interval for a payment agreement." }, "AuthorizeResponse": { "title": "AuthorizeResponse", "required": [ "paymentId", "transactionId" ], "type": "object", "properties": { "paymentId": { "type": "integer", "description": "ID of the payment the transaction belongs to. Used with the transactionId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "transactionId": { "type": "integer", "description": "ID of the transaction this terminal belongs to. Used with the paymentId to later capture transaction.", "format": "int64", "examples": [ 10 ] } }, "description": "Information about the authorized transaction", "examples": [ { "paymentId": 1, "transactionId": 10 } ] }, "PaymentMergePatch": { "title": "PaymentMergePatch", "required": [ "totalAmount" ], "properties": { "active": { "type": "boolean", "description": "Active is used during activation of payment", "examples": [ true ] }, "totalAmount": { "type": "string", "description": "Amount to pay, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. Editable: true", "examples": [ "450.00" ] }, "settlementId": { "type": "integer", "description": "Id of a settlement used to identify on-site payments i.e. mobile terminals, ticket vending machines and customer service help-desks.", "examples": [ 100123 ] } }, "description": "Request body udes to update a payment. The properties described here are the only properties that can be updated on a payment.", "examples": [ { "active": true, "totalAmount": "450.00" } ] }, "TransactionStatus": { "type": "string", "description": "Current state of the transaction.", "enum": [ "CANCELLED", "CAPTURED", "CREATED", "CREDITED", "INITIATED", "REJECTED" ], "examples": [ "CREATED" ] }, "TransactionRequest": { "title": "TransactionRequest", "required": [ "amount" ], "type": "object", "properties": { "amount": { "type": "string", "description": "Amount to pay, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. ", "examples": [ "450.00" ] }, "currency": { "pattern": "[A-Z]{3}", "type": "string", "description": "3-letter ISO 4217 currency code. Default is NOK.", "default": "NOK", "examples": [ "NOK" ] }, "isImport": { "type": "boolean", "description": "Import flag. Selects a special payment method for imports.", "default": false, "examples": [ false ] }, "paymentType": { "$ref": "#/components/schemas/PaymentType" }, "scaExemption": { "$ref": "#/components/schemas/ScaExemption" }, "with3DSecure": { "type": "boolean", "description": "Flag to choose payment methods with or without 3D Secure. This option is only accessible to privileged clients.", "default": true, "examples": [ true ] }, "createAgreement": { "type": "boolean", "description": "If true, a new FLEXIBLE Vipps agreement is created and the transaction amount becomes the initial charge. The user must approve the agreement before the charge is processed. Use with paymentType VIPPS / paymentTypeGroup MOBILE. Mutually exclusive with paymentAgreementId and recurringPaymentId.", "default": false, "examples": [ false ] }, "paymentTypeGroup": { "$ref": "#/components/schemas/PaymentTypeGroup" }, "paymentAgreementId": { "type": "integer", "description": "ID of the payment agreement to charge against. Used for Vipps recurring agreement payments. Mutually exclusive with recurringPaymentId.", "format": "int64", "examples": [ 456 ] }, "recurringPaymentId": { "type": "integer", "description": "ID of the saved payment method to use for this transaction.", "format": "int64", "examples": [ 123 ] } }, "description": "Information used to create a transaction.", "examples": [ { "amount": "450.00", "currency": "NOK", "isImport": false, "paymentType": "VISA", "scaExemption": "LOW_VALUE", "with3DSecure": true, "paymentTypeGroup": "PAYMENTCARD", "recurringPaymentId": 1 } ] }, "TransactionSummary": { "title": "TransactionSummary", "required": [ "capturedAmount", "creditedAmount", "remainingAmountToCapture", "remainingAmountToCredit" ], "type": "object", "properties": { "capturedAmount": { "type": "string", "description": "Captured amount, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. ", "examples": [ "450.00" ] }, "creditedAmount": { "type": "string", "description": "Credited amount, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. ", "examples": [ "450.00" ] }, "remainingAmountToCredit": { "type": "string", "description": "Remaining amount to credit, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. ", "examples": [ "450.00" ] }, "remainingAmountToCapture": { "type": "string", "description": "Remaining amount to capture, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. ", "examples": [ "450.00" ] } }, "description": "Aggregated summary of amounts on a transaction.", "examples": [ { "capturedAmount": "450.00", "creditedAmount": "450.00", "remainingAmountToCredit": "0.00", "remainingAmountToCapture": "0.00" } ] }, "TerminalCountryCode": { "type": "string", "description": "ISO 3166-1 Alpha 2 country code used for certain terminals (PayPal, Collector). Used to decide which country store the customer wants to use. Default is 'NO'", "default": "NO", "enum": [ "NO", "DK", "SE", "FI" ], "examples": [ "NO" ] }, "TransactionResponse": { "title": "Transaction", "required": [ "amount", "createdAt", "currency", "status", "transactionId" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "Reconciliation reference number used to track a transaction through different economy systems.", "examples": [ "000012345678" ] }, "amount": { "type": "string", "description": "Amount to pay, represented in the standard currency unit. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. Deprecated and will be removed in next version of API. Use summary instead.", "examples": [ "450.00" ] }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "summary": { "$ref": "#/components/schemas/TransactionSummary" }, "currency": { "type": "string", "description": "3-letter currency code. (ISO 4217)", "default": "NOK", "examples": [ "NOK" ] }, "createdAt": { "type": "string", "description": "Timestamp for when transaction was first created.", "format": "date-time", "readOnly": true, "examples": [ "2025-09-30T22:00:00Z" ] }, "updatedAt": { "type": "string", "description": "Timestamp for when transaction was last updated.", "format": "date-time", "readOnly": true, "examples": [ "2025-09-30T22:00:00Z" ] }, "cardNumber": { "type": "string", "description": "Last 4 digits in card number (PAN - Personal Account Number)", "examples": [ "0004" ] }, "paymentType": { "$ref": "#/components/schemas/PaymentType" }, "operationLog": { "type": "array", "description": "Log of each successful operation made on the transaction. Failing operations will not be included.", "items": { "$ref": "#/components/schemas/TransactionOperationResponse" }, "examples": [ [ { "pos": "18930345", "error": { "code": "25", "source": "Netaxept", "message": "Transaction not found." }, "amount": "450.00", "operation": "CREATE", "timestamp": "2025-08-24T14:15:22Z", "distributionChannelId": "ENT:DistributionChannel:Test" } ] ] }, "transactionId": { "type": "integer", "description": "ID of the specific transaction.", "format": "int64", "examples": [ 1 ] }, "paymentTypeFee": { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/PaymentTypeFee" } ] }, "transactionData": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra transaction data from external client. Only relevant for clients using the import flow.", "examples": [ { "extraData": "any extra data you want to add" } ] }, "paymentTypeGroup": { "$ref": "#/components/schemas/PaymentTypeGroup" }, "paymentAgreementId": { "type": "integer", "description": "ID of the payment agreement associated with this transaction, if any.", "format": "int64", "examples": [ 456 ] }, "recurringPaymentId": { "type": "integer", "description": "Reference to the saved payment agreement this transaction will use, if any was specified.", "format": "int64", "examples": [ 123 ] } }, "description": "Payment transaction information", "examples": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "summary": { "capturedAmount": "450.00", "creditedAmount": "450.00", "remainingAmountToCredit": "0.00", "remainingAmountToCapture": "0.00" }, "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "updatedAt": "2025-01-12T16:13:13Z", "cardNumber": "0004", "paymentType": "VISA", "operationLog": [ { "pos": "18930345", "error": { "code": "25", "source": "Netaxept", "message": "Transaction not found." }, "amount": "450.00", "operation": "CREATE", "timestamp": "2025-08-24T14:15:22Z", "distributionChannelId": "ENT:DistributionChannel:Test" } ], "transactionId": 10, "paymentTypeFee": { "name": "ENT:PaymentTypeFee:Collector", "amount": "450.00", "reason": "Walley Invoice", "taxCode": "3", "taxRate": "25.00", "currency": "NOK", "taxAmount": "25.00" }, "transactionData": { "extraData": "any extra data you want to add" }, "paymentTypeGroup": "PAYMENTCARD", "recurringPaymentId": 1 } ] }, "PaymentMethodResponse": { "title": "PaymentMethodResponse", "required": [ "distributionChannelId", "id", "paymentTypeGroup" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for a payment method.", "format": "int64", "examples": [ 1 ] }, "clientId": { "type": "string", "description": "ID of the client this payment method belongs to. This ID is the one found in the client's token.", "examples": [ "sS7grDF79fddBFd4=" ] }, "paymentType": { "type": "string", "description": "The actual type of payment.", "examples": [ "VISA" ] }, "paymentConfig": { "$ref": "#/components/schemas/PaymentConfigurationResponse" }, "paymentTypeFee": { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/PaymentTypeFee" } ] }, "paymentTypeGroup": { "type": "string", "description": "Group for the payment type. Payment types which are payment cards is in the PAYMENTCARD group.", "examples": [ "PAYMENTCARD" ] }, "distributionChannelId": { "type": "string", "description": "Distribution Channels controls which organisations can sell, refund or inform on available products or salepoints.", "examples": [ "ENT:DistributionChannel:Test" ] } }, "description": "Result from creating a PaymentMethod.", "examples": [ { "id": 1, "paymentType": "VISA", "paymentConfig": { "id": 1, "accountName": "Entur Test", "merchantConfig": { "someKey": { "configParam": "configValue" } }, "paymentProvider": "NETAXEPT" }, "paymentTypeFee": { "name": "ENT:PaymentTypeFee:Collector", "amount": "450.00", "reason": "Walley Invoice", "taxCode": "3", "taxRate": "25.00", "currency": "NOK", "taxAmount": "25.00" }, "paymentTypeGroup": "PAYMENTCARD", "distributionChannelId": "ENT:DistributionChannel:Test" } ] }, "PaymentWebhookRequest": { "title": "PaymentWebhookRequest", "required": [ "enturPaymentTransactionId", "eventName", "partnerTransactionId", "transactionSummary" ], "type": "object", "properties": { "id": { "type": "string", "description": "The identification of a sent webhook event.", "examples": [ "1" ] }, "eventName": { "type": "string", "description": "The name of the event that is being sent with the webhook. Currently only support CREDIT-events", "examples": [ "CREDIT" ] }, "timestamp": { "maxLength": 10, "minLength": 1, "pattern": "^[0-9]+$", "type": "string", "description": "Unix timestamp (seconds since epoch) for when webhook was sent.", "examples": [ "1736698393" ] }, "transactionData": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra transaction data from external client. Only relevant for clients using the import flow.", "examples": [ { "extraData": "any extra data you want to add" } ] }, "transactionSummary": { "$ref": "#/components/schemas/WebhookTransactionSummary" }, "externalTransactionId": { "type": "string", "description": "The transaction id of the transaction in the partners system. This is provided by the partner when importing the transaction.", "examples": [ "1234" ] }, "enturPaymentTransactionId": { "type": "integer", "description": "The transaction id of the transaction in Entur's system.", "format": "int64", "examples": [ 1 ] } }, "description": "The request object a client can expect to receive when we send them webhooks.", "examples": [ { "eventName": "CREDIT", "transactionSummary": { "capturedAmount": "100.00", "creditedAmount": "100.00" }, "partnerTransactionId": "1234", "enturPaymentTransactionId": 1 } ] }, "PanHashTerminalRequest": { "title": "PanHashTerminalRequest", "required": [ "panHash", "recurringType", "redirectUrl" ], "type": "object", "properties": { "panHash": { "type": "string", "description": "The pan hash used to execute the payment.", "examples": [ "eVHXJzGr4gu1lz9TwGJU" ] }, "redirectUrl": { "pattern": "^(https?://).{0,1024}", "type": "string", "description": "Location to be redirected to from the payment terminal.", "examples": [ "http://www.entur.org" ] }, "recurringType": { "maxLength": 1, "minLength": 1, "pattern": "^R|S$", "type": "string", "description": "The type of the recurring payment. Can be either R og S.", "examples": [ "R" ] } }, "description": "Information used to create a terminal.", "examples": [ { "panHash": "eVHXJzGr4gu1lz9TwGJU", "redirectUrl": "https://www.entur.org", "recurringType": "R" } ] }, "InternalTerminalRequest": { "title": "InternalTerminalRequest", "required": [ "redirectUrl" ], "type": "object", "properties": { "redirectUrl": { "pattern": "^(https?://).{0,1024}", "type": "string", "description": "Location to be redirected to from the payment terminal.", "examples": [ "http://www.entur.org" ] } }, "description": "Information used to customize the payment terminal.", "examples": [ { "redirectUrl": "https://www.entur.org" } ] }, "RecurringPaymentRequest": { "title": "RecurringPaymentRequest", "type": "object", "properties": { "nickname": { "type": "string", "description": "Nickname for the recurring payment", "examples": [ "Bottomless mastercard" ] }, "isPrimary": { "type": "boolean", "description": "Is the recurring payment the primary recurring payment of the user. There can only be one primary recurring payment at a time. Therefore, changing this status to true might set another recurring payment's isPrimary to false.", "examples": [ false ] }, "customerNumber": { "type": "string", "description": "The customer number this recurring payment belongs to. This field is optional and will only be considered for certain privileged clients. This value can not be updated.", "examples": [ "42" ] } }, "description": "Recurring payment API resource.", "examples": [ { "nickname": "Bottomless mastercard", "isPrimary": true, "customerNumber": "123456789" } ] }, "CreditTransactionRequest": { "title": "CreditTransactionRequest", "required": [ "amount", "paymentTransactionId" ], "type": "object", "properties": { "amount": { "maxLength": 19, "pattern": "^[1-9][0-9]{0,17}\\.[0-9]{1,5}$|^([1-9])[0-9]{0,17}$|^[0]\\.[1-9][0-9]{1,5}$", "type": "string", "description": "Amount to credit, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] }, "currency": { "pattern": "[A-Z]{3}", "type": "string", "description": "3-letter ISO 4217 currency code. Default is NOK.", "default": "NOK", "examples": [ "NOK" ] }, "paymentTransactionId": { "type": "integer", "description": "Reference to the transaction to credit.", "format": "int64", "examples": [ 1 ] }, "reimbursementTypeGroup": { "$ref": "#/components/schemas/PaymentTypeGroup" }, "transactionImportRequest": { "description": "Required data when importing transaction/overriding method of reimbursement. This only works when importing already credited transactions, and will only be considered when this is the case.", "allOf": [ { "$ref": "#/components/schemas/TransactionImportRequest" } ] } }, "description": "Single credit transaction referring to a single payment transaction.", "examples": [ { "amount": "450.00", "currency": "NOK", "paymentTransactionId": 1, "reimbursementTypeGroup": "PAYMENTCARD" } ] }, "InternalTerminalResponse": { "title": "Internal Terminal", "required": [ "terminalUrl" ], "type": "object", "properties": { "paymentId": { "type": "integer", "description": "ID of the payment the transaction belongs to.", "format": "int64", "examples": [ 1 ] }, "terminalUrl": { "type": "string", "description": "Location of the payment terminal.", "examples": [ "https://terminal.entur.no/?data=MTAzNTgzMzoxMDY1NTY4" ] }, "transactionId": { "type": "integer", "description": "ID of the transaction this terminal belongs to.", "format": "int64", "examples": [ 1 ] } }, "description": "Information about how to access the terminal.", "examples": [ { "paymentId": 1, "terminalUrl": "https://terminal.staging.entur.no/?data=MTAzNTgzMzoxMDY1NTY4", "transactionId": 1 } ] }, "PaymentAgreementResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "The current status of the agreement.", "enum": [ "CREATED", "PENDING", "ACTIVE", "STOPPED", "EXPIRED" ] }, "pricing": { "$ref": "#/components/schemas/AgreementPricing" }, "agreementId": { "type": "integer", "description": "The unique identifier of the payment agreement.", "format": "int64" }, "productName": { "type": "string", "description": "Name of the product or subscription." }, "providerData": { "$ref": "#/components/schemas/AgreementResponseProviderData" } }, "description": "Response containing payment agreement details." }, "RecurringPaymentResponse": { "title": "RecurringPaymentResponse", "required": [ "cardExpiresAt", "expiresAt", "maskedPan", "paymentType", "primary", "recurringPaymentId", "recurringStatus" ], "type": "object", "properties": { "primary": { "type": "boolean", "description": "Is the recurring payment the primary recurring payment of the user. There can only be one primary recurring payment at a time. Therefore, changing this status to true might set another recurring payment's isPrimary to false.", "examples": [ false ] }, "nickname": { "type": "string", "description": "Nickname for the recurring payment", "examples": [ "Bottomless mastercard" ] }, "expiresAt": { "type": "string", "description": "When the recurring payment is no longer valid", "format": "date-time", "examples": [ "2025-02-12T16:13:13Z" ] }, "maskedPan": { "type": "string", "description": "The stored card's masked number", "examples": [ "4925 **** **** 0004" ] }, "paymentType": { "$ref": "#/components/schemas/PaymentType" }, "cardExpiresAt": { "type": "string", "description": "The stored card's expiration date, may be longer than the recurring payment's expiration date, but never shorter.", "format": "date-time", "examples": [ "2025-01-12T16:13:13Z" ] }, "recurringStatus": { "$ref": "#/components/schemas/RecurringStatus" }, "recurringPaymentId": { "type": "integer", "description": "ID of the recurring payment", "format": "int64", "examples": [ 111 ] } }, "description": "Response type for the Recurring Payment API", "examples": [ { "primary": false, "nickname": "Bottomless mastercard", "expiresAt": "2025-01-12T16:13:13Z", "maskedPan": "4925 **** **** 0004", "paymentType": "VISA", "cardExpiresAt": "2025-01-12T16:13:13Z", "recurringStatus": "ACTIVE", "recurringPaymentId": 111 } ] }, "TransactionImportRequest": { "title": "TransactionImportRequest", "required": [ "transactionConfirmedAt" ], "type": "object", "properties": { "rrn": { "maxLength": 12, "minLength": 1, "type": "string", "description": "Reconciliation reference number used to track a transaction through different economy systems. Required for PAYMENTCARD.", "examples": [ "000012345678" ] }, "companyId": { "pattern": "[\\d]{1,4}", "type": "string", "description": "Id of the issuing organisation. The id is equal to the internal id in Enturs Organisation Register. Required for ECARD.", "examples": [ "1" ] }, "terminalId": { "type": "string", "description": "Unique identifier for a physical terminal. Makes a transaction unique together with rrn. Required for PAYMENTCARD.", "examples": [ "123-133-44" ] }, "paymentType": { "type": "string", "description": "Name of the specific payment type used. This further specifies the type of payment method used for this transaction. Often referred to as the name of the issuer for payment cards in the transaction data retrieved from payment terminals. Required for PAYMENTCARD.", "examples": [ "Coop Mastercard" ] }, "envNetworkId": { "pattern": "[\\d]{6}", "type": "string", "description": "County code for issuer", "examples": [ "578000" ] }, "transactionData": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Any extra transaction data which could be relevant can be specified as a key value map of strings.", "examples": [ { "someKey": "someValue" } ] }, "mediaSerialNumberId": { "pattern": "[\\d]{1,10}", "type": "string", "description": "Numerical e-Card identifier. Required for ECARD.", "examples": [ "0067340023" ] }, "externalTransactionId": { "type": "string", "description": "Transaction ID from 3rd party payment provider.", "examples": [ "7381cc2886b147198tuf257440c614fd" ] }, "transactionConfirmedAt": { "type": "string", "description": "Time when payment transaction was completed by the client.", "format": "date-time", "examples": [ "2018-03-07T12:20:46Z" ] } }, "description": "Request body for importing an already completed transaction.", "examples": [ { "rrn": "000123456123", "companyId": "1", "terminalId": "123-133-44", "paymentType": "Coop Mastercard", "envNetworkId": "578000", "transactionData": { "someKey": "someValue" }, "mediaSerialNumberId": "0067340023", "externalTransactionId": "7381cc2886b147198tuf257440c614fd", "transactionConfirmedAt": "2025-01-12T16:13:13Z" } ] }, "CreditTransactionResponse": { "title": "CreditTransaction", "required": [ "amount", "paymentId", "paymentTransactionId", "reimbursementTypeGroup" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "Reconciliation reference number used to track a transaction through different economy systems.", "examples": [ "000012345678" ] }, "amount": { "type": "string", "description": "Amount to credit, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot.", "examples": [ "450.00" ] }, "status": { "type": "string", "description": "Status of this credit transaction.", "enum": [ "CREATED", "CREDITED" ], "examples": [ "CREATED" ] }, "currency": { "type": "string", "description": "3-letter ISO 4217 currency code. Default is NOK.", "examples": [ "NOK" ] }, "createdAt": { "type": "string", "description": "Timestamp for when transaction was first created.", "format": "date-time", "readOnly": true }, "paymentId": { "type": "integer", "description": "Reference to the payment the credited payment transaction belongs to.", "format": "int64", "examples": [ 1 ] }, "updatedAt": { "type": "string", "description": "Timestamp for when transaction was last updated.", "format": "date-time", "readOnly": true, "examples": [ "2025-01-12T16:13:13Z" ] }, "creditedAt": { "type": "string", "description": "Time when credit was confirmed.", "format": "date-time", "examples": [ "2025-01-12T16:13:13Z" ] }, "newGiftCardId": { "type": "string", "description": "Reference to the gift card id (contract uuid) the credited payment transaction belongs to. Note: This field will be set if the transaction was credited to a gift card.", "readOnly": true, "examples": [ "0068a450-066f-442d-8117-1543fe2b1e0e" ] }, "transactionData": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra transaction data from external client. Only relevant for clients using the import flow.", "examples": [ { "extraData": "any extra data you want to add" } ] }, "reimbursementMethod": { "type": "string", "description": "Specific type of reimbursement method.", "examples": [ "VISA" ] }, "paymentTransactionId": { "type": "integer", "description": "Reference to the transaction this credit transaction credits.", "format": "int64", "examples": [ 10 ] }, "reimbursementTypeGroup": { "type": "string", "description": "General type of reimbursement method.", "examples": [ "PAYMENTCARD" ] } }, "description": "Represents a credit transaction referring to a payment transaction.", "examples": [ { "rrn": "000123456123", "amount": "450.00", "status": "CREATED", "currency": "NOK", "createdAt": "2025-01-12T16:08:03Z", "paymentId": 1, "updatedAt": "2025-01-12T16:13:13Z", "creditedAt": "2025-01-12T16:13:13Z", "newGiftCardId": "0068a450-066f-442d-8117-1543fe2b1e0e", "transactionData": { "extraData": "any extra data you want to add" }, "reimbursementMethod": "VISA", "paymentTransactionId": 10, "reimbursementTypeGroup": "PAYMENTCARD" } ] }, "WebhookTransactionSummary": { "title": "WebhookTransactionSummary", "required": [ "capturedAmount", "creditedAmount" ], "type": "object", "properties": { "capturedAmount": { "type": "string", "description": "The amount that has been captured on this transaction", "examples": [ "100.00" ] }, "creditedAmount": { "type": "string", "description": "The amount that has been credited on this transaction.", "examples": [ "100.00" ] } }, "description": "A summary of the the different operations done on a transaction.", "examples": [ { "capturedAmount": "100.00", "creditedAmount": "100.00" } ] }, "PageOfWebhookConfiguration": { "title": "PageOfWebhookConfiguration", "required": [ "items", "totalItems", "totalPages" ], "type": "object", "properties": { "items": { "type": "array", "description": "Items on a specific page", "readOnly": true, "items": { "$ref": "#/components/schemas/WebhookConfigurationResponse" }, "examples": [ [ { "secret": "xgr*hyw8bru4DWZ1wqc", "baseUrl": "https://entur-partner.no/webhooks", "eventPaths": [ { "path": "/credit", "event": "CREDIT" }, { "path": "/capture", "event": "CAPTURE" } ], "organisationId": 1 } ] ] }, "totalItems": { "type": "integer", "description": "Total number of items", "format": "int64", "readOnly": true, "examples": [ 72 ] }, "totalPages": { "type": "integer", "description": "Total number of pages available to browse", "format": "int64", "readOnly": true, "examples": [ 9 ] } }, "description": "Page displays a subset of a list of entities", "examples": [ { "items": [ { "secret": "xgr*hyw8bru4DWZ1wqc", "baseUrl": "https://entur-partner.no/webhooks", "eventPaths": [ { "path": "/credit", "event": "CREDIT" }, { "path": "/capture", "event": "CAPTURE" } ], "organisationId": 1 } ], "totalItems": 1, "totalPages": 1 } ] }, "WebhookConfigurationRequest": { "title": "WebhookConfigurationRequest", "required": [ "baseUrl", "eventPaths" ], "type": "object", "properties": { "baseUrl": { "type": "string", "description": "The client specified base url where they want to use for all event paths.", "examples": [ "https://entur-partner.no/webhooks" ] }, "eventPaths": { "minItems": 1, "type": "array", "description": "A collection of which webhooks events and the paths they should be sent to. The path is combined with the base url to form a complete url", "items": { "$ref": "#/components/schemas/WebhookConfigurationEventPaths" }, "examples": [ [ { "path": "/credit", "event": "CREDIT" }, { "path": "/capture", "event": "CAPTURE" } ] ] } }, "description": "The request body a client will send when registering a webhook configuration.", "examples": [ { "baseUrl": "https://entur-partner.no/webhooks", "eventPaths": [ { "path": "/credit", "event": "CREDIT" }, { "path": "/capture", "event": "CAPTURE" } ] } ] }, "AgreementRequestProviderData": { "required": [ "agreementProvider" ], "type": "object", "properties": { "agreementProvider": { "type": "string", "description": "The payment provider for the agreement.", "enum": [ "VIPPS" ] } }, "description": "Base provider-specific data for creating an agreement.", "discriminator": { "propertyName": "agreementProvider", "mapping": { "VIPPS": "#/components/schemas/VippsAgreementRequestProviderData" } } }, "PaymentConfigurationResponse": { "title": "PaymentConfigurationResponse", "required": [ "accountName", "id", "paymentProvider" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of this payment configuration.", "format": "int64", "examples": [ 1 ] }, "accountName": { "type": "string", "description": "Name describing the owner of the configuration. Usually the name of the client.", "examples": [ "Entur Test" ] }, "merchantConfig": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Key/value map of merchant configuration parameters needed for each merchant. See documentation for specific merchant on which parameters are required.", "examples": [ { "someKey": { "configParam": "configValue" } } ] }, "paymentProvider": { "type": "string", "description": "The payment service provider this configuration is used for. This is not necessarily a 3rd party provider. This will control the way the API is used.", "examples": [ "NETAXEPT" ] } }, "description": "Current payment configuration set up for psp-client relationship.", "examples": [ { "id": 1, "accountName": "Entur Test", "merchantConfig": { "someKey": { "configParam": "configValue" } }, "paymentProvider": "NETAXEPT" } ] }, "TransactionOperationResponse": { "title": "TransactionOperation", "required": [ "amount", "operation", "pos", "timestamp" ], "type": "object", "properties": { "pos": { "type": "string", "description": "Point-of-sale id which performed this operation.", "examples": [ "18930345" ] }, "error": { "$ref": "#/components/schemas/ErrorResponse" }, "amount": { "type": "string", "description": "Amount for this operation, represented in the standard currency. Maximum (totalDigits: 18, fractionDigits: 5) according to ISO 20022. The integer and fractional digits are separated by a dot. ", "examples": [ "450.00" ] }, "operation": { "$ref": "#/components/schemas/Operation" }, "timestamp": { "type": "string", "description": "Time when operation was completed. A date without a time zone in the ISO 8601 calendar system.", "format": "date-time", "examples": [ "2025-01-12T16:13:13Z" ] }, "distributionChannelId": { "type": "string", "description": "Distribution Channels controls which organisations can sell, refund or inform on available products or salepoints. The distribution channel id represents a specific distribution channel.", "examples": [ "ENT:DistributionChannel:Test" ] } }, "description": "Describes an operation performed on a transaction.", "examples": [ { "pos": "18930345", "error": { "code": "25", "source": "Netaxept", "message": "Transaction not found." }, "amount": "450.00", "operation": "CREATE", "timestamp": "2025-08-24T14:15:22Z", "distributionChannelId": "ENT:DistributionChannel:Test" } ] }, "WebhookConfigurationResponse": { "title": "WebhookConfigurationResponse", "required": [ "baseUrl", "eventPaths", "organisationId", "secret" ], "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the webhook configuration", "format": "int64", "examples": [ 1 ] }, "secret": { "type": "string", "description": "The secret that should be used to validate the signature of receive webhooks. This is generated by Entur.", "examples": [ "xgr*hyw8bru4DWZ1wqc" ] }, "baseUrl": { "type": "string", "description": "The client specified base url where they want to use for all event paths.", "examples": [ "https://entur-partner.no/webhooks" ] }, "eventPaths": { "type": "array", "description": "A collection of which webhooks events and the paths they should be sent to. The path is combined with the base url to form a complete url", "items": { "$ref": "#/components/schemas/WebhookConfigurationEventPaths" }, "examples": [ [ { "path": "/credit", "event": "CREDIT" }, { "path": "/capture", "event": "CAPTURE" } ] ] }, "organisationId": { "type": "integer", "description": "The organisation that own this webhook configuration", "format": "int64", "examples": [ 1 ] } }, "description": "The response returned when registering or updating a webhook configuration", "examples": [ { "secret": "xgr*hyw8bru4DWZ1wqc", "baseUrl": "https://entur-partner.no/webhooks", "eventPaths": [ { "path": "/credit", "event": "CREDIT" }, { "path": "/capture", "event": "CAPTURE" } ], "organisationId": 1 } ] }, "AgreementResponseProviderData": { "required": [ "agreementProvider" ], "type": "object", "properties": { "agreementProvider": { "type": "string", "description": "The payment provider for the agreement.", "enum": [ "VIPPS" ] } }, "description": "Base provider-specific data in an agreement response.", "discriminator": { "propertyName": "agreementProvider", "mapping": { "VIPPS": "#/components/schemas/VippsAgreementResponseProviderData" } } }, "CreatePaymentAgreementRequest": { "required": [ "customerNumber", "pricing", "productName", "providerData" ], "type": "object", "properties": { "pricing": { "$ref": "#/components/schemas/AgreementPricing" }, "productName": { "type": "string", "description": "Name of the product or subscription." }, "providerData": { "$ref": "#/components/schemas/AgreementRequestProviderData" }, "customerNumber": { "type": "string", "description": "The customer number for the agreement." } }, "description": "Request to create a new payment agreement." }, "WebhookConfigurationEventPaths": { "title": "WebhookConfigurationEventPaths", "required": [ "event", "path" ], "type": "object", "properties": { "path": { "type": "string", "description": "The path a webhook event should be sent to.", "examples": [ "/credit" ] }, "event": { "type": "string", "description": "A webhook event. Possible values are: CREDIT.", "examples": [ "CREDIT" ] } }, "description": "The response returned when registering or updating a webhook configuration", "examples": [ { "path": "/credit", "event": "CREDIT" } ] }, "RegisterWalletTransactionRequest": { "title": "RegisterWalletTransactionRequest", "required": [ "paymentData", "walletProvider" ], "type": "object", "properties": { "paymentData": { "minLength": 1, "type": "string", "description": "Contains payment data that will be ECC encrypted. Client should send this as a JSON-string containing the data as described in https://developer.apple.com/documentation/passkit/payment-token-format-reference#Payment-token-format-reference .", "examples": [ "{data:{\"version\": \"EC_v1\",\"data\": \"CiAgQmFzZTY0IGVueWNyeXB0ZWQgY29udGVudCBvZiB0aGUgdG9rZW4gZGF0YS4uLg==\",\"signature\": \"MEUCIQDfKf9Zl...FAKE_SIGNATURE...b7Q==\",\"header\": {\"ephemeralPublicKey\": \"BCEFAKE_EPHEMERAL_PUBLIC_KEY_BASE64==\",\"publicKeyHash\": \"FAKE_PUBLIC_KEY_HASH_BASE64==\",\"transactionId\": \"6B1F2E3A-9C4D-4B1A-8F4C-1234567890AB\"}}" ] }, "redirectUrl": { "type": [ "string", "null" ], "description": "Points to where users should be redirected to for 3DS handling after registering payment, according to client. This is optional, and should only be used for GooglePay and if the transaction is being initiated from a web client, and not an app client.", "examples": [ "https://your-redirect-url.org/123123" ] }, "walletProvider": { "$ref": "#/components/schemas/WalletProvider" } }, "description": "Request body used to register a wallet transaction with an external payment provider.", "examples": [ { "paymentData": "{data:{\"version\": \"EC_v1\",\"data\": \"CiAgQmFzZTY0IGVueWNyeXB0ZWQgY29udGVudCBvZiB0aGUgdG9rZW4gZGF0YS4uLg==\",\"signature\": \"MEUCIQDfKf9Zl...FAKE_SIGNATURE...b7Q==\",\"header\": {\"ephemeralPublicKey\": \"BCEFAKE_EPHEMERAL_PUBLIC_KEY_BASE64==\",\"publicKeyHash\": \"FAKE_PUBLIC_KEY_HASH_BASE64==\",\"transactionId\": \"6B1F2E3A-9C4D-4B1A-8F4C-1234567890AB\"}}", "redirectUrl": "https://www.entur.org", "walletProvider": "APPLE_PAY" } ] }, "RegisterWalletTransactionResponse": { "title": "RegisterWalletTransactionResponse", "type": "object", "properties": { "paymentId": { "type": "integer", "description": "ID of the payment the transaction belongs to. Used with the transactionId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "terminalUri": { "type": [ "string", "null" ], "description": "Location of the payment terminal for handling 3DS. This will only be returned if the redirectUrl was provided in the request.", "examples": [ "https://epayment.nets.eu/epay/default.aspx?merchantId=700000&transactionId=8841532204d4426da913a5abfbg322f0" ] }, "transactionId": { "type": "integer", "description": "ID of the transaction this terminal belongs to. Used with the paymentId to later capture transaction.", "format": "int64", "examples": [ 1 ] }, "walletProvider": { "type": "string", "description": "Examples of providers are ApplePay and GooglePay. Both are supported.", "examples": [ "ApplePay" ] } }, "description": "Information about registered wallet-transaction.", "examples": [ { "paymentId": 1, "redirectUrl": "https://your-redirect-url.org/123123", "transactionId": 1, "walletProvider": "ApplePay" } ] }, "VippsAgreementRequestProviderData": { "description": "Vipps-specific data for creating a recurring agreement.", "allOf": [ { "$ref": "#/components/schemas/AgreementRequestProviderData" }, { "required": [ "merchantAgreementUrl", "merchantRedirectUrl" ], "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "The customer's phone number for Vipps push notification." }, "merchantRedirectUrl": { "type": "string", "description": "URL to redirect the customer to after they have accepted or rejected the agreement in Vipps.", "format": "uri" }, "merchantAgreementUrl": { "type": "string", "description": "URL where the customer can manage the agreement on the merchant's site.", "format": "uri" } } } ] }, "VippsAgreementResponseProviderData": { "description": "Vipps-specific data returned when an agreement is created.", "allOf": [ { "$ref": "#/components/schemas/AgreementResponseProviderData" }, { "required": [ "confirmationUrl" ], "type": "object", "properties": { "confirmationUrl": { "type": "string", "description": "URL to redirect the customer to for confirming the agreement in Vipps.", "format": "uri" } } } ] } }, "responses": { "conflict": { "description": "Conflict", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } }, "notFound": { "description": "Not Found", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } }, "badRequest": { "description": "Bad Request", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } }, "notImplemented": { "description": "Not Implemented", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } }, "internalServerError": { "description": "Internal Server Error", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } }, "conflictValidationError": { "description": "Conflict", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "serviceUnavailableError": { "description": "Service Unavailable Error", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } }, "badRequestValidationError": { "description": "Bad Request", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/PaymentError" } } } } }, "parameters": { "dciHeader": { "name": "Entur-Distribution-Channel", "in": "header", "description": "Distribution channel identifier.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, "posHeader": { "name": "Entur-POS", "in": "header", "description": "Point-of-sale identifier.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, "onBehalfOfHeader": { "name": "Entur-On-Behalf-Of", "in": "header", "description": "Identifier of the organisation on whose behalf the request is made. Use of this header requires a separate agreement before use.", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" } }, "creditIdPathParam": { "name": "creditId", "in": "path", "description": "creditId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, "paymentIdPathParam": { "name": "paymentId", "in": "path", "description": "paymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, "paginationPageParam": { "name": "page", "in": "query", "description": "Selects a specific page in the collection", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 1 } }, "agreementIdPathParam": { "name": "agreementId", "in": "path", "description": "agreementId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, "paginationPerPageParam": { "name": "perPage", "in": "query", "description": "Selects the number of elements per page", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 30 } }, "transactionIdPathParam": { "name": "transactionId", "in": "path", "description": "transactionId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, "webhookConfigurationId": { "name": "webhookConfigurationId", "in": "path", "description": "The id of a webhook", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, "recurringPaymentIdPathParam": { "name": "recurringPaymentId", "in": "path", "description": "recurringPaymentId", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, "ET-Client-Name": { "in": "header", "name": "ET-Client-Name", "description": "\nEntur Client Header.\nIt is required that all consumers identify themselves by using this header.\nEntur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.\nThe structure of ET-Client-Name should be: `-` for companies, and `-` for individuals.", "schema": { "type": "string" } }, "X-Correlation-Id": { "in": "header", "name": "X-Correlation-Id", "description": "Correlation id", "schema": { "type": "string" } } }, "securitySchemes": { "jwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }