openapi: 3.2.0
info:
title: api Sales API
version: '1.0'
servers:
- url: https://sandboxsalesapi.connexpay.com
security:
- sec0: []
tags:
- name: Sales
paths:
/api/v1/sales/UpdateFutureSale:
post:
summary: Update Delayed Sale
description: Updates the sale amount or activation date on a delayed activation sale.
operationId: update-delayed-sale
parameters:
- name: Content-Type
in: header
description: '"application/json"'
schema:
type: string
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- DeviceGuid
- SaleGuid
- Amount
properties:
DeviceGuid:
type: string
description: Device's Guid provided by ConnexPay.
SaleGuid:
type: string
description: Sales's Guid that was provided by ConnexPay upon initial creation of the delayed activation sale.
Amount:
type: number
description: 'Amount of the transaction that will be processed. Note: this value is submitted multiple times (in different formats) within the integration to support different purposes i.e. risk analysis, merchant processing, etc. The minimun amount is: $0.50.'
format: float
ActivationDate:
type: string
description: Set a future date on which to run this sale, at least one day from creation date and within 600 days.
format: date
responses:
'200':
description: '200'
content:
application/json:
examples:
Update Delayed Sale Response Example:
value: "{\n \"guid\":\"965a67b0-cd0e-4020-973b-5e0d1b4bd6e2\",\n \"status\":\"Transaction - Approved\",\n \"type\":\"Default\",\n \"batchStatus\":\"Batch - Open\",\n \"timeStamp\":\"2019-11-20T05:37:13.22-05:00\",\n \"deviceGuid\":\"f758a448-7780-4b50-93a1-28329e37f94f\",\n \"amount\":280.0,\n \"activationDate\":\"2020-10-12T00:00:00\",\n \"activated\":false, \n \"tenderType\":\"Credit\",\n \"effectiveAmount\":280.0,\n \"orderNumber\":\"159874\",\n \"cardDataSource\":\"INTERNET\",\n \"customerID\":\"xt147\",\n \"batchGuid\":\"c71d0ee6-b595-4792-b1ee-1156d28be132\",\n \"riskProcessingOnly\":false,\n \"processorStatusCode\":\"A0000\",\n \"processorResponseMessage\":\"Success\",\n \"wasProcessed\":true,\n \"generatedBy\":\"tcformal1\",\n \"card\":{\n \"first4\":\"4716\",\n \"last4\":\"0473\",\n \"cardNumber\":\"CARD NOT TOKENIZED\",\n \"cardHolderName\":\"John Doe\",\n \"cardType\":\"Visa\",\n \"expirationDate\":\"2019-12\",\n },\n \"sequenceNumber\":\"849741\",\n \"addressVerificationResult\":\"No match. Acquirer sent postal/ZIP code only, or street address only, or both postal/ZIP and street address.\",\n \"cvvVerificationCode\":\"M\",\n \"cvvVerificationResult\":\"CVV2 Match. Indicates that the Funds Transfer API or the issuer was able to verify the CVV2 value provided by the merchant.\"\n \"incomingTransactionCode\":\"09ASECYE48S9KHBQL00028000\"\n }"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Sales
/api/v1/sales/Activate/{SaleGuid}:
put:
summary: Activate Delayed Sale
description: 'Activate a delayed activation sale independent of the activation date for which the sale was created.
A client can "Activate" a delayed activation sale this way at any time before ConnexPay will automatically activate it during the early hours of the supplied future date.'
operationId: activate-delayed-sale
parameters:
- name: SaleGuid
in: path
description: The sale guid returned upon initial creation of the delayed activation sale.
schema:
type: string
required: true
- name: Content-Type
in: header
description: '"application/json"'
schema:
type: string
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Sales
/api/v1/sales/group:
post:
summary: Create Group
description: This endpoint creates a Sale Group. This is the first step to create group sales. To add any Sale to this newly created group, the response GroupGuid needs to be used with the Sale request.
operationId: create-group-sale
parameters:
- name: Content-Type
in: header
description: '"application/json"'
schema:
type: string
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- DeviceGuid
- GroupId
properties:
DeviceGuid:
type: string
description: Device's Guid provided by ConnexPay.
GroupId:
type: string
description: Group ID you choose to associate with the group
ExpectedNumberOfCards:
type: integer
description: Number of virtual credit cards you expect to issue
format: int32
GroupName:
type: string
description: Optional group name you can assign to the group.
examples:
Create Group Sale Request Example:
value:
DeviceGuid: 0b7a9536-9fcd-4074-a841-d47eef77b81b
GroupId: Test-Sale-Group-1
ExpectedNumberOfCards: 3
GroupName: Test Sale Group
responses:
'200':
description: '200'
content:
application/json:
examples:
Create Group Sale Response Example:
value: "{\n \"deviceGuid\": \"0b7a9536-9fcd-4074-a841-d47eef77b81b\",\n \"guid\": \"727374dd-f4dc-43ab-b49f-bc5deb1c4bcd\",\n \"groupId\": \"Test-Sale-Group-1\",\n \"status\": \"Open\",\n \"balance\": 0.00,\n \"groupName\": \"Test Sale Group\",\n \"incomingTransactionCode\": \"03MRDILHU3LV0EOQQ00000GRP\"\n}"
schema:
type: object
properties:
deviceGuid:
type: string
example: 0b7a9536-9fcd-4074-a841-d47eef77b81b
guid:
type: string
example: 727374dd-f4dc-43ab-b49f-bc5deb1c4bcd
groupId:
type: string
example: Test-Sale-Group-1
status:
type: string
example: Open
balance:
type: integer
example: 0
default: 0
groupName:
type: string
example: Test Sale Group
incomingTransactionCode:
type: string
example: 03MRDILHU3LV0EOQQ00000GRP
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Sales
/api/v1/sales/group/{GroupGuid}:
put:
summary: Update Group
description: This endpoint allows to update an existing sale group by setting the group status as Closed or changing the GroupName.
operationId: update-group-sale
parameters:
- name: GroupGuid
in: path
description: Sale Group Guid (required)
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- DeviceGuid
properties:
DeviceGuid:
type: string
description: Device Guid provided by ConnexPay
Status:
type: string
description: Group status to update to. Only closing a sale group is allowed now, e.g. 1301 or "GroupClosed".
GroupName:
type: string
description: GroupName to update to. Allowed only alphanumeric characters between 1-100.
examples:
Update Group Sale Request Example:
value:
DeviceGuid: 0b7a9536-9fcd-4074-a841-d47eef77b81b
Status: 1301
GroupName: Test Sale Group
responses:
'200':
description: '200'
content:
application/json:
examples:
Update Group Sale Response Example:
value: "{\n \"deviceGuid\": \"f758a448-7780-4b50-93a1-28329e37f94f\",\n \"guid\": \"48b9520c-803e-467e-bb95-38925d6f4766\",\n \"groupId\": \"saiful-group-1\",\n \"status\": \"Closed\",\n \"idStatus\": 1301,\n \"balance\": 200.00,\n \"groupName\": \"Test Sale Group\",\n \"incomingTransactionCode\": \"03MRDILHU3LV0EOQQ00000GRP\"\n}"
schema:
type: object
properties:
deviceGuid:
type: string
example: f758a448-7780-4b50-93a1-28329e37f94f
guid:
type: string
example: 48b9520c-803e-467e-bb95-38925d6f4766
groupId:
type: string
example: saiful-group-1
status:
type: string
example: Closed
idStatus:
type: integer
example: 1301
default: 0
balance:
type: integer
example: 200
default: 0
groupName:
type: string
example: Test Sale Group
incomingTransactionCode:
type: string
example: 03MRDILHU3LV0EOQQ00000GRP
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Sales
/api/v1/sales/group/{guid}:
get:
summary: Get Group
description: This endpoint returns group sale info, including Status and Group Balance
operationId: get-group-sale
parameters:
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
- name: guid
in: path
description: Group’s guid to get.
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Get Group Sale Response Example:
value: "{\n \"deviceGuid\": \"f758a448-7780-4b50-93a1-28329e37f94f\",\n \"guid\": \"9c018683-05f9-47d3-b4c1-4d1ccae4a91e\",\n \"groupId\": \"saiful-group-8\",\n \"expectedNumberOfCards\": 1,\n \"status\": \"Closed\",\n \"idStatus\": 1301,\n \"balance\": 100.00,\n \"groupName\": \"SG-8\",\n \"incomingTransactionCode\": \"01QR5AZA7D454PQCD00000GRP\"\n}"
schema:
type: object
properties:
deviceGuid:
type: string
example: f758a448-7780-4b50-93a1-28329e37f94f
guid:
type: string
example: 9c018683-05f9-47d3-b4c1-4d1ccae4a91e
groupId:
type: string
example: saiful-group-8
expectedNumberOfCards:
type: integer
example: 1
default: 0
status:
type: string
example: Closed
idStatus:
type: integer
example: 1301
default: 0
balance:
type: integer
example: 100
default: 0
groupName:
type: string
example: SG-8
incomingTransactionCode:
type: string
example: 01QR5AZA7D454PQCD00000GRP
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Sales
/api/v1/sales:
post:
summary: Create Sale
description: The Create Sale Endpoint is used by acquiring clients. The Sale transaction is used to create a sale for your consumer. You can create a credit sale or an ACH sale (ACH sales apply to US Clients only). A credit sale will charge a consumer's credit card. The consumer's credit card will be authorized immediately when the Sales request is received and will automatically settle/batch that same night. In other words, this one Sale request is just like running an AuthOnly and a Capture in one request.You can postpone charging the consumer's credit card by providing a date in the 'ActivationDate' of your request. Doing so will delay the authorization and charge to the consumer's credit card until that future date.An ACH sale will create an ACH transaction that will debit the consumer's bank account. ACH sales received prior to 3:00 PM EST will process overnight. ACH Sales received after 3:00 PM EST will process the following night.
operationId: getting-started-with-your-api
parameters:
- name: Content-Type
in: header
description: Content-Type Header
schema:
type: string
default: '"application/json"'
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
default: Bearer Token
requestBody:
content:
application/json:
schema:
type: object
required:
- DeviceGuid
- Amount
- ConnexPayTransaction
- RiskData
properties:
DeviceGuid:
type: string
description: Device's Guid provided by ConnexPay
default: '{{Device}}'
Amount:
type: number
description: 'Amount of the transaction that will be processed. Note: this value is submitted multiple times (in different formats) within the integration to support different purposes i.e. risk analysis, merchant processing, etc. The minimum amount is: $0.50.'
default: null
format: float
TenderType:
type: string
description: 'Allowed values: "credit" (default if TenderType not provided) and "ach"'
default: credit
SequenceNumber:
type: string
description: 'Transaction sequence number within client environment. Provide a unique SequenceNumber for each new request. If a sale request with the same parameter data and the same sequence number is sent within 30 minutes it will be considered a duplicate request and the sale will not process. Note: value is not searchable or reportable in Bridge. The maximum length is 100 alpha-numeric characters.'
default: '{{SequenceNumber}}'
OrderNumber:
type: string
description: 'A value that is commonly used for reporting on and reconciling your PayIns and PayOuts. The Order Number is searchable in the ConnexPay Bridge and referenced in Analytics and reporting, and can be any identifier within your environment to associate with the sale or payment, such as a Record Locator, PNR, or transaction ID. The maximum length is 50 alpha-numeric characters and allows the following special characters: period, underscore, backslash, dash, and space [._ /- ].'
default: '{{OrderNumber}}'
SendReceipt:
type: boolean
description: Value determines whether or not a customer shall be emailed a receipt from the ConnexPay platform if the email address is provided in the API customer block. The default value is TRUE. Set to FALSE so that an email receipt is not sent to the customer. Set to TRUE or leave empty if you want e-mail to be sent. If TRUE, customer's email must be included in the "Card.Customer.email" parameter.
RiskProcessingOnly:
type: boolean
description: 'Indicator that determines if client would like to evaluate the transactions as risk only rather than process as merchant of record and create a virtual card. The allowed values: 1. Set to TRUE will only run risk validations. If TenderType is not set to Credit, setting TRUE will throw a validation error. 2. Set to FALSE will run risk validations and an authorization on the card. For this option a Processing Merchant account is required, contact ConnexPay support if any questions. 3. Set to NULL and your Merchant Level settings would apply.'
StatementDescription:
type: string
description: 'US, CA, and EU clients only: The statement description allows you to customize the merchant name that appears on the cardholder''s statement for the transaction. We recommend including your DBA name along with identifying details such as a travel PNR (e.g., "ABC Travel ABC123") to help cardholders recognize the charge. Maximum length is 25 alpha-numeric characters for US clients; for CA clients, 18 alpha-numeric characters is the maximum and ConnexPay will automatically prefix the result with "CXP*"; for EU clients, 22 alpha-numeric characters is the maximum however up to 13 numeric characters may be added for phone number after the DBA name if an asterisk is used in-between the values. No spaces are allowed and the only allowed special characters are: period, dash, and asterisk [.-*]. This functionality is not available for American Express programs.'
default: '{{StatementDescription}}'
CustomerID:
type: string
description: 'Transaction ID within client environment associated with the customer. This value acts as a secondary identifier in conjunction with OrderNumber. The value is searchable and reportable in the ConnexPay portal. This value may be sent in multiple times within the integration for multiple purposes. The maximum length is 100 alpha-numeric characters and the following special characters: period, underscore, backslash, dash, and space [._ /- ].'
ActivationDate:
type: string
description: Set a future date on which to run this sale, at least one day from creation date and within 600 days. If this parameter is supplied a record for this sale is created, supplied consumer card information is internally tokenized, but fraud check and authorization do not occur until ConnexPay processes it on the supplied ActivationDate. Alternatively, a client can force activation via the Activate API (see below). If this date is not supplied a sale is authorized and the consumer's credit card is charged immediately.
format: date
RequestIp:
type: string
description: Mandatory if TenderType is ACH. Customer's IP Address is a required parameter for all ACH Sales transactions to adhere to NACHA regulations.
ConnexPayTransaction:
type: object
description: ConnexPay Transaction
required:
- ExpectedPayments
properties:
ExpectedPayments:
type: integer
description: This is the number of outbound payments that will be made to suppliers. If paying a single supplier the value is 1, if paying two suppliers the value is 2, etc. If no outbound payments will be made, set to 0.
format: int32
RiskData:
type: object
description: Mandatory if TenderType is Credit or not set. This will be ignored if TenderType is Cash or ACH
properties:
SessionId:
type: string
description: If you are using Equifax's Device Data Collector, this would be the SessionId from that particular session. Do not include this property if not using Equifax's Device Data Collector.
Name:
type: string
description: 'This is the name of the individual making the purchase i.e. cardholder who may or may not also be the customer. This value is submitted in multiple integration points for different purposes. This value/object is specific to fraud mitigation. Note: for airline ticket purchases this value may or may not be the same as the passenger. Max = 64 characters.'
Gender:
type: string
description: Cardholder gender. "M" or "F".
DateOfBirth:
type: string
description: Cardholder date of birth
BillingPhoneNumber:
type: string
description: Phone number associated with cardholder making purchase. This could be used for risk analysis, decisioning, and rule creation. Max = 15 characters. Numbers and plus sign (+) allowed.
BillingAddress1:
type: string
description: Cardholder billing address 1. This could be used for risk analysis, decisioning, and rule creation.
BillingAddress2:
type: string
description: Cardholder billing address 2. This could be used for risk analysis, decisioning, and rule creation.
BillingCity:
type: string
description: Cardholder billing city. This could be used for risk analysis, decisioning, and rule creation.
BillingState:
type: string
description: Cardholder billing state. This could be used for risk analysis, decisioning, and rule creation.
BillingPostalCode:
type: string
description: Cardholder billing postal code. This could be used for risk analysis, decisioning, and rule creation. Max = 15 characters. Alphanumerics and "-" allowed.
BillingCountryCode:
type: string
description: Cardholder billing country code. This could be used for risk analysis, decisioning, and rule creation. Max = 2 characters.
Email:
type: string
description: Cardholder's valid email address. This could be used for risk analysis, decisioning, and rule creation.
ProductType:
type: string
description: Generalized description of the item added passed as plain text. This could be flight, tour, hotel, etc. (This is part of shopping cart information in Kount 360). Each transaction submitted for risk analysis and decisioning must be submitted with one shopping cart item.
ProductDescription:
type: string
description: Attribute for a specific description of the item being purchased i.e. airline ticket. This information is general shopping cart information that describes the type of item being purchased. ConnexPay suggests clients submitted a high level description such as Flight, Hotel, Car Rental, etc... and leverage custom parameters to submit more detailed information that can be used for rule creation and transaction decisioning.
ProductItem:
type: string
description: Typically the SKU for an item passed as plain text. This information is general shopping cart information to provide secondary detail to the ProductDesc above. ConnexPay suggests clients submit a high level description such as One Way, Round Trip, Seven Nights, etc...and several customer parameters to submit more detailed information that can be used for rule creation and transaction decisioning. Field is required by Equifax therefore some value must be submitted. Alphanumeric.
ProductQuantity:
type: integer
description: Quantity of the item being purchased in the shopping cart. This is just a general quantity field.
format: int32
ProductPrice:
type: integer
description: 'Price per unit item, displayed in lowest currency factor - expressed in cents. Example: 42400 (which is $424.00).'
format: int32
OrderNumber:
type: string
description: Transaction ID within client environment associated with the order. The value is searchable and reportable in the Kount 360 portal. This value may be sent in multiple instances of the integration for multiple purposes. Customers in the travel space often send the Record Locator/PNR in this field. Max = 32 characters. Alpha-numeric characters and dashes ( - ) allowed.
SellerId:
type: string
description: Transaction ID within client environment associated with the customer. This value acts as a secondary identifier in conjunction with OrderNumber. The value is searchable and reportable in the Kount 360 portal. This value may be sent in multiple times within the integration for multiple purposes. Max = 32 characters.
FlightData:
type: object
description: Flight Data
properties:
Airline:
type: string
description: Name of airline; likely carrier code
default: AA
DepartureAirport:
type: string
description: Departure airport code
default: NY
DepartureDate:
type: string
description: 'Departure date of flight. Format: mm/dd/yyyy'
default: 06/20/1993
DestinationAirport:
type: string
description: Destination airport code
default: CA
HoursToDeparture:
type: string
description: Time in hours to flight departure
default: '5'
JourneyType:
type: string
description: Type of journey i.e. Day/Night journey
default: Day
Route:
type: string
description: The route type i.e. Direct/Indirect
default: Direct
RouteByCountry:
type: string
description: Complete flight route by country
default: NY, CA
FlightPassengers:
type: array
items:
properties:
Country:
type: string
description: Country of origin of passenger
default: USA
DateOfBirth:
type: string
description: DOB of first passenger
default: '2020-06-20'
format: date
Id:
type: string
description: Passport, drivers license or id# associated with passenger
default: JXY123
Name:
type: string
description: Passenger information. Each passenger should be sent in it's own object.
default: John Doe
type: object
CustomParameters:
type: object
description: Custom Parameters. Array.
properties: {}
Card:
type: object
description: Customer's card data. Mandatory if TenderType is Credit or not set. This will be ignored if TenderType is Cash or ACH.
properties:
CardNumber:
type: string
description: 'Mandatory if Guid field is not provided. Card number. Must be 16 characters. (example: 4532538795426624) or token (example: FfL7exC7Xe2y6624)'
CardHolderName:
type: string
description: Cardholder's name. Providing information in this field allows a user of the ConnexPay portal to search for a transaction using the cardholder name
Cvv2:
type: string
description: The three or four digit CVV code at the back side of the credit and debit card. This value is required for all card-not-present processing environments
ExpirationDate:
type: string
description: Optional with Token. Card's expiry date in the YYMM format
format: date
Guid:
type: string
description: Guid is the unique identifier for a card info generated by Connexpay upon previous Sale creation. Create Sale API will accept either card info or Guid, but not both
IsRecurring:
type: boolean
description: 'Set to
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/connexpay/refs/heads/main/openapi/connexpay-sales-api-openapi.yml