# /paymentmethods/in3/v1/transactions/{transactionId} # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Payments Gateway", "description": "Common payments API", "version": "1.23.0" }, "security": [ { "oAuth2ClientCredentials": [] } ], "servers": [ { "url": "/api/v1/" } ], "paths": { "/paymentmethods/in3/v1/transactions/{transactionId}": { "get": { "tags": [ "in3" ], "operationId": "getIN3Transaction", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/IN3Transaction" }, "4XX": { "$ref": "#/components/responses/UserError" }, "5XX": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "schemas": { "ReturnUrl": { "oneOf": [ { "required": [ "returnUrls" ], "type": "object", "properties": { "returnUrls": { "type": "object", "required": [ "success", "cancelled", "expired", "failed" ], "properties": { "success": { "type": "string", "format": "url", "maxLength": 2000, "example": "https://yourdomain.tld/order/payment-success.html" }, "cancelled": { "type": "string", "format": "url", "maxLength": 2000, "example": "https://yourdomain.tld/order/payment-cancelled.html" }, "expired": { "type": "string", "format": "url", "maxLength": 2000, "example": "https://yourdomain.tld/order/payment-expired.html" }, "failed": { "type": "string", "format": "url", "maxLength": 2000, "example": "https://yourdomain.tld/order/payment-failed.html" } } } } }, { "required": [ "returnUrl" ], "type": "object", "properties": { "returnUrl": { "type": "string", "format": "url", "maxLength": 2000, "example": "https://yourdomain.tld/order/return?orderID=order123" } } } ] }, "Uuid": { "description": "Unique identifier", "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "8db1e7fa-ba8a-4189-92fd-67a20217443d" }, "Reference": { "description": "Identifier from client. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.", "type": "string", "minLength": 1, "maxLength": 255, "example": 20210623130413, "default": "" }, "Datetime": { "description": "ISO 8601 date and time", "type": "string", "format": "date-time", "minLength": 20, "example": "2006-01-02T15:04:05Z" }, "Amount": { "description": "Denomination in the smallest currency subunit, as for example eurocents.", "type": "integer", "minimum": 1, "maximum": 99999999, "example": 1200 }, "TransactionWebhookEvent": { "description": "* `FINALSTATUS` - When the status of the transaction becomes final; it is no longer `OPEN`.\n* `STATUS_CHANGE` - When the status of the transaction has any change.\n", "type": "string", "enum": [ "FINALSTATUS", "STATUS_CHANGE" ], "example": "FINALSTATUS" }, "TransactionWebhooks": { "description": "Webhooks enable receiving a web request once a given event occurs. \nWe won't do preventive rate-limiting in order to have the highest throughput possible. \nHowever, we will honor 429 (Too-many-requests) responses per callback. \nWe use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.\n", "type": "array", "items": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "description": "The URL the request must be send to.", "type": "string", "format": "url", "example": "https://yourdomain.tld/webhooks?purchaseId=order123" }, "events": { "description": "The events when this URL must be requested.", "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/TransactionWebhookEvent" } } } }, "example": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ] }, "Email": { "type": "string", "format": "email", "example": "john.doe@email.tld" }, "IN3Address": { "type": "object", "required": [ "street", "houseNumber", "postalCode", "city", "countryCode" ], "properties": { "addressedTo": { "type": "string", "maxLength": 250, "example": "Scenius", "nullable": true, "description": "The name or entity which shall accept the package/invoice" }, "street": { "type": "string", "maxLength": 128, "example": "Rustenburgerlaan" }, "houseNumber": { "type": "string", "maxLength": 25, "example": "25" }, "houseNumberSuffix": { "type": "string", "maxLength": 25, "example": "A", "nullable": true }, "postalCode": { "type": "string", "maxLength": 25, "example": "2012AL" }, "city": { "type": "string", "maxLength": 128, "example": "Haarlem" }, "countryCode": { "type": "string", "format": "ISO 3166-1 alpha-2", "example": "NL" }, "state": { "type": "string", "maxLength": 40, "example": "Noord-Holland", "nullable": true } } }, "IN3Consumer": { "type": "object", "required": [ "name", "email", "phone", "shippingAddress", "dateOfBirth" ], "properties": { "name": { "type": "object", "required": [ "lastName" ], "properties": { "initials": { "type": "string", "maxLength": 20, "example": "A" }, "lastName": { "maxLength": 250, "type": "string", "example": "Lopez" } } }, "phone": { "type": "string", "example": "+31695613259" }, "email": { "$ref": "#/components/schemas/Email" }, "dateOfBirth": { "type": "string", "example": "1996-12-31" }, "shippingAddress": { "$ref": "#/components/schemas/IN3Address" }, "invoiceAddress": { "$ref": "#/components/schemas/IN3Address" }, "business": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "maxLength": 35, "example": "CM" }, "cocNumber": { "type": "string", "maxLength": 20, "example": "70528500" } } } } }, "Digest": { "description": "Digest of whole message body", "type": "string", "example": "sha-256=OWM5MDc3ODYwNzdjYjE5NjU0Y2NjMDM4MzEyYzMxZTA5MTAzMDBjYWM1Y2I1ODM4NTdlMDU2MzhiMzE1ZDhjNw==", "externalDocs": { "description": "Instance Digests in HTTP", "url": "https://datatracker.ietf.org/doc/html/rfc3230" } }, "IN3Items": { "description": "Items included in the order. Required field for the following payment methods: in3.\nWe request both values 'vatAmount' and 'vatRate' to prevent errors.\n", "type": "array", "minItems": 1, "maxItems": 512, "items": { "type": "object", "required": [ "description", "code", "unitPrice", "quantity", "vatAmount", "vatRate" ], "properties": { "code": { "description": "A code that identifies the item. Each item code must be unique per transaction.", "type": "string", "minLength": 1, "maxLength": 50, "example": "SDC4/32GB-2ADP" }, "name": { "description": "A human readable name for the item.", "type": "string", "minLength": 1, "maxLength": 50, "example": "Kingston microSD 32GB" }, "description": { "description": "Additional item description.", "type": "string", "minLength": 1, "maxLength": 100, "example": "Best seller SD card" }, "unitPrice": { "description": "Unit price (including VAT) of the item, specified in the smallest currency subunit, as for example eurocents.", "type": "integer", "minimum": 1, "maximum": 99999999, "example": 600 }, "quantity": { "description": "The number of items of this type.", "type": "integer", "minimum": 1, "maximum": 1000000000, "example": 2 }, "vatAmount": { "description": "VAT amount of one unit, specified in the smallest currency subunit, as for example eurocents.", "type": "integer", "minimum": 1, "maximum": 99999999, "example": 100 }, "vatRate": { "description": "Percentage of VAT applied.\nOnly the first decimal value will be taken into account, the rest will be ignored.\n", "type": "number", "minimum": 0, "maximum": 99.9, "example": 20, "multipleOf": 0.1 } } } }, "TransactionStatus": { "description": "* `OPEN` - Payment has been created. This is the initial status.\n* `SUCCESS` - Payment has succeeded.\n* `CANCELLED` - Payment has not succeeded; cancelled by the consumer.\n* `EXPIRED` - Payment has not succeeded; expired.\n* `FAILURE` - Payment has not succeeded; unknown reason.\n* `AUTHORIZED` - Payment is authorized.\n* `PENDING` - Payment could not be completed yet; waiting for something.\n* `CHARGEBACK` - Payment chargeback was created.\n", "type": "string", "enum": [ "OPEN", "SUCCESS", "CANCELLED", "EXPIRED", "FAILURE", "AUTHORIZED", "PENDING", "CHARGEBACK" ], "example": "OPEN" } }, "responses": { "IN3Transaction": { "description": "IN3 transaction details", "headers": { "Digest": { "$ref": "#/components/headers/Digest" } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "id", "invoice", "reference", "amount", "consumer", "description", "expiresAt", "items", "status", "created", "updated", "action" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "invoice": { "type": "object", "required": [ "reference", "description", "amount" ], "properties": { "reference": { "$ref": "#/components/schemas/Reference" }, "amount": { "$ref": "#/components/schemas/Amount" }, "description": { "type": "string", "example": "Order at yourdomain.tld" } } }, "consumer": { "$ref": "#/components/schemas/IN3Consumer" }, "expiresAt": { "$ref": "#/components/schemas/Datetime" }, "items": { "$ref": "#/components/schemas/IN3Items" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "action": { "description": "Next action to be performed by merchant (or consumer) to complete the payment.", "type": "object", "nullable": true, "properties": { "redirect": { "type": "object", "properties": { "url": { "description": "URL where consumer should be redirected to by the merchant to perform the payment. This url is only available when a card payment has been started", "type": "string", "format": "url", "example": "https://checkout.tld/redirect/in3" } } } } }, "created": { "$ref": "#/components/schemas/Datetime" }, "updated": { "$ref": "#/components/schemas/Datetime" }, "webhooks": { "$ref": "#/components/schemas/TransactionWebhooks" } } }, { "$ref": "#/components/schemas/ReturnUrl" } ] } } } }, "InternalError": { "description": "Internal server error. This can be caused by an unresponsive backend", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "message" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "message": { "type": "string", "example": "Service Unavailable" } } } } } }, "UserError": { "description": "The user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized)", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "message" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "message": { "type": "string", "example": "no authorization methods provided" } } } } } } }, "headers": { "Digest": { "description": "Digest of whole message body", "schema": { "$ref": "#/components/schemas/Digest" } } }, "securitySchemes": { "oAuth2ClientCredentials": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "/api/v1/authorization/oauth2/token", "scopes": {} } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 103, "1": 234, "2": 76, "3": 191, "4": 145, "5": 198, "6": 48, "7": 79, "8": 46, "9": 249, "10": 185, "11": 249 } } } ```