openapi: 3.2.0
info:
title: sales-api 3ds API
version: '1.0'
servers:
- url: https://sandboxsalesapi.connexpay.com
security:
- sec0: []
tags:
- name: 3ds
paths:
/api/v1/3ds:
post:
summary: 3DS Authentication
description: This endpoint can be used for obtaining 3D Secure Authentication separate from the Create Sale or Auth-Only calls. This is recommended for our US and CA clients.
operationId: 3ds-authentication
parameters:
- name: Content-Type
in: 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:
- Card
- DeviceGuid
- BrowserData
- Amount
properties:
Card:
type: object
description: Customer's card data. CardNumber and CardHolderName are required.
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: 'Flagging a transaction as "IsRecurring": true allows a recurring sale to be submitted without a valid CVV code, which is only intended for scenarios where you might be storing card data to perform repeated payments on the same card, such as a monthly subscriptions. Typically IsRecurring can be defaulted to False.'
default: false
Customer:
type: object
description: Customer data
properties:
FirstName:
type: string
description: Mandatory for ACH Sales. Min Length = 2 Max Length = 30
LastName:
type: string
description: Mandatory for ACH Sales. Min Length = 2 Max Length = 30
Phone:
type: string
description: Customer's phone number. Phone number up to 15 characters. Numbers and plus sign (+) allowed only. 3D Secure Authentication requires a valid customer email address or phone number is included.
City:
type: string
description: Customer's City
State:
type: string
description: Customer's short name state. The ISO 3166-2 CA and US state or province code of a customer. Length = 2.
Country:
type: string
description: Customer's country. The ISO country code of a customer’s country. Length = 2
Email:
type: string
description: Customer's valid email address which is available in various reports. It is critical that SendReceipt is set to FALSE so that ConnexPay does not send a receipt to the cardholder when the transaction is processed. 3D Secure Authentication requires a valid customer email address or phone number is included.
Address1:
type: string
description: 'Customer billing address 1. It is strongly recommended to send this value in a card-not-present environment such that enhanced Address Validation (AVS) can be performed on transaction and the lowest possible interchange is received on transaction. Note: only the street number value portion of address is used for enhanced AVS check'
Address2:
type: string
description: Customer billing address 2. It is strongly recommended to send this value in a card-not-present environment such that Address Validation (AVS) can be performed on transaction and the lowest possible interchange is received on transaction
Zip:
type: string
description: Customer billing postal code. It is strongly recommended to send this value in a card-not-present environment such that basic Address Validation (AVS) can be performed on transaction and the lowest possible interchange is received on transaction. Only the a standard U.S. 5 digit zip code is eligible for basic AVS check. Min Length = 2 Max Length = 15. Alphanumerics and "-" allowed.
DateOfBirth:
type: string
description: 'Customer''s date of birth. Allowed format: YYYY-MM-DD. For example: 2002-05-30'
format: date
DriversLicenseNumber:
type: integer
description: Customer's driver license number. Only letters, numbers and a hyphen is allowed
format: int32
DriversLicenseState:
type: string
description: Mandatory when DriverLicenseNumber is provided. Customer's driver license short name state. The ISO 3166-2 CA and US state or province code of a customer. Length = 2
SSN4:
type: integer
description: Last 4 of Customer's Social Security Number
format: int32
ThreeDS:
type: object
description: 'ThreeDS object is required when 3DS authentication parameters are being passed in the Sale or Auth. For US clients: the parameters are identified using the 3DS Authentication endpoint. For EU clients: the parameters are identified when a cardholder challenge and/or fingerprint authentication is required after calling the Create Sale or Auth Only endpoint with the BrowserData object details.'
properties:
SecureCode:
type: string
Cavv:
type: string
description: Cardholder authentication verification value
Version:
type: string
description: Version of 3DS being used
DirectoryServerTransactionID:
type: string
description: Unique identifier provided by the card scheme as part of 3D Secure authentication.
AcsTransactionId:
type: string
description: Unique Identifier provided by the Access Control Server of the Card Issuer.
ECI:
type: string
description: Displays the Electronic Commerce Indicator (ECI). The ECI indicates the security level of the payment information provided to the merchant. A value of 0, 1 or 2 is a Mastercard transaction. A value of 5, 6 or 7 is a Visa, American Express, Diners or Discover card.
DeviceGuid:
type: string
description: Device's Guid as assigned by ConnexPay.
default: '{{deviceGuid}}'
BrowserData:
type: object
description: BrowserData is required in order to successfully respond to a cardholder challenge of the authentication.
required:
- AcceptanceHeader
- ColorDepth
- JavaEnabled
- ScreenHeight
- ScreenWidth
- TimeZoneOffset
- Language
- RedirectURL
- UserAgentHeader
properties:
AcceptanceHeader:
type: string
description: Required. Exact content of the http accept header.
ColorDepth:
type: integer
description: Required. Value representing the bit depth of the color palette for displaying images, in bits per pixel.
format: int32
JavaEnabled:
type: boolean
description: True or False response that represents ability of cardholder browser to execute Java
ScreenHeight:
type: integer
description: Total height of the Cardholder's screen in pixels
format: int32
ScreenWidth:
type: integer
description: Total width of the Cardholder's screen in pixels
format: int32
TimeZoneOffset:
type: integer
description: Time Zone difference between browser time zone and UTC time, in hours. Can be positive or negative.
format: int32
Language:
type: string
description: Value representing the browser language as defined in IETF BCP47
RedirectURL:
type: string
description: The merchant URL to which the browser should be redirected after the challenge session.
UserAgentHeader:
type: string
description: Exact content of the HTTP user-agent header.
Amount:
type: number
description: Amount of the transaction being 3DS authenticated
default: null
format: float
responses:
'200':
description: '200'
content:
application/json:
examples:
3DS Frictionless Response Example:
value: "{\n \"guid\": \"74fb35e7-3b41-427a-969b-1fc42a35fb11\",\n \"status\": \"3DS - Approved\",\n \"timeStamp\": \"2023-08-16T16:40:29.6401705Z\",\n \"deviceGuid\": \"e639a1dc-5cc4-43de-ab74-d5bea6c6b107\",\n \"amount\": 0.0,\n \"threeDSStatus\": \"Y\",\n \"SecureData\": \"06:3030303030303030303030313130363639393458:none\",\n \"Cavv\": \"MDAwMDAwMDAwMDAxMTA2Njk5NFg=\",\n \"Version\": \"2.1.0\",\n \"DirectoryServerTransactionID\": \"5066e271-4752-4445-a025-235c7789c151\",\n \"AcsTransactionId\": \"09a291d3-92b5-4354-b31a-5446409444f3\",\n \"ECI\": \"06\",\n \"card\": { \n \"first6\": \"401881\",\n \"first4\": \"4018\",\n \"last4\": \"0036\",\n \"cardHolderName\": \"Jason Harmon\",\n \"cardType\": \"Visa\",\n \"expirationDate\": \"2023-12\",\n \"guid\": \"c3398555-e4c0-43da-b3ca-6abc475b79b9\"\n },\n \"exemptThreeDSRequest\": false,\n \"exemptThreeDSPayment\": false\n}"
schema:
type: object
properties:
guid:
type: string
example: 74fb35e7-3b41-427a-969b-1fc42a35fb11
status:
type: string
example: 3DS - Approved
timeStamp:
type: string
example: '2023-08-16T16:40:29.6401705Z'
deviceGuid:
type: string
example: e639a1dc-5cc4-43de-ab74-d5bea6c6b107
amount:
type: integer
example: 0
default: 0
threeDSStatus:
type: string
example: Y
SecureData:
type: string
example: 06:3030303030303030303030313130363639393458:none
Cavv:
type: string
example: MDAwMDAwMDAwMDAxMTA2Njk5NFg=
Version:
type: string
example: 2.1.0
DirectoryServerTransactionID:
type: string
example: 5066e271-4752-4445-a025-235c7789c151
AcsTransactionId:
type: string
example: 09a291d3-92b5-4354-b31a-5446409444f3
ECI:
type: string
example: '06'
card:
type: object
properties:
first6:
type: string
example: '401881'
first4:
type: string
example: '4018'
last4:
type: string
example: '0036'
cardHolderName:
type: string
example: Jason Harmon
cardType:
type: string
example: Visa
expirationDate:
type: string
example: 2023-12
guid:
type: string
example: c3398555-e4c0-43da-b3ca-6abc475b79b9
exemptThreeDSRequest:
type: boolean
example: false
default: true
exemptThreeDSPayment:
type: boolean
example: false
default: true
'202':
description: '202'
content:
application/json:
examples:
3DS Device Fingerprint Response Example:
value: "{\n \"guid\": \"3a0d533f-588b-4ce4-920f-7bc4641ea8f7\",\n \"status\": \"3DS - Pending Fingerprint\",\n \"timeStamp\": \"2023-08-16T16:44:40.9866697Z\",\n \"deviceGuid\": \"e639a1dc-5cc4-43de-ab74-d5bea6c6b107\",\n \"amount\": 1.34,\n \"version\": \"2.1.0\",\n \"redirectUrl\": \"https://x3d-sim.credorax.net/acs/3ds-method\",\n \"redirectUrlRequestPayload\": \"threeDSMethodData=eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9zYWxlc2FwaS5jb25uZXhwYXlkZXYuY29tL2FwaS92MS8zZHMvY2FsbGJhY2siLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU2YmNjM2RiLTAwZjQtNDdiZi05OTgwLTljZjE2MTUxOGM5NyJ9\",\n \"card\": {\n \"first6\": \"401881\",\n \"first4\": \"4018\",\n \"last4\": \"0010\",\n \"cardHolderName\": \"Jason Harmon\",\n \"cardType\": \"Visa\",\n \"expirationDate\": \"2023-12\",\n \"guid\": \"c6b816a3-f107-40d5-9dc3-bcefc576c8bc\"\n },\n \"exemptThreeDSRequest\": false,\n \"exemptThreeDSPayment\": false\n}"
3DS Cardholder Challenge Response Example:
value: "{\n \"guid\": \"a41dd8ab-8629-42c0-8a6f-8b9162a93ccc\",\n \"status\": \"3DS - Pending User Challenge\",\n \"timeStamp\": \"2023-08-16T16:45:23.9986814Z\",\n \"deviceGuid\": \"e639a1dc-5cc4-43de-ab74-d5bea6c6b107\",\n \"amount\": 1.34,\n \"threeDSStatus\": \"C\",\n \"directoryServerTransactionID\": \"72f4afb2-c057-4abc-b054-9fae4b4ceb49\",\n \"acsTransactionId\": \"7c6670d1-d888-4af5-b5f4-db286ba6c20a\",\n \"version\": \"2.1.0\",\n \"redirectUrl\": \"https://x3d-any-int.credorax.net/challenge/request/CONN2978/2534bb4d055f10423709276026df821ff3c8\",\n \"card\": {\n \"first6\": \"401881\",\n \"first4\": \"4018\",\n \"last4\": \"0015\",\n \"cardHolderName\": \"Jason Harmon\",\n \"cardType\": \"Visa\",\n \"expirationDate\": \"2023-12\",\n \"guid\": \"2c032f47-f7ab-4849-9715-0b4bacf252a3\"\n },\n \"exemptThreeDSRequest\": false,\n \"exemptThreeDSPayment\": false\n}"
schema:
oneOf:
- title: 3DS Device Fingerprint Response Example
type: object
properties:
guid:
type: string
example: 3a0d533f-588b-4ce4-920f-7bc4641ea8f7
status:
type: string
example: 3DS - Pending Fingerprint
timeStamp:
type: string
example: '2023-08-16T16:44:40.9866697Z'
deviceGuid:
type: string
example: e639a1dc-5cc4-43de-ab74-d5bea6c6b107
amount:
type: number
example: 1.34
default: 0
version:
type: string
example: 2.1.0
redirectUrl:
type: string
example: https://x3d-sim.credorax.net/acs/3ds-method
redirectUrlRequestPayload:
type: string
example: threeDSMethodData=eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9zYWxlc2FwaS5jb25uZXhwYXlkZXYuY29tL2FwaS92MS8zZHMvY2FsbGJhY2siLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU2YmNjM2RiLTAwZjQtNDdiZi05OTgwLTljZjE2MTUxOGM5NyJ9
card:
type: object
properties:
first6:
type: string
example: '401881'
first4:
type: string
example: '4018'
last4:
type: string
example: '0010'
cardHolderName:
type: string
example: Jason Harmon
cardType:
type: string
example: Visa
expirationDate:
type: string
example: 2023-12
guid:
type: string
example: c6b816a3-f107-40d5-9dc3-bcefc576c8bc
exemptThreeDSRequest:
type: boolean
example: false
default: true
exemptThreeDSPayment:
type: boolean
example: false
default: true
- title: 3DS Cardholder Challenge Response Example
type: object
properties:
guid:
type: string
example: a41dd8ab-8629-42c0-8a6f-8b9162a93ccc
status:
type: string
example: 3DS - Pending User Challenge
timeStamp:
type: string
example: '2023-08-16T16:45:23.9986814Z'
deviceGuid:
type: string
example: e639a1dc-5cc4-43de-ab74-d5bea6c6b107
amount:
type: number
example: 1.34
default: 0
threeDSStatus:
type: string
example: C
directoryServerTransactionID:
type: string
example: 72f4afb2-c057-4abc-b054-9fae4b4ceb49
acsTransactionId:
type: string
example: 7c6670d1-d888-4af5-b5f4-db286ba6c20a
version:
type: string
example: 2.1.0
redirectUrl:
type: string
example: https://x3d-any-int.credorax.net/challenge/request/CONN2978/2534bb4d055f10423709276026df821ff3c8
card:
type: object
properties:
first6:
type: string
example: '401881'
first4:
type: string
example: '4018'
last4:
type: string
example: '0015'
cardHolderName:
type: string
example: Jason Harmon
cardType:
type: string
example: Visa
expirationDate:
type: string
example: 2023-12
guid:
type: string
example: 2c032f47-f7ab-4849-9715-0b4bacf252a3
exemptThreeDSRequest:
type: boolean
example: false
default: true
exemptThreeDSPayment:
type: boolean
example: false
default: true
'400':
description: '400'
content:
application/json:
examples:
Result:
value: ''
deprecated: false
tags:
- 3ds
/api/v1/3ds/{GUID}:
get:
summary: Get 3DS Status Group
description: This endpoint returns the 3D Secure status of an authentication when a device fingerprint and/or cardholder challenge are required for 3D Secure Authentication.
operationId: get-3ds-status-group
parameters:
- name: guid
in: path
description: Replace the original guid value with the guid that was returned with the status response indicating a device fingerprint or cardholder challenge is required to complete 3DS authentication..
schema:
type: string
required: true
- name: Content-Type
in: header
schema:
type: string
default: '"application/json"'
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Get 3DS Status Response Example:
value: "{\n \"guid\": \"34f3ae17-89c4-4bc8-b085-f46eef5af3d6\",\n \"status\": \"3DS - Approved\",\n \"timeStamp\": \"2022-12-07T14:50:18.33\",\n \"deviceGuid\": \"e639a1dc-5cc4-43de-ab74-d5bea6c6b107\",\n \"amount\": 11.35,\n \"secureData\": \"05:0099010281111100000000788400707000000000:none\",\n \"eci\": \"05\",\n \"cavv\": \"AJkBAoEREQAAAAB4hABwcAAAAAA=\",\n \"directoryServerTransactionID\": \"a52b6caa-d58e-4d72-8007-bf026acebecc\",\n \"acsTransactionId\": \"7c6670d1-d888-4af5-b5f4-db286ba6c20a\", \n \"version\": \"2.1.0\",\n \"card\": {\n \"first6\": \"401881\",\n \"first4\": \"4018\",\n \"last4\": \"0010\",\n \"cardType\": \"Visa\",\n \"expirationDate\": \"2025-12\",\n \"guid\": \"da25f77e-758a-4729-ade6-37fbbcb4675c\"\n },\n \"processorResponseCode\": \"0\",\n \"processorMessage\": \"Transaction has been executed successfully.\"\n}"
schema:
type: object
properties:
guid:
type: string
example: 34f3ae17-89c4-4bc8-b085-f46eef5af3d6
status:
type: string
example: 3DS - Approved
timeStamp:
type: string
example: '2022-12-07T14:50:18.33'
deviceGuid:
type: string
example: e639a1dc-5cc4-43de-ab74-d5bea6c6b107
amount:
type: number
example: 11.35
default: 0
secureData:
type: string
example: 05:0099010281111100000000788400707000000000:none
eci:
type: string
example: '05'
cavv:
type: string
example: AJkBAoEREQAAAAB4hABwcAAAAAA=
directoryServerTransactionID:
type: string
example: a52b6caa-d58e-4d72-8007-bf026acebecc
acsTransactionId:
type: string
example: 7c6670d1-d888-4af5-b5f4-db286ba6c20a
version:
type: string
example: 2.1.0
card:
type: object
properties:
first6:
type: string
example: '401881'
first4:
type: string
example: '4018'
last4:
type: string
example: '0010'
cardType:
type: string
example: Visa
expirationDate:
type: string
example: 2025-12
guid:
type: string
example: da25f77e-758a-4729-ade6-37fbbcb4675c
processorResponseCode:
type: string
example: '0'
processorMessage:
type: string
example: Transaction has been executed successfully.
deprecated: false
tags:
- 3ds
components:
securitySchemes:
sec0:
type: oauth2
flows: {}
x-readme:
headers: []
explorer-enabled: false
proxy-enabled: false
x-readme-fauxas: true