OpenAPI 3.0 REST API for online / e-commerce card payments. Issues access-tokens, processes and resumes payments, runs cross-reference (repeat) payments, and lists supported payment methods against the Connect-E host (e..connect.paymentsense.cloud).
{
"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
}
}
}
}
}
}