openapi: 3.1.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