{
  "openapi": "3.0.0",
  "info": {
    "description": "Javascript client to remove the PCI burden when taking payments online",
    "title": "Connect-E Development Environment",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/access-tokens": {
      "post": {
        "description": "Create a one time use access token to make a payment.",
        "tags": [
          "Access Token"
        ],
        "operationId": "/v1/access-tokens",
        "responses": {
          "200": {
            "description": "Access Token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/accessToken"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - The request has failed validation by our servers."
          },
          "401": {
            "description": "Unauthorized - There is an issue authenticating the request."
          },
          "500": {
            "description": "Internal Server Error - An error has occured while processing the request."
          }
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/accessTokenRequest"
        },
        "security": [
          {
            "jwt": []
          }
        ]
      }
    },
    "/v1/payments/{access-token}": {
      "get": {
        "description": "Get details of the payment with this access token",
        "tags": [
          "Payment Details"
        ],
        "operationId": "/v1/payments/",
        "parameters": [
          {
            "description": "Id returned from creating the access token associated with the payment",
            "in": "path",
            "name": "access-token",
            "required": true,
            "example": "WEV2IGFzt-yOb1bAQFv5gByq38zz1OdMdyvIXHHJdn7CRzBrdd9VZJNdwhAKMW0b-ar6KDJMFivr6NlKiimxljV6kXDC2pCAVoJT6SoEP5GzrmwvPg6EIe7FKE2Bn83HHkd8S4pxSrksSCl6cg==",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment Info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/paymentInfo"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - The request has failed validation by our servers."
          },
          "401": {
            "description": "Unauthorized - There is an issue authenticating the request."
          },
          "404": {
            "description": "Not Found - Unable to find a payment with this access-token."
          },
          "500": {
            "description": "Internal Server Error - An error has occured while processing the request."
          }
        },
        "security": [
          {
            "jwt": []
          }
        ]
      }
    },
    "/v1/payments/{access-token}/resume": {
      "post": {
        "description": "Resume a paused wait pre-execute transaction using the id.",
        "tags": [
          "Resume Payment"
        ],
        "operationId": "/v1/payments/resume",
        "responses": {
          "200": {
            "description": "Resume Payment Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/resumePaymentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - The request has failed validation by our servers."
          },
          "401": {
            "description": "Unauthorized - There is an issue authenticating the request."
          },
          "500": {
            "description": "Internal Server Error - An error has occured while processing the request."
          }
        },
        "parameters": [
          {
            "description": "Id returned from create access token for the payment",
            "in": "path",
            "name": "access-token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "jwt": []
          }
        ]
      }
    },
    "/v1/cross-reference-payments/{access-token}": {
      "post": {
        "description": "Execute a transaction using the cross reference from a previous transaction. To execute this request, pass the id from creating an access token as {access-token} in the path. This token can only be used once.",
        "tags": [
          "Cross Reference Payment"
        ],
        "operationId": "/v1/cross-reference-payments/access-token",
        "responses": {
          "200": {
            "description": "Payment Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/crossReferenceResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - The request has failed validation by our servers."
          },
          "401": {
            "description": "Unauthorized - There is an issue authenticating the request."
          },
          "500": {
            "description": "Internal Server Error - An error has occured while processing the request."
          }
        },
        "parameters": [
          {
            "description": "Id returned from creating an access-token for the payment",
            "in": "path",
            "name": "access-token",
            "required": true,
            "example": "WEV2IGFzt-yOb1bAQFv5gByq38zz1OdMdyvIXHHJdn7CRzBrdd9VZJNdwhAKMW0b-ar6KDJMFivr6NlKiimxljV6kXDC2pCAVoJT6SoEP5GzrmwvPg6EIe7FKE2Bn83HHkd8S4pxSrksSCl6cg==",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/paymentCrossReferenceRequest"
        },
        "security": [
          {
            "jwt": []
          }
        ]
      }
    },
    "/v1/access-tokens/{access-token}/revoke": {
      "post": {
        "tags": ["Revoke Access Token"],
        "description": "Revoke an access token",
        "responses": {
          "200": {
            "description": "Access token successfully revoked"
          },
          "400": {
            "description": "Access token either does not exist or has already been consumed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "enum": ["Invalid access token", "unable to revoke access token with transaction in [state] state"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - There is an issue authenticating the request."
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "parameters": [
          {
            "description": "Access token associated with the payment",
            "in": "path",
            "name": "access-token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/payment-methods": {
      "get" : {
        "description": "Get supported payment methods for authenticated merchant.",
        "tags": ["Payment Methods"],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/paymentMethods"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://e.test.connect.paymentsense.cloud"
    }
  ],
  "components": {
    "requestBodies": {
      "accessTokenRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/accessTokenRequest"
            }
          }
        },
        "description": "Details of the Payment to be made",
        "required": true
      },
      "paymentCrossReferenceRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/paymentCrossReferenceRequest"
            }
          }
        },
        "description": "Details of the Payment to be made",
        "required": true
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      },
      "access_token": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "This authorization is deprecated and only used on the POST /v1/cross-reference-payments endpoint. Please only use the api_key for new integrations."
      },
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "paymentMethods": {
        "type": "object",
        "properties": {
          "cardSchemes": {
            "description": "List of card schemes supported for this merchant. Supported values are <code>VISA</code>, <code>MASTERCARD</code>, <code>MAESTRO</code>, <code>AMEX</code>, <code>DCI</code>, <code>DISCOVER</code>.",
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": ["VISA", "MASTERCARD", "MAESTRO", "AMEX"]
          },
          "wallets":{
            "description": "List of payment wallets supported for this merchant. Supported values are <code>APPLE_PAY</code>, <code>GOOGLE_PAY</code>.",
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": ["APPLE_PAY", "GOOGLE_PAY"]
          }
        }
      },
      "resumePaymentResponse": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "enum": [
              0,
              4,
              5,
              20,
              30
            ],
            "example": 0,
            "description": "* `0` - Successful\n* `4` - Referred\n* `5` - Declined\n* `20` - Duplicate Transaction\n* `30` - Failed\n\n More details <a href='/ConnectE/Standard#statusCode'>here</a>"
          },
          "authCode": {
            "type": "string",
            "example": "866344"
          },
          "message": {
            "type": "string",
            "example": "AuthCode: 898968"
          }
        }
      },
      "crossReferenceResponse": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "enum": [
              0,
              4,
              5,
              20,
              30
            ],
            "example": 0,
            "description": "* `0` - Successful\n* `4` - Referred\n* `5` - Declined\n* `20` - Duplicate Transaction\n* `30` - Failed\n\n More details <a href='/ConnectE/Standard#statusCode'>here</a>"
          },
          "authCode": {
            "type": "string",
            "example": "866344"
          },
          "message": {
            "type": "string",
            "example": "AuthCode: 898968"
          }
        }
      },
      "paymentCrossReferenceRequest": {
        "type": "object",
        "properties": {
          "crossReference": {
            "type": "string",
            "example": "181025085937854101886353"
          },
          "cv2": {
            "type": "string",
            "description": "The CV2 code associated with the card from the original transaction. Note that if using this you need to be PCI SAQ-D compliant",
            "example": "123"
          }
        },
        "required": [
          "crossReference"
        ]
      },
      "paymentInfo": {
        "type": "object",
        "properties": {
          "transactionDateTime": {
            "type": "string",
            "description": "ISO 8601 datetime including offset",
            "example": "2019-07-16 07:39:29 +0000 UTC"
          },
          "statusCode": {
            "type": "integer",
            "example": 0,
            "enum": [
              0,
              3,
              4,
              5,
              20,
              30,
              40,
              90,
              99
            ],
            "description": "* `0` - Successful\n* `3` - Authorizing\n* `4` - Referred\n* `5` - Declined\n* `20` - Duplicate Transaction\n* `30` - Failed\n* `40` - Processing\n* `90` - Revoked\n* `99` - Waiting pre-execute\n\n More details <a href='/ConnectE/Standard#statusCode'>here</a>"
          },
          "message": {
            "type": "string",
            "example": "AuthCode: 898968"
          },
          "crossReference": {
            "type": "string",
            "example": "181025085937854101886353",
            "description": "Code to be passed to /v1/cross-reference-payments, this code does not have an expiry date."
          },
          "authCode": {
            "type": "string",
            "example": "866344"
          },
          "cardNumber": {
            "type": "string",
            "example": "411111*****1111",
            "description": "Masked card number used in the transaction."
          },
          "cardName": {
            "type": "string",
            "example": "John Smith",
            "description": "Card name used in the transaction."
          },
          "expiryDate": {
            "type": "string",
            "example": "11/20",
            "description": "Expiry date used in the transaction."
          },
          "cardType": {
            "type": "string",
            "example": "VISA",
            "description": "Card type used in the transaction."
          },
          "billingAddress": {
            "$ref": "#/components/schemas/address"
          },
          "shippingDetails": {
            "$ref": "#/components/schemas/shippingDetails"
          },
          "userEmailAddress": {
            "type": "string",
            "example": "john.smith@example.com",
            "description": "User email associated with this transaction"
          },
          "metaData": {
            "type": "object",
            "description": "String key value pairs passed when creating the access token.",
            "additionalProperties": {
              "example": {
                "item": "t-shirt",
                "tax": "123.00"
              },
              "type": "string"
            }
          }
        }
      },
      "shippingDetails": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "address": {
            "$ref": "#/components/schemas/address"
          }
        }
      },
      "address": {
        "type": "object",
        "properties": {
          "address1": {
            "type": "string",
            "example": "1 Test Street",
            "description": "Line 1 of the address."
          },
          "address2": {
            "type": "string",
            "description": "Line 2 of the address."
          },
          "address3": {
            "type": "string",
            "description": "Line 3 of the address."
          },
          "address4": {
            "type": "string",
            "description": "Line 4 of the address."
          },
          "city": {
            "type": "string",
            "example": "London",
            "description": "City of the address."
          },
          "state": {
            "type": "string",
            "example": "Greater London",
            "description": "State of the address."
          },
          "postcode": {
            "type": "string",
            "example": "TR14 8PA",
            "description": "postcode of the address."
          },
          "countryCode": {
            "type": "string",
            "example": "826",
            "description": "CountryCode of the address."
          }
        }
      },
      "accessTokenRequest": {
        "type": "object",
        "properties": {
          "merchantUrl": {
            "type": "string",
            "example": "MERCHANT_URL",
            "description": "The URL of the merchant's website used ensure the correct JWT is used. This needs to match what it provided when setting up an account"
          },
          "currencyCode": {
            "type": "string",
            "pattern": "^\\d\\d\\d$",
            "description": "The three digit ISO- 4217 currency code for the currency. eg 826 for the United Kingdom",
            "example": "826"
          },
          "amount": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "The amount in the minor unit e.g. '100' for 1.00 GBP",
            "example": "100"
          },
          "transactionType": {
            "type": "string",
            "enum": [
              "SALE",
              "REFUND",
              "PREAUTH",
              "COLLECTION",
              "REFUND",
              "VOID"
            ],
            "pattern": "^(SALE)|(REFUND)|(PREAUTH)|(COLLECTION)|(REFUND)|(VOID)$",
            "description": "The type of transaction to be processed. If making a web payment only <code>SALE</code> and <code>PREAUTH</code> are supported. If making a cross reference payment only <code>COLLECTION</code>, <code>REFUND</code>, <code>VOID</code>, <code>PREAUTH</code> or <code>SALE</code> are supported",
            "example": "SALE"
          },
          "transactionSource": {
            "type": "string",
            "enum": [
              "MOTO",
              ""
            ],
            "pattern": "^(MOTO)|()$",
            "example": "",
            "description": "Specify if the source of the transaction is <code>MOTO</code> (via mail or over the phone)"
          },
          "orderId": {
            "type": "string",
            "description": "A merchant side ID for the order",
            "example": "ORD00001"
          },
          "merchantTransactionId": {
            "type": "string",
            "description": "Merchant generated transaction ID to uniquely identify the transaction. If included must be unique for each access token.",
            "example": "09f3fe11-b3fd-4866-b759-5b4ddee63c85"
          },
          "orderDescription": {
            "type": "string",
            "example": "Example description."
          },
          "userAgent": {
            "type": "string",
            "description": "Not supported for cross reference transactions."
          },
          "userEmailAddress": {
            "type": "string",
            "format": "email",
            "example": "user@exmaple.com",
            "description": "Not supported for cross reference transactions."
          },
          "userPhoneNumber": {
            "type": "string",
            "example": "55512345",
            "description": "Not supported for cross reference transactions."
          },
          "userIpAddress": {
            "type": "string",
            "example": "192.168.0.0.1",
            "description": "Not supported for cross reference transactions."
          },
          "userAddress1": {
            "type": "string",
            "example": "1 Example st",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userAddress2": {
            "type": "string",
            "example": "Angel",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userAddress3": {
            "type": "string",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userAddress4": {
            "type": "string",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userCity": {
            "type": "string",
            "example": "London",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userState": {
            "type": "string",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userPostcode": {
            "type": "string",
            "example": "N19PS",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "userCountryCode": {
            "type": "string",
            "pattern": "^(\\d\\d\\d)|()$",
            "example": "826",
            "description": "If any address field is provided for a cross reference transaction all address fields will be overridden."
          },
          "shippingDetails": {
            "$ref": "#/components/schemas/shippingDetails"
          },
          "newTransaction": {
            "type": "boolean",
            "example": false,
            "description": "Treat the transaction as a new transaction. Default is false and is only supported by cross reference transactions."
          },
          "crossReference": {
            "type": "string",
            "example": "1234567890ABC",
            "description": "The cross reference from a previous transaction to be used with customer present recurring transactions."
          },
          "webHookUrl": {
            "type": "string",
            "example": "https://www.example.com/order/1234/webhook",
            "description": "Url to be called once the transaction is complete."
          },
          "metaData": {
            "type": "object",
            "description": "String key value pairs to associate with the transaction. Will be passed back on the Payment Details API. Not used in processing.",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "item": "t-shirt",
              "tax": "123.00"
            }
          },
          "waitPreExecute": {
            "type": "boolean",
            "example": true,
            "description": "Pause the transaction before the payment is executed, after any payer authentication (such as 3DS) has been completed."
          },
          "customerId": {
            "type": "string",
            "example": "cust_test",
            "description": "Customer Id used to enable save payment method feature."
          }
        },
        "required": [
          "currencyCode",
          "transactionType",
          "amount",
          "orderId",
          "merchantUrl"
        ]
      },
      "accessToken": {
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true,
            "description": "Id to track the payment.",
            "example": "5f1tYtm-I5X_fB4lxkD7vQqtHGCykdguffB9GWySCr73qtAnz-g_3KQqxxAQVUyViMgmGbplcYVraRnYz7ro_5PkbD64WIalEgY788Q1yNbYTIIXmD6t"
          },
          "expiresAt": {
            "type": "integer",
            "readOnly": true,
            "description": "UTC timestamp when this token will expire (Number of seconds since Jan 01 1970. (UTC))",
            "example": 1540457361
          }
        }
      }
    }
  }
}