{ "openapi": "3.0.1", "info": { "title": "Pays Service API Specifications", "version": "2.1.0", "description": "API to manage payment transactions." }, "externalDocs": { "description": "TPE Auth Server API Documentation", "url": "https://civitek.github.io/open-api-docs/tpe-auth.html" }, "servers": [ { "url": "https:testapi.civikestpayment.com", "description": "Test server url" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Payment Service", "description": "Operations for processing payments and retrieving available payment methods." }, { "name": "Subscription Service", "description": "Operations for managing subscriptions and stored payment methods." }, { "name": "Recurring Service", "description": "Operations for setting up and managing recurring payments." }, { "name": "Order Service", "description": "Operations for retrieving order and receipt details." } ], "paths": { "/payment/processPayment": { "post": { "tags": [ "Payment Service" ], "summary": "Process a payment transaction", "description": "Accepts payment details and processes the transaction.", "operationId": "processPayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } }, "required": true }, "responses": { "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Payment request processed successfully. The payment may be approved or declined. Check the response status for the transaction outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/payment/paymentMethods": { "post": { "tags": [ "Payment Service" ], "summary": "Retrieve payment methods", "description": "Returns a list of available payment methods, along with their corresponding fees.", "operationId": "getpaymentMethods", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodsRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Payment methods not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Retrieved payment methods successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodsResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/order/receipt/{orderId}": { "post": { "tags": [ "Order Service" ], "summary": "Get order receipt", "description": "Retrieves receipt details for a completed order using the orderId.", "operationId": "orderReceiptDetails", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Unique identifier of the order." } ], "responses": { "200": { "description": "Order receipt retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptModel" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/order/details/{orderId}": { "post": { "tags": [ "Order Service" ], "summary": "Get order details", "description": "Retrieves order details for the specified orderId.", "operationId": "viewOrder", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Unique identifier of the order." } ], "responses": { "200": { "description": "Order details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscription/paymentMethods": { "post": { "tags": [ "Subscription Service" ], "summary": "Retrieves stored payment methods", "description": "Gets the stored payment methods associated with a subscriptionId", "operationId": "findStoredPaymentMethods", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredPaymentMethodRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "No saved payment methods found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Payment methods successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredPaymentMethodsResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscription/update": { "post": { "tags": [ "Subscription Service" ], "summary": "Updates subscription details", "description": "Updates email and phone number associated with a subscriptionId", "operationId": "updateSubscriptionDetails", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetailsRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "No saved payment methods found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Payment methods successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetailsResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscription/deletePaymentMethod": { "post": { "tags": [ "Subscription Service" ], "summary": "Deletes a stored payment method", "description": "Deletes the stored payment method associated with a referenceId", "operationId": "deleteSavedPaymentMethod", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteStoredPaymentMethodRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Payment method deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscription/addIdentity": { "post": { "tags": [ "Subscription Service" ], "summary": "Adds identities to the subscription", "description": "Adds identities and associates them with a subscriptionId, while overwritting the previously added identities", "operationId": "addIdentity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionIdentitiesRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "200": { "description": "Identities added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/recurring/setup": { "post": { "tags": [ "Recurring Service" ], "summary": "Create recurring payment", "description": "Sets up a recurring payment using the specified subscription, stored payment method, item, and schedule.", "operationId": "setup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRequest" } } }, "required": true }, "responses": { "200": { "description": "Recurring payment setup completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Subscription or stored payment method not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/recurring/details": { "post": { "tags": [ "Recurring Service" ], "summary": "Get recurring payment details", "description": "Retrieves the configuration and status of a recurring payment for the provided recurring ID.", "operationId": "details", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringDetailsRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Recurring payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Recurring payment details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringDetailsResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/recurring/cancel": { "post": { "tags": [ "Recurring Service" ], "summary": "Cancel recurring payment", "description": "Cancels an active recurring payment and stops future billing cycles for the specified recurring ID.", "operationId": "cancel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringCancelRequest" } } }, "required": true }, "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Recurring payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Recurring payment cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringCancelResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/recurring/subscription": { "post": { "tags": [ "Recurring Service" ], "summary": "Get recurring items", "description": "Retrieves all the recurring payment items associated with a subscriptionId.", "operationId": "subscriptionDetails", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringSubscriptionRequest" } } }, "required": true }, "responses": { "200": { "description": "Retrived the recurring payment details successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringSubscriptionResponse" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "SubscriptionId not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/recurring/history": { "post": { "tags": [ "Recurring Service" ], "summary": "Get recurring payment history", "description": "Retrieves all the recurring payments associated with a subscriptionId and recurringId.", "operationId": "getRecurringPaymentHistory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringHistoryRequest" } } }, "required": true }, "responses": { "404": { "description": "No records found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Retrived the recurring payment history successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringHistoryResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "responses": { "UnauthorizedError": { "description": "Unauthorized. The access token is missing, invalid, or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "StoredPaymentMethodRequest": { "required": [ "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier used to retrieve stored payment methods." } } }, "ErrorResponse": { "type": "object", "properties": { "responseTimestamp": { "type": "string", "description": "Date and time when the error response was generated.", "format": "date-time" }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "message": { "type": "string", "description": "Error message." } } }, "StoredBankAccount": { "type": "object", "properties": { "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method." }, "maskedAccountNumber": { "type": "string", "description": "Masked bank account number." }, "maskedRoutingNumber": { "type": "string", "description": "Masked routing number." }, "accountHolderName": { "type": "string", "description": "Account holder name or business name." } }, "description": "List of stored bank accounts for the subscriber." }, "StoredCreditCard": { "type": "object", "properties": { "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method." }, "maskedCardNumber": { "type": "string", "description": "Masked credit card number." }, "cardType": { "type": "string", "description": "Card type." }, "cardHolderName": { "type": "string", "description": "Card holder name." }, "expiryMonth": { "type": "string", "description": "Expiration month." }, "expiryYear": { "type": "string", "description": "Expiration year." } }, "description": "List of stored credit cards for the subscriber." }, "StoredPaymentMethodsResponse": { "type": "object", "properties": { "creditCards": { "type": "array", "description": "List of stored credit cards for the subscription.", "items": { "$ref": "#/components/schemas/StoredCreditCard" } }, "bankAccounts": { "type": "array", "description": "List of stored bank accounts for the subscription.", "items": { "$ref": "#/components/schemas/StoredBankAccount" } }, "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the stored payment methods." }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "message": { "type": "string", "description": "Response message." }, "responseTimestamp": { "type": "string", "description": "Date and time when the response was generated.", "format": "date-time" } } }, "DeleteStoredPaymentMethodRequest": { "required": [ "storedPaymentMethodId", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the stored payment method." }, "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method to delete." } } }, "SubscriptionResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Id associated with a user's stored payments" }, "storedPaymentMethodId": { "type": "string", "description": "Identifies a specific stored payment" }, "httpStatusCode": { "type": "integer", "description": "Http status code", "format": "int32" }, "message": { "type": "string", "description": "Success message" }, "responseTimestamp": { "type": "string", "description": "Date of response", "format": "date-time" } } }, "CustomerIdentity": { "required": [ "countryCode", "identityTypeId", "value" ], "type": "object", "properties": { "identityTypeId": { "type": "integer", "description": "Valid values: 1=SSN, 2=Passport, 4=Alien Registration Number for Identity One; 0=Other, 3=Driver’s License for Identity Two", "format": "int32", "example": 1, "enum": [0, 1, 2, 3, 4] }, "value": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The identity's value", "example": "SSN Number, Passport Id, Driver's license, etc." }, "countryCode": { "type": "string", "description": "Country code", "example": "US" }, "region": { "type": "string", "description": "(optional for SSN, Passport, and Alien Registration Number; required for Driver's license and Other)Region/state code", "example": "CA" } }, "description": "Identities that will be associated with SubscriptionId" }, "SubscriptionIdentitiesRequest": { "required": [ "identities", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Id associated with a user's stored payments" }, "identities": { "maxItems": 2, "minItems": 2, "type": "array", "description": "Identities that will be associated with SubscriptionId", "items": { "$ref": "#/components/schemas/CustomerIdentity" } } } }, "SubscriptionDetailsRequest": { "type": "object", "description": "Either email or phone must be provided.", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier." }, "email": { "type": "string", "description": "Subscriber's email address." }, "phone": { "type": "string", "description": "Subscriber's phone number." } }, "required": [ "subscriptionId" ] }, "SubscriptionDetailsResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier." }, "httpStatusCode": { "type": "integer", "format": "int32", "description": "Http status code" }, "message": { "type": "string", "description": "Response message" }, "responseTimestamp": { "type": "string", "format": "date-time", "description": "Date of response" } } }, "Item": { "type": "object", "properties": { "itemKey": { "type": "string", "description": "The item's key" }, "amount": { "type": "number", "description": "The amount to pay for the item" }, "instanceId": { "type": "string", "description": "SKU" }, "attributes": { "type": "array", "description": "Additional attributes", "items": { "$ref": "#/components/schemas/ItemAttribute" } } }, "description": "Item charged on the recurring schedule." }, "ItemAttribute": { "type": "object", "properties": { "receiptDisplay": { "type": "boolean", "description": "Determines whether or not the attribute is displayed on the receipt" }, "attribute": { "type": "string", "description": "Attribute name" }, "value": { "type": "string", "description": "Attribute value" } }, "description": "Additional attributes" }, "RecurringRequest": { "required": [ "item", "paymentType", "recurringFrequency", "recurringStartDate", "storedPaymentMethodId", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the customer and stored payment method." }, "paymentType": { "type": "string", "description": "Type of payment method.", "enum": [ "creditcard", "echeck" ] }, "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method to be used for recurring payments." }, "item": { "$ref": "#/components/schemas/Item" }, "recurringFrequency": { "type": "string", "description": "Recurring payment frequency.", "enum": [ "daily", "weekly", "monthly", "bi_weekly", "bi_monthly", "annually" ] }, "recurringStartDate": { "type": "string", "description": "Start date of the recurring schedule.", "format": "date" }, "recurringEndDate": { "type": "string", "description": "End date of the recurring schedule. If provided, no payments are scheduled after this date.", "format": "date" } } }, "RecurringResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment setup." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment setup." }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "message": { "type": "string", "description": "Response message." }, "responseTimestamp": { "type": "string", "description": "Date and time when the response was generated.", "format": "date-time" } } }, "RecurringDetailsRequest": { "required": [ "recurringId", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." } } }, "RecurringDetailsResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." }, "paymentType": { "type": "string", "description": "Type of payment method.", "enum": [ "creditcard", "echeck" ] }, "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method used for the recurring payment." }, "item": { "$ref": "#/components/schemas/Item" }, "recurringFrequency": { "type": "string", "description": "Recurring payment frequency.", "enum": [ "daily", "weekly", "monthly", "bi_weekly", "bi_monthly", "annually" ] }, "recurringStartDate": { "type": "string", "description": "Start date of the recurring schedule.", "format": "date" }, "recurringEndDate": { "type": "string", "description": "End date of the recurring schedule.", "format": "date" }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "message": { "type": "string", "description": "Response message." }, "responseTimestamp": { "type": "string", "description": "Date and time when the response was generated.", "format": "date-time" } } }, "RecurringSubscriptionRequest": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment.", "minLength": 1 }, "status": { "type": "string", "description": "Optional recurring payment status. Default is active", "enum": [ "active", "cancel", "all" ] } }, "required": [ "subscriptionId" ] }, "RecurringSubscriptionDetails": { "type": "object", "properties": { "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." }, "paymentType": { "type": "string", "description": "Type of payment method.", "enum": [ "creditcard", "echeck" ] }, "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method used for the recurring payment." }, "recurringStatus": { "type": "string", "description": "Recurring payment Status" }, "cancelReason": { "type": "string", "description": "Cancel Reason" }, "cancelReasonText": { "type": "string", "description": "Cancel Reason Text" }, "cancelledDate": { "type": "string", "format": "date", "description": "Cancelled Date" }, "item": { "$ref": "#/components/schemas/PaymentItem", "description": "Item charged on the recurring schedule." }, "recurringFrequency": { "type": "string", "description": "Recurring payment frequency.", "enum": [ "daily", "weekly", "monthly", "bi_weekly", "bi_monthly", "annually" ] }, "recurringStartDate": { "type": "string", "format": "date", "description": "Start date of the recurring schedule." }, "recurringEndDate": { "type": "string", "format": "date", "description": "End date of the recurring schedule." }, "nextPaymentDate": { "type": "string", "format": "date", "description": "Next recurring payment date." }, "createDate": { "type": "string", "format": "date", "description": "Date that the recurring payment was created." } } }, "RecurringSubscriptionResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "message": { "type": "string", "description": "Response message." }, "responseTimestamp": { "type": "string", "description": "Date and time when the response was generated.", "format": "date-time" }, "recurringItems": { "type": "array", "description": "All recurring payment details associated with subscriptionId.", "items": { "$ref": "#/components/schemas/RecurringSubscriptionDetails" } } } }, "RecurringCancelRequest": { "required": [ "cancelReasonCode", "recurringId", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." }, "cancelReasonCode": { "type": "integer", "description": "Cancellation reason code. Valid values: 1 = Payment Failure, 2 = Fraud-Related, 3 = Chargeback, 4 = Disabled/Blocked Case/Payer, 5 = Customer Initiated, 6 = Other.", "format": "int32", "example": 5 }, "cancelReasonText": { "type": "string", "description": "Additional free-text details for the cancellation reason.", "example": "Customer requested cancellation by phone." } } }, "RecurringCancelResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "message": { "type": "string", "description": "Response message." }, "cancelledAt": { "type": "string", "description": "Date and time when the recurring payment cancellation was processed.", "format": "date-time" } } }, "AttributeValue": { "type": "object", "properties": { "attribute": { "type": "string" }, "value": { "type": "string" } } }, "Address": { "required": [ "city", "countryCode", "postalCode", "state", "street1" ], "type": "object", "properties": { "street1": { "type": "string", "description": "Address line 1" }, "street2": { "type": "string", "description": "Address line 2" }, "city": { "type": "string", "description": "City" }, "postalCode": { "type": "string", "description": "Zip/Postal code" }, "state": { "type": "string", "description": "State/Province" }, "countryCode": { "type": "string", "description": "Country Code" } }, "description": "Payer address information." }, "Customer": { "type": "object", "properties": { "username": { "type": "string", "description": "Username" }, "phone": { "type": "string", "description": "Primary phone number" }, "phone2": { "type": "string", "description": "Secondary phone number" }, "company": { "type": "string", "description": "Company name" }, "email": { "type": "string", "description": "Email address" }, "fax": { "type": "string", "description": "Fax number" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "middleName": { "type": "string", "description": "Middle name" }, "ip": { "type": "string", "description": "IP address" }, "deviceFingerprint": { "type": "string", "description": "Device fingerprint" }, "identities": { "type": "array", "description": "Extra identity information needed when grand total is $3000 or more", "items": { "$ref": "#/components/schemas/CustomerIdentity" } }, "employer": { "type": "boolean", "description": "Indicates whether or not you are an employer" }, "employerFein": { "type": "string", "description": "Employer FEIN" } }, "description": "Customer information." }, "Payment": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of payment method.", "enum": [ "creditcard", "echeck" ] }, "shopperPaymentInfo": { "type": "object", "additionalProperties": { "type": "object", "description": "Payment details for the selected payment type.\n\nFor creditcard, provide:\n- encryptedCardNumber\n- encryptedSecurityCode\n- encryptedExpiryMonth\n- encryptedExpiryYear\n- cardHolderName\n\nFor echeck, provide:\n- accountNumber\n- routingNumber\n- either firstName and lastName, or businessName" }, "description": "Payment details for the selected payment type.\n\nFor creditcard, provide:\n- encryptedCardNumber\n- encryptedSecurityCode\n- encryptedExpiryMonth\n- encryptedExpiryYear\n- cardHolderName\n\nFor echeck, provide:\n- accountNumber\n- routingNumber\n- either firstName and lastName, or businessName" }, "storePaymentMethod": { "type": "boolean", "description": "Whether the entered payment method should be stored for future use. If true and subscriptionId is not provided, a new subscriptionId is created during payment processing." } }, "description": "Payment information used to process a transaction.\n\nUse payment.type to indicate the payment method.\n\nIf using a stored payment method, provide storedPaymentMethodId in the request and do not provide shopperPaymentInfo.\n\nIf not using a stored payment method, provide shopperPaymentInfo based on payment.type.\n\nSupported payment.type values in this document:\n- creditcard\n- echeck" }, "PaymentRequest": { "required": [ "payment" ], "type": "object", "properties": { "items": { "type": "array", "description": "List of items to be paid. Do not include this field when the request is intended only for payment method tokenization.", "items": { "$ref": "#/components/schemas/Item" } }, "address": { "$ref": "#/components/schemas/Address" }, "customer": { "$ref": "#/components/schemas/Customer" }, "payment": { "$ref": "#/components/schemas/Payment" }, "storedPaymentMethodId": { "type": "string", "description": "Identifier of a previously stored payment method, such as a credit card or bank account. When provided, the payment is processed using the stored payment method." }, "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the customer and payment method. Provide this field to use an existing subscription. If storePaymentMethod is true and this field is not provided, a new subscriptionId is created during payment processing." } }, "description": "Request used to process a payment transaction.\n\nProvide payment information in the payment object.\n\nIf using a stored payment method, provide storedPaymentMethodId and do not provide shopperPaymentInfo.\n\nIf not using a stored payment method, provide shopperPaymentInfo based on payment.type.\n\nInclude items when processing a payment.\n\nDo not include items when the request is intended only for payment method tokenization.\n\nIf storePaymentMethod is true and subscriptionId is not provided, a new subscriptionId is created during payment processing and returned in the response.\n\nIf subscriptionId is provided, the payment method is associated with the existing subscription." }, "PaymentResponse": { "type": "object", "properties": { "orderId": { "type": "integer", "description": "Unique identifier of the payment transaction.", "format": "int64" }, "paymentTimestamp": { "type": "string", "description": "Date and time when the payment transaction was processed.", "format": "date-time" }, "amount": { "type": "number", "description": "Base payment amount for the transaction, excluding fees." }, "feeAmount": { "type": "number", "description": "Fee amount applied to the transaction." }, "totalAmount": { "type": "number", "description": "Total amount charged for the transaction, including fees." }, "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the customer. Returned when an existing subscription is used, or when a new subscriptionId is created because storePaymentMethod is true and subscriptionId was not provided in the request." }, "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method. Returned when storePaymentMethod is true and the payment method is successfully stored." }, "status": { "type": "string", "description": "Status of the payment transaction.", "example": "Success", "enum": [ "Success", "Refused", "Failed", "Cancelled", "PendingPayment", "PendingSettle", "Review" ] }, "errorMessage": { "type": "string", "description": "Error message returned when the transaction fails." }, "errorDetails": { "type": "string", "description": "Detailed error information for troubleshooting purposes." }, "storePaymentMethodStatus": { "type": "string", "description": "Status of storing the payment method. Returned only when storePaymentMethod is true in the request.", "example": "success", "enum": [ "success", "failed" ] }, "retry": { "type": "boolean", "description": "Indicates whether the payment attempt can be retried.", "example": true } }, "description": "Response returned after a payment transaction is processed.\n\nFor successful payments, orderId and status are returned.\n\nIf the payment method was requested to be stored, storePaymentMethodStatus indicates whether the payment method was stored successfully.\n\nIf the transaction fails, errorMessage and errorDetails may be returned.\n\nretry indicates whether the payment attempt can be retried." }, "OrderPaymentInfo": { "type": "object", "properties": { "paymentMethod": { "type": "string", "description": "Payment method used in the order.", "enum": [ "Unkown", "CreditCard", "BankAccount", "BillingAccount", "ApplePay", "GooglePay", "PayPal", "WeChat", "AliPay", "PointOfSale", "Venmo", "Cash" ] }, "cardHolderName": { "type": "string", "description": "Card holder name when payment is made by card." }, "cardSummary": { "type": "string", "description": "Masked card number summary shown to the customer." }, "cardType": { "type": "string", "description": "Card brand or type, for example Visa or MasterCard." }, "expiryDate": { "type": "string", "description": "Card expiration date in display format." }, "bankAccountSummary": { "type": "string", "description": "Masked bank account summary when payment is made by bank account." }, "bankAccountName": { "type": "string", "description": "Name on the bank account used for payment." } }, "description": "Details about the payment instrument used to complete the order." }, "ReceiptItem": { "type": "object", "properties": { "orderItemId": { "type": "integer", "format": "int64", "description": "Unique identifier of the item in the order." }, "skuLabel": { "type": "string", "description": "Display label of the SKU attribute." }, "skuValue": { "type": "string", "description": "Value of the SKU attribute." }, "description": { "type": "string", "description": "Description of the billed line item." }, "amount": { "type": "number", "description": "Monetary amount for this line item." }, "quantity": { "type": "integer", "format": "int32", "description": "Quantity billed for this line item." }, "itemKey": { "type": "string", "description": "Unique item key associated with this line item." }, "itemName": { "type": "string", "description": "Display name of the billed item." }, "attributes": { "type": "array", "description": "Additional attributes associated with this receipt line item.", "items": { "$ref": "#/components/schemas/ItemAttribute" } } }, "description": "Line item details included in the receipt." }, "ReceiptModel": { "type": "object", "properties": { "orderId": { "type": "integer", "format": "int64", "description": "Unique identifier of the order." }, "orderDate": { "type": "string", "format": "date-time", "description": "Date and time when the order was created." }, "paymentAmount": { "type": "number", "description": "Total paid amount for the order." }, "partnerName": { "type": "string", "description": "Name of the partner or agency receiving payment." }, "shopperStatement": { "type": "string", "description": "Statement text shown to the customer for this payment." }, "paymentItems": { "type": "array", "description": "List of primary payment items included in the receipt.", "items": { "$ref": "#/components/schemas/ReceiptItem" } }, "feeItems": { "type": "array", "description": "List of fee-related items included in the receipt.", "items": { "$ref": "#/components/schemas/ReceiptItem" } }, "customer": { "$ref": "#/components/schemas/Customer", "description": "Customer information associated with the order." }, "paymentInfo": { "$ref": "#/components/schemas/OrderPaymentInfo", "description": "Payment method details used to complete the order." }, "review": { "type": "boolean", "description": "Indicates whether the order requires manual review." }, "disclaimers": { "type": "array", "description": "List of disclaimer messages shown on the receipt.", "items": { "type": "string" } }, "emailSubject": { "type": "string", "description": "Subject line used when the receipt is sent by email." } }, "description": "Receipt details returned for an order." }, "Order": { "type": "object", "properties": { "orderId": { "type": "integer", "format": "int64", "description": "Unique identifier of the order." }, "orderDate": { "type": "string", "format": "date-time", "description": "Date and time when the order was created." }, "authorizeAmount": { "type": "number", "description": "Total authorized amount for the order." }, "paymentAmount": { "type": "number", "description": "Total paid amount for the order." }, "refundAmount": { "type": "number", "description": "Total refunded amount for the order." }, "refundBalance": { "type": "number", "description": "Remaining refundable balance for the order." }, "status": { "type": "string", "description": "Current status of the order." }, "paymentItems": { "type": "array", "description": "List of payment items associated with the order.", "items": { "$ref": "#/components/schemas/OrderItem" } }, "feeItems": { "type": "array", "description": "List of fee items associated with the order.", "items": { "$ref": "#/components/schemas/OrderItem" } }, "customer": { "$ref": "#/components/schemas/Customer", "description": "Customer information associated with the order." }, "paymentInfo": { "$ref": "#/components/schemas/OrderPaymentInfo", "description": "Payment method details used for the order." }, "subscriptionId": { "type": "string", "description": "Subscription identifier associated with this order, when applicable." } }, "description": "Order details returned for an orderId." }, "OrderItem": { "type": "object", "properties": { "itemId": { "type": "integer", "format": "int64", "description": "Unique identifier of the item." }, "itemKey": { "type": "string", "description": "Unique key of the item." }, "name": { "type": "string", "description": "Display name of the item." }, "description": { "type": "string", "description": "Description of the item." }, "orderItemId": { "type": "integer", "format": "int64", "description": "Unique identifier of the item entry within the order." }, "sku": { "type": "string", "description": "SKU value for the item." }, "instanceId": { "type": "string", "description": "Instance identifier for the item." }, "type": { "type": "string", "description": "Type classification of the item.", "enum": [ "INVALID", "GENERAL", "TAX", "FEE", "DISCOUNT", "ENGINE" ] }, "authorizeAmount": { "type": "number", "description": "Authorized amount for the item." }, "paymentAmount": { "type": "number", "description": "Paid amount for the item." }, "refundAmount": { "type": "number", "description": "Refunded amount for the item." }, "refundBalance": { "type": "number", "description": "Remaining refundable balance for the item." }, "attributes": { "type": "array", "description": "Additional attributes for the item.", "items": { "$ref": "#/components/schemas/ItemAttribute" } } }, "description": "Order item details returned as part of the order response." }, "PaymentMethodsRequest": { "required": [ "amount", "itemKey" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier used to retrieve stored payment methods. If not provided, only generally available payment methods are returned." }, "itemKey": { "type": "string", "description": "Unique item key used to determine the applicable payment methods and fees." }, "amount": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "Payment amount used to determine the applicable fees for various payment methods.", "example": 25.5 } } }, "PaymentMethod": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the payment method.", "example": "Credit Card" }, "type": { "type": "string", "description": "Type of payment method, such as creditcard, echeck, googlepay, or applepay.", "example": "creditcard" }, "totalAmount": { "type": "number", "description": "Total payment amount for the transaction, including any applicable fee.", "example": 10.35 }, "config": { "type": "object", "additionalProperties": { "type": "string", "description": "Configuration properties for the payment method as key-value pairs." }, "description": "Configuration properties for the payment method as key-value pairs." }, "fee": { "$ref": "#/components/schemas/PaymentMethodFee" } }, "description": "List of payment methods available for processing the payment." }, "PaymentMethodFee": { "type": "object", "properties": { "itemKey": { "type": "string", "description": "Unique identifier of the fee item." }, "name": { "type": "string", "description": "Display name of the fee." }, "description": { "type": "string", "description": "Description of the fee." }, "amount": { "type": "number", "description": "Calculated fee amount for the request.", "example": 1.25 } }, "description": "Fee information associated with the stored payment method type." }, "PaymentMethodsResponse": { "type": "object", "properties": { "environment": { "type": "string", "description": "Payment environment.", "example": "test", "enum": [ "test", "prod" ] }, "paymentMethods": { "type": "array", "description": "List of payment methods available for processing the payment.", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "storedPaymentMethods": { "type": "array", "description": "List of stored payment methods available for the subscription.", "items": { "$ref": "#/components/schemas/StoredPaymentMethod" } } } }, "SavedPaymentInfo": { "type": "object", "properties": { "summary": { "type": "string", "description": "Summary that describes the specific payment." }, "reference": { "type": "string", "description": "ReferenceId that identifies this specific saved payment method." }, "expiresOn": { "type": "string", "description": "Expiration date for a credit card." }, "expired": { "type": "boolean", "description": "Expiration flag to alert the user that a credit card has expired." } }, "description": "List of stored payment methods available for the provided subscription." }, "StoredPaymentMethod": { "type": "object", "properties": { "storedPaymentMethodId": { "type": "string", "description": "Identifier of the stored payment method." }, "name": { "type": "string", "description": "Display name of the stored payment method.", "example": "Visa ending in 1234" }, "type": { "type": "string", "description": "Type of payment method, such as creditcard or echeck.", "example": "creditcard" }, "totalAmount": { "type": "number", "description": "Total payment amount for the transaction, including any applicable fee.", "example": 10.35 }, "fee": { "$ref": "#/components/schemas/PaymentMethodFee" } }, "description": "List of stored payment methods available for the subscription." }, "RecurringHistoryRequest": { "required": [ "recurringId", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." } } }, "RecurringHistoryDetails": { "type": "object", "properties": { "orderId": { "type": "integer", "description": "Recurring payment Order Id.", "format": "int64" }, "orderStatus": { "type": "string", "description": "Status of the recurring payment order." }, "amount": { "type": "number", "description": "Recurring payment amount." }, "orderDate": { "type": "string", "description": "Date and time when the order was created.", "format": "date-time" }, "settleDate": { "type": "string", "format": "date-time", "description": "Date and time when the order was settled." }, "errorMessage": { "type": "string", "description": "Error message returned if processing the recurring payment failed." }, "recurringFrequency": { "type": "string", "description": "Configured frequency of the recurring payment.", "enum": [ "daily", "weekly", "monthly", "bi_weekly", "bi_monthly", "annually" ] }, "scheduledPaymentDate": { "type": "string", "description": "Scheduled date for the recurring payment.", "format": "date" }, "paymentMethod": { "type": "string", "description": "Payment method used for the recurring transaction." }, "lastFourAccount": { "type": "string", "description": "Last four digits of the account or card used for payment." } }, "description": "List of all the recurring payments associated with subscriptionId and recurringId." }, "RecurringHistoryResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Unique subscription identifier associated with the recurring payment." }, "recurringId": { "type": "string", "description": "Unique identifier of the recurring payment." }, "paymentHistory": { "type": "array", "description": "List of all the recurring payments associated with subscriptionId and recurringId.", "items": { "$ref": "#/components/schemas/RecurringHistoryDetails" } }, "httpStatusCode": { "type": "integer", "description": "HTTP status code.", "format": "int32" }, "responseTimestamp": { "type": "string", "description": "Date and time when the response was generated.", "format": "date" }, "item": { "$ref": "#/components/schemas/PaymentItem", "description": "Recurring item details." } } }, "PaymentItem": { "type": "object", "properties": { "itemKey": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "instanceId": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAttribute" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the JWT access token issued by the TPE Auth server. Obtain a token via the TPE Auth API (see https://civitek.github.io/open-api-docs/tpe-auth.html) then include it as: Authorization: Bearer " } } } }