{ "swagger": "2.0", "info": { "version": "0.4.1", "title": "Web Dashboard API" }, "basePath": "/api/v0", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "security": [ { "bridge_session": [ ] }, { "device_session": [ ] } ], "tags": [ { "name": "login", "description": "Management of login, and logout" }, { "name": "users", "description": "User registration, details and information" }, { "name": "transactions", "description": "Transaction information" }, { "name": "accounts", "description": "Client accounts" }, { "name": "merchant", "description": "Merchant related functions" }, { "name": "devices", "description": "Mobile devices using the payment app" }, { "name": "utils", "description": "General requests to support clients etc." } ], "paths": { "/login": { "x-swagger-router-controller": "api_login_controller", "post": { "tags": [ "login" ], "summary": "Login", "description": "Username & password log in to a new session. On succesfull login, the server replies with 200 OK, a `Secure, HttpOnly` session cookie, and an XSRF token for this session in the body. From then on the client should include in any request:\n* the session cookie (generally using XHR with the `withCredentials` flag), and\n* a custom header - `X-XSRF-TOKEN` - that reflects the XSRF token back to the server.\n", "operationId": "login", "security": [ ], "parameters": [ { "name": "body", "in": "body", "description": "Credentials", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/LoginBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/LoginSuccess" }, "401": { "description": "Email or password didn't match. Please try again", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "403": { "description": "User is barred. Contact provider for help.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/poll2FA": { "x-swagger-router-controller": "api_login_controller", "post": { "tags": [ "login" ], "summary": "Polls the 2FA status", "description": "Polls the 2FA status to check if the 2-factor request has been authorised (or timed out). 2FA can only be authorised by the apps.", "operationId": "poll2FA", "security": [ { "awaiting_2fa_bridge_session": [ ] } ], "parameters": [], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/LoginSuccess" }, "202": { "description": "2-factor request is still pending" }, "408": { "description": "2-factor request is invalid, has timed out or been rejected. Must start again from /login." } } } }, "/logout": { "x-swagger-router-controller": "api_login_controller", "post": { "tags": [ "login" ], "operationId": "logout", "summary": "Logout", "security": [ { "awaiting_accept_eula_bridge_session": [] } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/LogoutSuccess" } } } }, "/login/elevate": { "x-swagger-router-controller": "api_login_controller", "post": { "tags": [ "login" ], "summary": "Elevate standard session", "description": "Elevates the existing session to allow the user to make more significant changes (which can't be done from a standard session). All session cookies and tokens are refreshed by the elevation for more security.", "operationId": "elevate", "parameters": [], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/ElevationSuccess" }, "202": { "$ref": "api_responses.json#/responses/Await2FA" }, "401": { "description": "Email or password didn't match. Please try again", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "Client doesn't have any active devices that can process the required 2FA request. Add a new device, or contact the service provider.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/login/demote": { "x-swagger-router-controller": "api_login_controller", "post": { "tags": [ "login" ], "summary": "Demote elevated session", "description": "Demotes the existing session back to the standard level that doesn't allow significant changes. All session cookies and tokens are refreshed for more security.", "operationId": "demote", "security": [ { "elevated_bridge_session": [ ] } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/DemotionSuccess" } } } }, "/login/accept-eula": { "x-swagger-router-controller": "api_login_controller", "post": { "tags": [ "login" ], "summary": "Accept EULA version", "description": "Reports client acceptance of the EULA version specified", "operationId": "acceptEULA", "security": [ { "awaiting_accept_eula_bridge_session": [] } ], "parameters": [ { "name": "body", "in": "body", "description": "Accepted EULA version", "required": true, "schema": { "type": "object", "properties": { "acceptedVersion": { "$ref": "api_definitions.json#/definitions/version" } } } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/LoginSuccess" } } } }, "/keepalive": { "x-swagger-router-controller": "api_login_controller", "get": { "tags":[ "login" ], "operationId": "keepAlive", "summary": "Extend the session duration", "description": "Extends the lifetime of the session (assuming the session is currently valid. Does nothing else", "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful" } } } }, "/recovery": { "x-swagger-router-controller": "api_recovery_controller", "post": { "tags": [ "login" ], "summary": "Start account recovery", "description": "Starts account recovery for the specified email address. This will create a session in which all further steps must be completed.", "operationId": "startRecovery", "security": [], "parameters": [ { "name": "body", "in": "body", "description": "Email address of the account to recover", "required": true, "schema": { "type":"object", "properties": { "email": { "$ref": "api_definitions.json#/definitions/email" } } } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/RecoverySuccess" }, "202": { "$ref": "api_responses.json#/responses/RecoverySuccess" }, "429": { "description": "Too many requests in too short a time. Please wait and try again", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/recovery/emailpw": { "x-swagger-router-controller": "api_recovery_controller", "post": { "tags": [ "login" ], "summary": "Reset the password to recover the account", "description": "Confirms the email token and resets the password", "operationId": "completeRecoveryEmailPw", "security": [{ "recovery_session": [] }], "parameters": [ { "name": "body", "in": "body", "description": "Recovery details", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/RecoveryTokenPwBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Recovery completed succcessfully. Login with the new credentials." } } } }, "/recovery/email": { "x-swagger-router-controller": "api_recovery_controller", "post": { "tags": [ "login" ], "summary": "Comfirm email address", "description": "Confirms the email address using the token sent to that address. Receives a variable-length list of KBA questions to ask in response", "operationId": "confirmRecoveryEmail", "security": [ { "recovery_session": [] } ], "parameters": [ { "name": "body", "in": "body", "description": "Recovery details", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/RecoveryTokenBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "202": { "description": "Email validation successfull. Respond to questions to continue.", "schema": { "type": "object", "properties": { "Questions": { "description": "Array of questions to ask the user.", "type": "array", "items": { "$ref": "api_definitions.json#/definitions/question" } } } } } } } }, "/recovery/answers": { "x-swagger-router-controller": "api_recovery_controller", "post": { "tags": [ "login" ], "summary": "Presents answers to the requested questions", "description": "Gives answers to the requested questions + provide a registered device number", "operationId": "confirmAnswers", "security": [ { "recovery_session": [] } ], "parameters": [ { "name": "body", "in": "body", "description": "Answers to the questions", "required": true, "schema": { "type": "object", "properties": { "Answers": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/answer" } }, "DeviceNumber":{ "$ref": "api_definitions.json#/definitions/phoneNumber" } } } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Answers accepted, and recovery token sent to device by SMS." } } } }, "/recovery/devicepw": { "x-swagger-router-controller": "api_recovery_controller", "post": { "tags": [ "login" ], "summary": "Reset the password to recover the account", "description": "Confirms the device token and resets the password", "operationId": "completeRecoveryDevicePw", "security": [ { "recovery_session": [] } ], "parameters": [ { "name": "body", "in": "body", "description": "Recovery details", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/RecoveryTokenPwBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Recovery completed succcessfully. Login with the new credentials." } } } }, "/utils/version": { "x-swagger-router-controller": "api_utils_controller", "get": { "tags": ["utils"], "description": "Gets the version of the server", "operationId": "getVersions", "summary": "Gets the version of the server", "security": [], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Object containing all relevant versions", "schema": { "type": "object", "properties": { "ServerVersion": { "$ref": "api_definitions.json#/definitions/version" } } } } } } }, "/users": { "x-swagger-router-controller": "api_users_controller", "get": { "tags": [ "users" ], "description": "List all users", "operationId": "getUsers", "summary": "List users", "security": [ { "administrator_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/limitParam" }, { "$ref": "#/parameters/skipParam" }, { "$ref": "#/parameters/minDateParam" }, { "$ref": "#/parameters/maxDateParam" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Users listed", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/User" } } } } }, "post": { "tags": [ "users" ], "operationId": "createUser", "security": [ ], "summary": "Add user", "parameters": [ { "name": "body", "in": "body", "description": "Request body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/CreateUserBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "User successfully created (no body)" }, "409" : { "description": "Email address already in use", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/users/change-password": { "x-swagger-router-controller": "api_users_controller", "post": { "tags": [ "users" ], "summary": "Change your password", "description": "Allows a user to change their password when they still know their current password. For forgotten passwords, follow the /users/forgot-password flow", "operationId": "changePassword", "parameters": [ { "name": "body", "in": "body", "description": "Change Password Body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/ChangePasswordBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully changed the password.", "headers": { "set-cookie": { "description": "Sets the session cookie (secure, http only) for the new session", "type": "string" } }, "schema": { "type": "object", "properties": { "X-XSRF-TOKEN": { "description": "New XSRF key for the basic session", "$ref": "api_definitions.json#/definitions/hex256" } } } } } } }, "/users/forgot-password": { "x-swagger-router-controller": "api_user_controller", "post": { "tags": [ "users" ], "summary": "Start a password reset", "description": "Starts the forgot password flow", "operationId": "forgotPassword", "security": [ ], "parameters": [ { "name": "body", "in": "body", "description": "Forgot Password Body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/ForgotPasswordBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Questions for the next step.", "headers": { "set-cookie": { "description": "Sets the session cookie (secure, http only) for the forgot password flow", "type": "string" } }, "schema": { "type": "object", "properties": { "X-XSRF-TOKEN": { "description": "New XSRF key for the basic session", "$ref": "api_definitions.json#/definitions/hex256" }, "questions": { "description": "Array of questions to ask the user.", "type": "array", "items": { "$ref": "api_definitions.json#/definitions/question" } } } } } } } }, "/users/forgot-password/verify-credentials": { "x-swagger-router-controller": "api_user_controller", "post": { "tags": [ "users" ], "summary": "Verify user credentials", "description": "Provides answers to the questions returned by /users/forgot-password", "operationId": "verifyCredentials", "security": [ { "reset_password_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "description": "Answers to the questions", "required": true, "schema": { "type": "object", "properties": { "answers": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/answer" } } } } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Email sent with reset password code. Progress to password reset form." }, "401": { "description": "Answers don't match the stored data. The user can correct their answers and re-submit." } } } }, "/users/forgot-password/resend-token": { "x-swagger-router-controller": "api_user_controller", "post": { "tags": [ "users" ], "summary": "Resend reset token", "description": "Requests a resend of the password reset verification token. This will also invalidate the previous token.", "operationId": "resendToken", "security": [ { "reset_password_bridge_session": [ ] } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Email resent with token" }, "403": { "description": "No password reset session exists. A new reset session should be started if required." } } } }, "/users/forgot-password/reset-password": { "x-swagger-router-controller": "api_user_controller", "post": { "tags": [ "users" ], "summary": "Reset password", "description": "Allows the user to reset their password using the token from the recovery email", "operationId": "resetPassword", "security": [ { "reset_password_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "description": "Reset Password Body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/ResetNewPasswordBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Password reset. User must now login again." }, "401": { "description": "The email and password recovery token do not match. The user can re-enter and try again.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/users/resend-confirm-email": { "x-swagger-router-controller": "api_users_controller", "post": { "tags": [ "users" ], "operationId": "resendConfirmEmail", "summary": "Resend the email address confirmation email", "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Email resent" } } } }, "/users/confirm-email": { "x-swagger-router-controller": "api_users_controller", "post": { "tags": [ "users" ], "operationId": "confirmEmail", "summary": "Confirm email address", "parameters": [ { "name": "body", "in": "body", "description": "Request body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/ConfirmEmailBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Email confirmed" } } } }, "/users/complete-registration": { "x-swagger-router-controller": "api_users_controller", "post": { "tags": [ "users" ], "security": [], "operationId": "completeRegistration", "summary": "Completes a partial registration previously added via the integration API", "parameters": [ { "name": "body", "in": "body", "description": "Request body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/CompleteRegistrationBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Registration Complete" } } } }, "/users/deny-email": { "x-swagger-router-controller": "api_users_controller", "post": { "tags": [ "users" ], "operationId": "denyEmail", "summary": "Deny email address", "description": "Allow someone to deny that they signed up for an account with this address. E.g. if someone else entered the wrong address.", "security": [ ], "parameters": [ { "name": "body", "in": "body", "description": "Request body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/DenyEmailBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Email confirmation rejected" } } } }, "/users/me": { "x-swagger-router-controller": "api_users_controller", "get": { "tags": [ "users" ], "operationId": "getUser", "summary": "Get user", "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "The user info", "schema": { "$ref": "api_definitions.json#/definitions/User" } } } }, "post": { "tags": [ "users" ], "operationId": "updateUser", "summary": "Update user", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/User" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Details updated" } } } }, "/users/me/email": { "x-swagger-router-controller": "api_users_controller", "put": { "tags": [ "users" ], "operationId": "changeEmail", "summary": "Change Email address", "security": [ { "elevated_bridge_session": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/ChangeEmailBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Details updated" } } }, "delete": { "tags": [ "users" ], "operationId": "revertChangedEmail", "summary": "Revert an attempt to change the Email address (no login required)", "security": [], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/ConfirmEmailBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Details updated" } } } }, "/users/me/kyc": { "x-swagger-router-controller": "api_users_controller", "get": { "tags": [ "users" ], "operationId": "getKYC", "summary": "Get Client KYC", "description": "Gets the Know Your Customer (KYC) details for this client.", "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "The KYC data for this client", "schema": { "$ref": "api_definitions.json#/definitions/kyc" } } } }, "put": { "tags": [ "users" ], "operationId": "updateKYC", "summary": "Update client KYC", "description": "Updates the Know Your Customer (KYC) details for this client.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/kyc" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "$ref": "api_responses.json#/responses/GeneralError" } } } }, "/users/me/merchant": { "x-swagger-router-controller": "api_users_controller", "get": { "tags": [ "users" ], "operationId": "getMerchant", "summary": "Get client's company details", "description": "Gets the details about the client's company.", "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "The merchant details for this client", "schema": { "$ref": "api_definitions.json#/definitions/merchant" } } } }, "put": { "tags": [ "users" ], "operationId": "updateMerchant", "summary": "Update client's company details.", "description": "Updates the merchant details for this client (authorised merchants only).", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/merchant" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Merchant details added." } } } }, "/users/me/merchant-promo-code": { "x-swagger-router-controller": "api_merchant_controller", "post": { "tags": [ "users" ], "operationId": "addMerchantPromoCode", "summary": "Add a merchant promotion code.", "description": "Enables merchant status if provided with a valid merchant promotion code.", "security": [ { "elevated_bridge_session": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/promoCode" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Merchant status enabled." } } } }, "/users/me/merchant/tokens": { "x-swagger-router-controller": "api_tokens_controller", "get": { "tags": [ "utils" ], "operationId": "listTokens", "summary": "List access tokens.", "description": "Lists all the Integrations API access tokens configured for this merchant (authorised merchants only).", "security": [ { "elevated_bridge_session": [] } ], "x-feature-flag": "tokens", "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Tokens List.", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/apiToken" } } } } }, "post": { "tags": ["utils"], "operationId": "createToken", "summary": "Create an access token.", "description": "Creates an access token for 3rd party access to the services (authorised merchants only).", "security": [{ "elevated_bridge_session": [] }], "x-feature-flag": "tokens", "parameters": [{ "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/apiToken" } }], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Token created.", "schema": { "type": "object", "properties": { "token": { "description": "The new token. This must be saved as its not available again from the system.", "type":"string" } } } } } } }, "/users/me/merchant/tokens/{token}": { "x-swagger-router-controller": "api_tokens_controller", "delete": { "tags": [ "utils" ], "operationId": "deleteToken", "summary": "Delete access token.", "description": "Deletes an access token, preventing it from being used in any future integrations API reqiests.", "security": [{ "elevated_bridge_session": [] }], "x-feature-flag": "tokens", "parameters": [{ "name": "token", "in": "path", "description": "Token to delete", "required": true, "type": "string", "pattern": "^[a-zA-Z0-9\\-_]+?\\.[a-zA-Z0-9\\-_]+?\\.([a-zA-Z0-9\\-_]+)?$" }], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Token deleted." } } } }, "/transactions": { "x-swagger-router-controller": "api_transactions_controller", "get": { "tags": [ "transactions" ], "operationId": "getTransactions", "summary": "List transactions", "description": "This command returns a list of transactions for the current user", "parameters": [ { "$ref": "#/parameters/limitParam" }, { "$ref": "#/parameters/skipParam" }, { "$ref": "#/parameters/minDateParam" }, { "$ref": "#/parameters/maxDateParam" }, { "name": "transactionTypes", "description": "The type(s) of transaction to return. See Transaction for the meaning of the values.", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ] } }, { "name": "accountId", "description": "Return only transactions associated with this account", "in": "query", "required": false, "type": "string", "pattern": "^([a-z0-9]{24})$", "minLength": 24, "maxLength": 24 } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful listing", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/transaction" } } } } } }, "/transactions/{objectId}": { "x-swagger-router-controller": "api_transactions_controller", "get": { "tags": [ "transactions" ], "operationId": "getTransaction", "summary": "Transaction detail", "description": "The detailed information of a single transaction", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Transaction found", "schema": { "$ref": "api_definitions.json#/definitions/transactionDetail" } } } } }, "/transactions/{objectId}/refund": { "x-swagger-router-controller": "api_transactions_controller", "post": { "tags": [ "transactions" ], "operationId": "refundTransaction", "summary": "Refund transaction", "description": "Refunds this whole transaction. Can only be initiated by the merchant side of the transaction.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Transaction refunded" } } } }, "/transactions/{objectId}/dispute": { "x-swagger-router-controller": "api_transactions_controller", "post": { "tags": [ "transactions" ], "operationId": "disputeTransaction", "summary": "Dispute transaction", "description": "Flags a dispute with this transaction (e.g. incorrect amount, suspected fraud, etc.). This may only be initiated by the customer side of the transaction.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/transactionDispute" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Transaction dispute added" } } } }, "/transactions/{objectId}/cancel-dispute": { "x-swagger-router-controller": "api_transactions_controller", "post": { "tags": [ "transactions" ], "operationId": "cancelDisputeTransaction", "summary": "Cancel dispute.", "description": "Removes the dispute request from this transaction", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Transaction dispute removed" } } } }, "/accounts": { "x-swagger-router-controller": "api_accounts_controller", "get": { "tags": [ "accounts" ], "operationId": "getAccounts", "summary": "List accounts", "description": "This command returns a list of accounts for the current client", "parameters": [ { "$ref": "#/parameters/limitParam" }, { "$ref": "#/parameters/skipParam" }, { "$ref": "#/parameters/minDateParam" }, { "$ref": "#/parameters/maxDateParam" }, { "name": "includeDeleted", "in": "query", "description": "Set to true if the query should also return deleted accounts, otherwise they are not included.", "required": false, "default": false, "type": "boolean" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful listing", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/account" } } } } } }, "/accounts/add/credorax": { "x-swagger-router-controller": "api_accounts_controller", "post": { "tags": [ "accounts" ], "operationId": "addAccountCredorax", "summary": "Add a Credorax merchant account", "description": "Adds a Credorax merchant account into the client's account list. Note that this is only valid for client's with merchant status enabled.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/AddAccountCredoraxMerchantBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new account", "schema": { "type": "object", "description": "The id of the new account", "properties": { "id": { "$ref": "api_definitions.json#/definitions/uuid" } } } } } } }, "/accounts/add/worldpay": { "x-swagger-router-controller": "api_accounts_controller", "post": { "tags": ["accounts"], "operationId": "addAccountWorldpay", "summary": "Add a Worldpay merchant account", "description": "Adds a Worldpay merchant account into the client's account list. Note that this is only valid for client's with merchant status enabled.", "security": [{ "elevated_bridge_session": [] }], "parameters": [{ "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/AddAccountWorldpayMerchantBody" } }], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new account", "schema": { "type": "object", "description": "The id of the new account", "properties": { "id": { "$ref": "api_definitions.json#/definitions/uuid" } } } } } } }, "/accounts/add/demo": { "x-swagger-router-controller": "api_accounts_controller", "post": { "tags": ["accounts"], "operationId": "addAccountDemo", "summary": "Add a Demo merchant account", "description": "Adds a Demo merchant account into the client's account list. Note that this is only valid for client's with merchant status enabled.", "security": [{ "elevated_bridge_session": [] }], "parameters": [{ "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/AddAccountBase" } }], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new account", "schema": { "type": "object", "description": "The id of the new account", "properties": { "id": { "$ref": "api_definitions.json#/definitions/uuid" } } } } } } }, "/accounts/{objectId}": { "x-swagger-router-controller": "api_accounts_controller", "get": { "tags": [ "accounts" ], "operationId": "getAccount", "summary": "Account details", "description": "This command returns more details on the specified account", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful", "schema": { "$ref": "api_definitions.json#/definitions/account" } } } }, "post": { "tags": [ "accounts" ], "operationId": "updateAccount", "summary": "Update account", "description": "Updates editable parameters of an account. NOTE: For more extensive changes, create a new account.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/UpdateAccountBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful update" } } }, "delete": { "tags": [ "accounts" ], "operationId": "deleteAccount", "summary": "Delete Account", "description": "Deletes an account", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully deleted" } } } }, "/addresses": { "x-swagger-router-controller": "api_addresses_controller", "get": { "tags": [ "accounts" ], "operationId": "getAddresses", "summary": "List addresses", "description": "This command returns a list of addresses for the current client", "parameters": [ { "$ref": "#/parameters/limitParam" }, { "$ref": "#/parameters/skipParam" }, { "$ref": "#/parameters/minDateParam" }, { "$ref": "#/parameters/maxDateParam" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful listing", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/address" } } } } }, "post": { "tags": [ "accounts" ], "operationId": "addAddress", "summary": "Add address", "description": "Add a new address. The parameter type depends on the address type being created", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "schema": { "allOf": [ { "$ref": "api_definitions.json#/definitions/address" }, { "required": [ "AddressDescription", "Address1", "Town", "PostCode", "Country" ] } ] } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new address", "schema": { "type": "object", "description": "The id of the new address", "properties": { "AddressID": { "$ref": "api_definitions.json#/definitions/uuid" } } } } } } }, "/addresses/{objectId}": { "x-swagger-router-controller": "api_addresses_controller", "get": { "tags": [ "accounts" ], "operationId": "getAddress", "summary": "Address details", "description": "This command returns the specified address", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful", "schema": { "$ref": "api_definitions.json#/definitions/address" } } } }, "delete": { "tags": [ "accounts" ], "operationId": "deleteAddress", "summary": "Delete Address", "description": "Deletes an address", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully deleted" } } } }, "/items": { "x-swagger-router-controller": "api_items_controller", "get": { "tags": [ "merchant" ], "operationId": "getItems", "summary": "List items", "description": "This command returns a list of items for the current client", "parameters": [ { "name": "includeDeleted", "in": "query", "description": "true to include deleted items as well as activeones.", "required": false, "type": "boolean", "default": false }, { "name": "BridgeID", "in": "query", "description": "Limit the returned items to only ones that match the BridgeID", "required": false, "type": "string", "pattern": "\\d{8}T\\d{9}[A-z\\d]{14}", "minLength": 32, "maxLength": 32 } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful listing", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/item" } } } } }, "post": { "tags": [ "merchant" ], "operationId": "addItems", "summary": "Add items", "description": "Add one or more new items.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/item" } } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new item", "schema": { "type": "object", "description": "An array containing the ids of the new items", "properties": { "ItemID": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/uuid" } } } } } } } }, "/items/{objectId}": { "x-swagger-router-controller": "api_items_controller", "get": { "tags": [ "merchant" ], "operationId": "getItem", "summary": "Item details", "description": "This command returns the specified item", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful", "schema": { "$ref": "api_definitions.json#/definitions/item" } } } }, "post": { "tags": [ "merchant" ], "operationId": "updateItem", "summary": "Update an item", "description": "Creates a new version of the item with the associated modifications, and makes it the active version.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/item" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new version of the item", "schema": { "type": "object", "description": "The id of the new version of the item", "properties": { "ItemID": { "$ref": "api_definitions.json#/definitions/uuid" } } } } } }, "delete": { "tags": [ "merchant" ], "operationId": "deleteItem", "summary": "Delete Item", "description": "Deletes an item", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully deleted" } } } }, "/devices": { "x-swagger-router-controller": "api_devices_controller", "get": { "tags": [ "devices" ], "operationId": "getDevices", "summary": "List devices", "description": "This command returns a list of devices for the current client", "parameters": [ { "$ref": "#/parameters/limitParam" }, { "$ref": "#/parameters/skipParam" }, { "$ref": "#/parameters/minDateParam" }, { "$ref": "#/parameters/maxDateParam" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful listing", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/device" } } } } }, "post": { "tags": [ "devices" ], "operationId": "addDevice", "summary": "Adds a device to a registered account.", "description": "This command adds a device to a registered account", "security": [], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/AddDeviceBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Existing device found.\n \n Possible description/code: \n \n * Device re-registered. (10039) \n * Waiting for SMS code. (10042) \n * Device re-registered - please reset PIN. (10068)", "schema": { "allOf":[ {"type": "object", "properties": { "DeviceID": { "description": "Unique identifier for the device (created by the server)", "$ref": "api_definitions.json#/definitions/uuid" }, "DeviceToken": { "description": "A token that is unique to this device", "$ref": "api_definitions.json#/definitions/token" } } }, {"$ref": "api_definitions.json#/definitions/SuccessInfo"} ] } }, "201": { "description": "New device added. \n \n Possible description/code: \n \n * AddDevice successful. (10048) \n * Changing hardware ID. (10040)", "schema": { "allOf":[ {"type": "object", "properties": { "DeviceID": { "description": "Unique identifier for the device (created by the server)", "$ref": "api_definitions.json#/definitions/uuid" }, "DeviceToken": { "description": "A token that is unique to this device", "$ref": "api_definitions.json#/definitions/token" } } }, {"$ref": "api_definitions.json#/definitions/SuccessInfo"} ] } }, "401": { "description": "Invalid details. \n \n Possible causes: \n \n * Wrong password. (code: 411) \n * No client registration found. (code: 333)", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "403": { "description": "Possible causes: \n \n * This phone number is registered to somebody else. (code: 338) \n * Maximum number of devices reached. (code: 359) \n * The device has been put on hold by Comcarde. (code: 341) \n * The device has been suspended by the user. (code 342) \n * Client barred. (code: 117) \n * Account Locked. (code: 406)", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "Failed to update the Device", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/devices/reportlost": { "x-swagger-router-controller": "api_devices_controller", "post": { "tags": [ "devices" ], "operationId": "reportLost", "summary": "Reports a device as lost", "description": "Reports the device as lost and suspends it, so it can't be used. This requires at least a partial login that is waiting for 2-factor authorisation.", "security": [ { "awaiting_2fa_bridge_session": [ ] } ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/ReportLostBody" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Lost device has been suspended" } } } }, "/devices/{objectId}": { "x-swagger-router-controller": "api_devices_controller", "get": { "tags": [ "devices" ], "operationId": "getDevice", "summary": "Device details", "description": "This command returns details on the specified device", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful", "schema": { "$ref": "api_definitions.json#/definitions/device" } } } }, "post": { "tags": [ "devices" ], "operationId": "updateDevice", "summary": "Update device", "description": "Updates editable parameters of a device. Larger changes like changing phone number, device etc. must re-register as a new device.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "api_definitions.json#/definitions/device" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful update" } } }, "delete": { "tags": [ "devices" ], "operationId": "deleteDevice", "summary": "Delete device", "description": "Deletes a device. The device will no longer be able to interact with server (no payments, transaction history, etc.). To use the device again it will need to be re-registered.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully deleted" } } } }, "/devices/{objectId}/login": { "x-swagger-router-controller": "api_devices_login_controller", "post":{ "tags": ["login"], "summary": "Logs in to a device", "description": "Allows a user to login via a device to get a session key that can be used for further requests.", "operationId": "deviceLogin", "security": [{ "device_hmac_nosession": [] }], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in":"body", "description": "Body", "required": true, "schema":{ "type": "object", "properties": { "ClientName": { "$ref": "api_definitions.json#/definitions/email" }, "DeviceAuthorisation": { "description": "The Pin for this device", "$ref": "api_definitions.json#/definitions/deviceAuthorisation" }, "DeviceHardware": { "$ref": "api_definitions.json#/definitions/DeviceHardware" }, "DeviceSoftware": { "$ref": "api_definitions.json#/definitions/DeviceSoftware" }, "Location": { "description": "Location of the device", "$ref": "api_definitions.json#/definitions/geojson-point" } }, "required": [ "ClientName", "DeviceAuthorisation", "DeviceHardware", "DeviceSoftware" ] } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Login Successful", "schema": { "$ref": "api_definitions.json#/definitions/successfulDeviceLoginResponse" } }, "202": { "description": "Credentials accepted, but HMAC rotation must be confirmed before further requests are made", "schema": { "allOf": [ { "$ref": "api_definitions.json#/definitions/successfulDeviceLoginResponse" }, { "$ref": "api_definitions.json#/definitions/pendingHmacResponse" } ] } }, "401": { "description": "Device not found, doesn't belong to ClientName, or the DeviceAuthorisation doesn't match.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "403": { "description": "Client or Device not in the correct state. The DeviceAuthorisation may not be configured, or the device or client may be suspended or barred.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "A simultaneous conflicting change has prevented this operation from completing.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/devices/{objectId}/verification":{ "x-swagger-router-controller": "api_devices_controller", "post":{ "tags": ["devices"], "summary": "Verify the Phone Number", "description": "Allow a user to verify their phone number", "operationId": "verifyPhoneNumber", "security": [], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in":"body", "description": "Verify Phone Number Body", "required": true, "schema":{ "type": "object", "properties": { "DeviceToken": { "description": "A token that is unique to this device", "$ref": "api_definitions.json#/definitions/token" }, "DeviceNumber": { "$ref": "api_definitions.json#/definitions/phoneNumber" }, "RegistrationToken": { "description": "A 6 digit code sent to the phone via SMS, which is used to verify the phone number.", "allOf": [ { "$ref": "api_definitions.json#/definitions/numeric" }, { "minLength": 6, "maxLength": 6 } ], "example": "123456" } }, "required": [ "DeviceToken", "DeviceNumber", "RegistrationToken" ] } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully verified phone number (re-registration)." }, "201": { "description": "Successfully verified phone number." }, "401": { "description": "Possible causes: \n \n * Invalid Device ID \n * Invalid device number \n * Invalid device token \n * Invalid registration Token.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "403": { "description": "Possible causes: \n \n * Device not in the correct state. \n * The Device may be suspended or barred. \n * Too many registration token attempts\n * Registration token has expired", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "Failed to update the Device", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/devices/{objectId}/pin":{ "x-swagger-router-controller": "api_devices_controller", "post":{ "tags": ["devices"], "summary": "Set your Pin for this device", "description": "Allow a user to set their pin for their device.", "operationId": "setPin", "security": [], "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "body", "in":"body", "description": "Set Pin Body", "required": true, "schema":{ "type": "object", "properties": { "DeviceToken": { "description": "A token that is unique to this device", "$ref": "api_definitions.json#/definitions/token" }, "ClientName": { "$ref": "api_definitions.json#/definitions/email" }, "Location": { "description": "Location of the device", "$ref": "api_definitions.json#/definitions/geojson-point" }, "DeviceAuthorisation": { "description": "The Pin for this device", "$ref": "api_definitions.json#/definitions/deviceAuthorisation" } }, "required": [ "DeviceToken", "ClientName", "DeviceAuthorisation" ] } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Pin successfully set." }, "401": { "description": "Possible causes: \n \n * Device not found \n * Device doesn't belong to ClientName, \n * The DeviceToken doesn't match.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "403": { "description": "Possible causes: \n \n * Client or Device not in the correct state. \n * The Device or Client may be suspended or barred.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "Failed to update the Device", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/devices/{objectId}/suspend": { "x-swagger-router-controller": "api_devices_controller", "post": { "tags": [ "devices" ], "operationId": "suspendDevice", "summary": "Suspend device", "description": "Client requested suspension of the phone. Will prevent transactions being made on this phone until resumed. Can be useful if the phone is thought to be lost, etc.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully suspended operation of the app on the device" } } } }, "/devices/{objectId}/resume": { "x-swagger-router-controller": "api_devices_controller", "post": { "tags": [ "devices" ], "operationId": "resumeDevice", "summary": "Resume device", "description": "Reverses the client requested suspension of the phone. The phone will now be able to make transactions again.", "security": [ { "elevated_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully resumed operation of the app on the device" } } } }, "/devices/{objectId}/bar": { "x-swagger-router-controller": "api_devices_controller", "post": { "tags": [ "devices" ], "operationId": "barDevice", "summary": "Bar device", "description": "Bars the device from use (suspected fraud, etc.). This is administrator driven and cannot be overridden by the client.", "security": [ { "administrator_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully barred the device" } } } }, "/devices/{objectId}/unbar": { "x-swagger-router-controller": "api_devices_controller", "post": { "tags": [ "devices" ], "operationId": "unbarDevice", "summary": "Restores device (after barring).", "description": "Restores the device from use after it was barred. This is administrator driven and cannot be done by the client.", "security": [ { "administrator_bridge_session": [ ] } ], "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully unbarred the device" } } } }, "/invoices": { "x-swagger-router-controller": "api_invoices_controller", "get": { "tags": [ "merchant" ], "operationId": "getInvoices", "summary": "List invoices", "description": "This command returns a list of outstanding invoices for the current merchant.", "x-feature-flag": "invoices", "parameters": [ { "$ref": "#/parameters/limitParam" }, { "$ref": "#/parameters/skipParam" }, { "$ref": "#/parameters/minDateParam" }, { "$ref": "#/parameters/maxDateParam" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful listing", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/pendingInvoice" } } } } }, "post": { "tags": [ "merchant" ], "operationId": "addInvoice", "summary": "Add a new pending invoice", "description": "Adds a new pending invoice.", "security": [ { "elevated_bridge_session": [ ] } ], "x-feature-flag": "invoices", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/addUpdateInvoice" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "201": { "description": "Successfully added the new invoice(s)", "schema": { "type": "object", "description": "An array containing the ids of the new invoices", "properties": { "InvoiceIDs": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/uuid" } } } } }, "403": { "description": "The caller is not an active merchant and can't add invoices", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "The specified customer or account id doesn't exist in the system.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/invoices/{objectId}": { "x-swagger-router-controller": "api_invoices_controller", "get": { "tags": [ "merchant" ], "operationId": "getInvoice", "summary": "Invoice details", "description": "This command returns the specified invoice", "x-feature-flag": "invoices", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successful", "schema": { "$ref": "api_definitions.json#/definitions/pendingInvoiceDetail" } } } }, "post": { "tags": [ "merchant" ], "operationId": "updateInvoice", "summary": "Update and/or resubmit a rejected invoice", "description": "Updates and/or resubmits a rejected invoice with new details. If 'resubmit' is set true, this will re-submit a rejected invoice (after any updates).", "security": [ { "elevated_bridge_session": [ ] } ], "x-feature-flag": "invoices", "parameters": [ { "$ref": "#/parameters/objectId" }, { "name": "resubmit", "in": "query", "type": "boolean" }, { "name": "body", "in": "body", "schema": { "$ref": "api_definitions.json#/definitions/addUpdateInvoice" } } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully updated the invoice" }, "403": { "description": "The caller is not an active merchant and can't add invoices", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } }, "409": { "description": "The specified customer or account id doesn't exist in the system.", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } }, "delete": { "tags": [ "merchant" ], "operationId": "cancelInvoice", "summary": "Cancel an invoice", "description": "Cancels an invoice that hasn't been paid yet.", "security": [ { "elevated_bridge_session": [ ] } ], "x-feature-flag": "invoices", "parameters": [ { "$ref": "#/parameters/objectId" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Successfully cancelled" }, "404": { "description": "The invoice is not found, or not in Pending or Rejected state", "schema": { "$ref": "api_definitions.json#/definitions/ErrorInfo" } } } } }, "/csp-report": { "x-swagger-router-controller": "api_csp_controller", "post": { "tags": [ "utils" ], "consumes": [ "application/json", "application/csp-report" ], "operationId": "cspReport", "summary": "Receives CSP violation reports", "description": "Receives CSP violation reports", "security": [], "parameters": [ { "name": "body", "in": "body", "description": "Report", "required": true, "schema": { "type": "object", "properties": { "csp-report": { "$ref": "api_definitions.json#/definitions/CspReport" } } } } ], "responses": { "204": { "description": "Report received." } } } }, "/utils/postcodeLookup/{postcode}": { "x-swagger-router-controller": "api_postcodes_controller", "get": { "tags": [ "utils" ], "operationId": "postcodeLookup", "summary": "Postcode to addresses lookup", "description": "Returns a list of addresses based on the provided postcode", "parameters": [ { "name": "postcode", "in": "path", "description": "PostCode", "required": true, "type": "string" } ], "responses": { "default": { "$ref": "api_responses.json#/responses/GeneralError" }, "200": { "description": "Lookup successful.", "schema": { "type": "array", "items": { "$ref": "api_definitions.json#/definitions/address" } } } } } } }, "securityDefinitions": { "bridge_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "An active session with the Bridge server is required. This represents the basic level that all users initially get after successful log in. See <> for more details.", "x-session-cookie": "X-BRIDGE-SESSION" }, "elevated_bridge_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "As per the bridge_session, except this session is elevated to a higher security level using <>. This is required for certain secure operations (adding/removing accounts, etc.). Paths requiring only the standard session level can also be used with an elevated session level.", "x-session-cookie": "X-BRIDGE-SESSION" }, "administrator_bridge_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "As per the bridge_session, except for administrative users. Administrative level users can also use paths that require standard or elevated sessions.", "x-session-cookie": "X-BRIDGE-SESSION" }, "reset_password_bridge_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "A session to manage the password reset flow. The full password reset must be completed within this session. Sessions at this level *MAY NOT* use any paths that require any other session type.", "x-session-cookie": "X-BRIDGE-SESSION" }, "awaiting_2fa_bridge_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "A session for when email and password have been verified, but still waiting for 2FA to complete. Sessions at this level *MAY NOT* use any paths that require any other session type.", "x-session-cookie": "X-BRIDGE-SESSION" }, "awaiting_accept_eula_bridge_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "A session for when email and password have been verified, but still waiting for an updated EULA to be accepted. Sessions at this level *MAY NOT* use any paths that require any other session type.", "x-session-cookie": "X-BRIDGE-SESSION" }, "recovery_session": { "type": "apiKey", "name": "X-XSRF-TOKEN", "in": "header", "description": "A session for handling account recovery.", "x-session-cookie": "X-BRIDGE-SESSION" }, "device_session": { "type": "apiKey", "description": "Session from a mobile device. Sent as :. This also requires a valid HMAC to be passed in the `x-bridge-hmac` header, with timestamp in `x-bridge-timestamp`. See HMAC Implementation docs for more information.", "name": "x-bridge-device-session", "in": "header" }, "device_hmac_nosession": { "type": "apiKey", "description": "A variant of the session hmac for cases where there is no session yet. This also requires a client timestamp in `x-bridge-timestamp`. See HMAC Implementation docs for more information.", "name": "x-bridge-hmac", "in": "header" } }, "parameters": { "objectId": { "name": "objectId", "in": "path", "required": true, "type": "string", "pattern": "^([A-Za-z0-9]{24})$", "minLength": 24, "maxLength": 24 }, "imageRef": { "name": "imageRef", "in": "path", "required": true, "type": "string", "pattern": "^([a-f0-9]{24}|(defaultSelfie)|(defaultCompanyLogo0))$", "minLength": 13, "maxLength": 24 }, "addressID": { "name": "addressID", "in": "path", "required": true, "type": "string", "pattern": "^([A-Za-z0-9]{24})$", "minLength": 24, "maxLength": 24 }, "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": false, "type": "integer", "format": "int32", "default": 0, "minimum": 0 }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": false, "type": "integer", "format": "int32", "default": 30, "minimum": 1, "maximum": 30 }, "minDateParam": { "name": "minDate", "in": "query", "description": "Records returned should have been dated after this ISO 8601 date-time", "required": false, "type": "string", "format": "date-time" }, "maxDateParam": { "name": "maxDate", "in": "query", "description": "Records returned should have been dated before this ISO 8601 date-time. Defaults to `now` if not set.", "required": false, "type": "string", "format": "date-time" } } }