{ "swagger": "2.0", "info": { "version": "1.4", "title": "Comcarde Bridge Integration API Definition", "description": "The REST Integration API that allows a subset of system functions to be driven by third party systems. Please contact Comcard for more details and access to the system." }, "basePath": "/int/v1", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "security": [ { "bearer": [] } ], "tags": [ { "name": "general", "description": "Functions in the API" }, { "name": "payment", "description": "Functions related to taking payment in various manners" } ], "securityDefinitions": { "bearer": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Bearer token for the specific integration partner. The bearer token **MUST** be kept secure as it provides access to the controlled functionality. The token should be sent in the `\"Authorization\"` header as `\"Bearer \"` following https://tools.ietf.org/html/rfc6750#section-2.1[Section 2.1 of RFC 6750]. Contact Comcarde to request a token for use with this API." } }, "responses": { "GeneralError": { "description": "General error response format", "schema": { "$ref": "#/definitions/ErrorInfo" } } }, "paths": { "/test": { "x-swagger-router-controller": "test_controller", "get": { "summary": "Test function", "description": "Tests that communication with the API works, and the supplied bearer token is valid", "tags": [ "general" ], "operationId": "test", "responses": { "default": { "$ref": "#/responses/GeneralError" }, "200": { "description": "Successful request: bearer token is valid", "schema": {} }, "401": { "description": "Invalid token", "schema": { "$ref": "#/definitions/ErrorInfo" } } } } }, "/clients": { "x-swagger-router-controller": "clients_controller", "post": { "summary": "Add a new client", "description": "Adds a new client to the system, validating their identity", "tags": [ "general" ], "operationId": "addClient", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/addClientBody" } } ], "responses": { "default": { "$ref": "#/responses/GeneralError" }, "200": { "description": "Successful request. Calls to send payment details can now be sent, using the email address as an identifier.", "schema": { "type":"object", "description": "TransactionID for the successful transaction", "properties": { "TransactionID": { "$ref": "#/definitions/uuid" } } } } } } }, "/payments": { "x-swagger-router-controller": "payments_controller", "post": { "summary": "Take a credit/debit card payment", "description": "Takes a credit or debit card payment from a client that has previously been added to the system.", "tags": [ "payment" ], "operationId": "takePayment", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/takeCardPaymentBody" } } ], "responses": { "default": { "$ref": "#/responses/GeneralError" }, "200": { "description": "Payment complete.", "schema": {} } } } }, "/payments/paycode": { "x-swagger-router-controller": "payments_controller", "post": { "summary": "Redeem a Bridge paycode payment", "description": "Redeems a Bridge paycode and progresses the payment process. Poll GET /transactions/{TransactionID}/status to wait for the customer to confirm.", "tags": [ "payment" ], "operationId": "redeemPaycode", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/redeemPaycodeBody" } } ], "responses": { "default": { "$ref": "#/responses/GeneralError" }, "202": { "description": "Paycode redeemed, and awaiting customer confirmation.", "schema": { "$ref": "#/definitions/redeemPaycodeResponse" } } } } }, "/transactions/{TransactionID}/status": { "x-swagger-router-controller": "payments_controller", "get": { "summary": "Checks the status of the transaction", "description": "Poll at most 1/s to wait for the customer to confirm the transaction.", "tags": [ "payment" ], "operationId": "getTransactionUpdate", "parameters": [ { "$ref": "#/parameters/TransactionID" } ], "responses": { "default": { "$ref": "#/responses/GeneralError" }, "200": { "description": "Transactions completed successfully.", "schema": { "$ref": "#/definitions/paycodeTransactionCompleteResponse" } }, "202": { "description": "Still waiting for customer to confirm the transaction.", "schema": {} }, "404": { "description": "Transaction can't be found or isn't associated with this merchant", "schema": { "$ref": "#/responses/GeneralError" } }, "409": { "description": "Transaction has been refunded.", "schema": { "$ref": "#/responses/GeneralError" } }, "410": { "description": "Transaction failed or cancelled by customer.", "schema": { "$ref": "#/responses/GeneralError" } } } } } }, "parameters": { "TransactionID": { "name": "TransactionID", "description": "TransactionID as returned from POST /payments/paycode etc.", "in": "path", "required": true, "type": "string", "pattern": "^([a-f0-9]{24})$", "minLength": 24, "maxLength": 24 } }, "definitions": { "alphaSpace": { "description": "Text with only ASCII letters and space", "type": "string", "pattern": "^([A-Za-z ]*)$", "x-invalid-pattern": "[^A-Za-z ]", "example": "Some Text With Only Ascii Letters plus space" }, "email": { "title": "Email address", "description": "Email address with simplified rules for correctness.", "type": "string", "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", "x-invalid-pattern": "[^a-zA-Z0-9.%+-.@]", "minLength": 7, "maxLength": 254, "example": "janedoe@example.com" }, "cardDate": { "title": "Date on a credit/debit card", "description": "The date on a credit or debit card in MM-YY format", "type": "string", "pattern": "^(?:0[1-9]|1[0-2])-[0-9][0-9]$", "example": "01-70" }, "generalTextSpace": { "description": "General text format + special chars + space", "type": "string", "pattern": "^([A-Za-z0-9'[\\]()@?!\\-/.,_&*:;+= ]*)$", "x-invalid-pattern": "[^a-zA-Z0-9'[\\]()@?!\\-/.,_&*:;+= ]", "example": "Some Text With Spaces plus '&', '*', etc." }, "kycGender": { "description": "The gender as required by the ID verification/AML service.", "type": "string", "enum": [ "M", "F" ], "example": "F" }, "paycodeString": { "description": "Paycode string. 0-9 + A-Z except IOQ which could be confusing", "type": "string", "pattern": "^([0-9ABCDEFGHJKLMNPRSTUVWXYZ]*)$", "minLength": 5, "maxLength": 12, "x-invalid-pattern": "[^0-9ABCDEFGHJKLMNPRSTUVWXYZ]", "example": "A1A1A" }, "phoneNumber": { "description": "UK phone number", "type": "string", "pattern": "^\\+[0-9]*$", "x-invalid-pattern": "[^0-9+]", "minLength": 8, "maxLength": 35, "example": "+447700900000" }, "postcode": { "description": "A UK postcode", "type": "string", "pattern": "^[A-Z]{1,2}\\d{1,2}[A-Z]? ?\\d[A-Z]{2}$", "example": "EH54 7GA" }, "uuid": { "description": "ID of another item in the system", "type": "string", "pattern": "^([a-f0-9]{24})$", "x-invalid-pattern": "[^a-f0-9]", "minLength": 24, "maxLength": 24, "example": "12a345b67c8901234d567e89" }, "addClientBody": { "type":"object", "description": "Parameters required to add a client to the system", "properties": { "email": { "$ref": "#/definitions/email", "example": "johndoe@example.com" }, "kyc": { "$ref": "#/definitions/kyc" } }, "required": [ "email", "kyc" ] }, "takeCardPaymentBody": { "type": "object", "description": "Parameters required to take a card payment.", "properties": { "merchantAccount": { "description": "The ID for the merchant account you want the card to pay into", "$ref": "#/definitions/uuid" }, "amount": { "description": "The amount of the payment IN PENCE. i.e. £123.45 would be sent as `12345`.", "type": "integer", "minimum": 1 }, "email": { "description": "The customer's email address (as added previously). This MUST be a client that was added by the same integration, and will not process a payment for any other clients.", "$ref": "#/definitions/email", "example": "johndoe@example.com" }, "cardDetails": { "description": "The details for the credit or debit card for the transaction.", "$ref": "#/definitions/cardDetails" } }, "required": [ "merchantAccount", "amount", "email", "cardDetails" ] }, "redeemPaycodeBody": { "type": "object", "description": "Parameters required to take a payment using a Bridge paycode.", "properties": { "merchantAccount": { "description": "The ID for the merchant account you want to pay into", "$ref": "#/definitions/uuid" }, "amount": { "description": "The amount of the payment IN PENCE. i.e. £123.45 would be sent as `12345`.", "type": "integer", "minimum": 1 }, "paycode": { "description": "The paycode to redeem.", "$ref": "#/definitions/paycodeString" } }, "required": [ "merchantAccount", "amount", "paycode" ] }, "redeemPaycodeResponse": { "type": "object", "description": "Response to the request to redeem a paycode. Contains the TransactionID needed to poll for status updates", "properties": { "TransactionID": { "description": "The ID for the transaction that is pending customer confirmation", "$ref": "#/definitions/uuid" } }, "required": [ "TransactionID" ] }, "paycodeTransactionCompleteResponse": { "type": "object", "description": "Transaction has completed successfully.", "properties": { "CustomerDisplayName": { "description": "The display name of the customer", "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 2, "maxLength": 101 } ] }, "CustomerSubDisplayName": { "description": "The sub-display name of the customer", "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 2, "maxLength": 101 } ] }, "TotalAmount": { "description": "The amount of the payment IN PENCE. i.e. £123.45 would be sent as `12345`.", "type": "integer", "minimum": 0 } }, "required": [ "CustomerDisplayName", "TotalAmount" ] }, "kyc": { "type": "object", "description": "Know Your Customer (KYC) data", "properties": { "Title": { "description": "Client's title (Mr, Mrs, Ms, Dr, etc.", "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 2, "maxLength": 20 } ], "example": "Mr" }, "FirstName": { "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 2, "maxLength": 50 } ], "example": "John" }, "LastName": { "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 2, "maxLength": 50 } ], "example": "Doe" }, "MiddleNames": { "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 0, "maxLength": 50 } ] }, "DateOfBirth": { "description": "Date of birth as an ISO8601 full-date (YYYY-MM-DD)", "type": "string", "format": "date", "example": "1970-01-01" }, "ResidentialAddress": { "$ref": "#/definitions/address", "description": "The customer's residential address. The accuracy of the address format is critical to succesful due diligence of the customer and SHOULD be filled out from a postcode-driven address lookup service or similar for best results." }, "Gender": { "$ref": "#/definitions/kycGender", "example": "M" } }, "required": [ "Title", "FirstName", "LastName", "DateOfBirth", "ResidentialAddress", "Gender" ] }, "address": { "type": "object", "description": "A UK address", "properties": { "BuildingNameFlat": { "description": "Building name or flat number", "allOf": [ { "$ref": "#/definitions/generalTextSpace" }, { "minLength": 1, "maxLength": 64 } ], "example": "Flat 20" }, "Address1": { "description": "First line of address", "allOf": [ { "$ref": "#/definitions/generalTextSpace" }, { "minLength": 4, "maxLength": 64 } ], "example": "Victoria House" }, "Address2": { "description": "Second line of address", "allOf": [ { "$ref": "#/definitions/generalTextSpace" }, { "minLength": 4, "maxLength": 64 } ], "example": "15 The Street" }, "Town": { "description": "Postal Town", "allOf": [ { "$ref": "#/definitions/generalTextSpace" }, { "minLength": 3, "maxLength": 32 } ], "example": "Christchurch" }, "PostCode": { "description": "Post code", "allOf": [ { "$ref": "#/definitions/postcode" }, { "minLength": 3, "maxLength": 32 } ], "example": "BH23 6AA" }, "Country": { "description": "Country. Only open to UK residents at present", "type": "string", "enum": [ "United Kingdom" ], "example": "United Kingdom" }, "PhoneNumber": { "description": "A contact phone number at this address; ideally a land line", "allOf": [ { "$ref": "#/definitions/phoneNumber" }, { "minLength": 8, "maxLength": 35 } ], "example": "+441214960711" } }, "required": [ "Address1", "Town", "PostCode", "Country", "PhoneNumber" ] }, "cardDetails": { "description": "Card details neccessary to process a payment", "type":"object", "properties": { "NameOnAccount": { "description": "The name on the customer's account", "allOf": [ { "$ref": "#/definitions/alphaSpace" }, { "minLength": 5, "maxLength": 64 } ], "example": "John Doe" }, "CardPAN": { "description": "The long number on the front of the card (with all spaces removed).", "type": "string", "minLength": 8, "maxLength": 19, "pattern": "^[0-9]*$", "example": "1234567890123456" }, "CardCVV": { "description": "The CVV/CVC/CV2 number. Usually found on the back of the card", "type": "string", "pattern": "^[0-9]{3,4}$", "example": "123" }, "ExpiryDate": { "$ref": "#/definitions/cardDate", "example": "01-70" }, "StartDate": { "$ref": "#/definitions/cardDate", "example": "01-70" }, "IssueNumber": { "description": "Issue number on the card. Only applies to some debit cards", "type": "integer", "minimum": 0, "example": 1 }, "BillingAddress": { "description": "The billing address to use for the card, if the billing address does not match the residential address", "$ref": "#/definitions/address" } }, "required": [ "NameOnAccount", "CardPAN", "CardCVV", "ExpiryDate", "BillingAddress" ] }, "ErrorInfo": { "description": "More information on the error reason", "type": "object", "properties": { "code": { "description": "Error code", "type": "integer", "example": -1 }, "info": { "description": "Text description of the issue", "type": "string", "example": "Unknown Error" } }, "example": { "code": "1", "description": "Some error" } } } }