680 lines
25 KiB
JSON
680 lines
25 KiB
JSON
{
|
|
"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 <token>\"` 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"
|
|
}
|
|
}
|
|
}
|
|
} |