YAML
openapi: 3.1.0
info:
title: OpenAPI definition
version: v0
servers:
- url: https://localhost:8443
description: Generated server url
paths:
/v3/authentication/{transId}:
put:
tags:
- authentication-controller
summary: Authentication service V3
description: >-
After creating the transaction, it's necessary to call the
authentication service to continue the flow. If the AUC status is
returned, a challenge must be initiated. For the AUD status, the
"decoupled" flow must be followed. Otherwise, further calls won't be
required.
operationId: doAuthenticationV3
parameters:
- name: Client-Request-Id
in: header
description: >-
UUID v4 generated following the RFC 4122 specification, unique to
each transaction.<br>Format = 26 H (UUID v4)
required: true
schema:
type: string
description: >-
UUID v4 generated following the RFC 4122 specification, unique to
each transaction.<br>Format = 26 H (UUID v4)
example: d608388f-8351-4ef7-a693-a48dc7651502
example: d608388f-8351-4ef7-a693-a48dc7651502
- name: Authorization
in: header
description: Generated HMAC signature.
required: true
schema:
type: string
description: Generated HMAC signature.
- name: Auth-Token-Type
in: header
description: Describes which Authorization type is being used.
required: true
schema:
type: string
description: Describes which Authorization type is being used.
example: HMAC
example: HMAC
- name: merchant-id
in: header
description: >-
Merchant code on 3DS Server. The production and certification codes
will be different.<br>Format < 15 AN, Mandatory YES
required: true
schema:
type: string
description: >-
Merchant code on 3DS Server. The production and certification
codes will be different.<br>Format < 15 AN, Mandatory YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: merchant-key
in: header
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
required: false
schema:
type: string
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat-merchant-id
in: header
description: >-
Carat merchant code must be sent only if the token field is sent in
the request.<br>Format < 15 AN, Mandatory COND
required: false
schema:
type: string
description: >-
Carat merchant code must be sent only if the token field is sent
in the request.<br>Format < 15 AN, Mandatory COND
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat-merchant-key
in: header
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
required: false
schema:
type: string
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
example: zzzzzzzzzzzzzz
example: zzzzzzzzzzzzzz
- name: api-key
in: header
description: HMAC key
required: true
schema:
type: string
description: HMAC key
example: xxxxxxxxxxxxxxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxxxxxxxxxxxxxx
- name: transId
in: path
description: 3DS Server Transaction ID
required: true
schema:
type: string
description: 3DS Server Transaction ID
example: zzzzzzzzzzzzzz
example: zzzzzzzzzzzzzz
requestBody:
description: Below are some examples of the authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Server3DSRootModel'
examples:
Frictionless Flow:
description: Frictionless Flow
value:
three_ds_comp_ind: 'Y'
pay_token_ind: 'false'
notification_url: https://www.requestor.com/notification
trans_type: '01'
three_ds_requestor:
authentication_ind: '01'
id: id
name: Loja de Testes
url: https://www.requestor.com
acquirer:
bin: '2'
merchant_id: '00000000'
browser:
accept_header: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip: 10.20.30.40
javascript_enabled: 'true'
java_enabled: 'false'
language: pt-BR
color_depth: '24'
screen_height: '864'
screen_width: '1536'
tz: '180'
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0)
Gecko/20100101 Firefox/75.0
cardholder:
card_expiry_date: '2212'
name: Joaquim
acct:
type: '02'
encrypted_number: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
merchant:
mcc: '1234'
country_code: BRA
name: Loja de Teste
message:
category: '01'
purchase:
amount: '10000'
currency: '986'
exponent: '2'
date: date
Challenge Flow:
description: Challenge Flow
value:
three_ds_comp_ind: 'Y'
pay_token_ind: 'false'
notification_url: https://www.requestor.com/notification
trans_type: '01'
three_ds_requestor:
authentication_ind: '01'
id: id
name: Loja de Testes
url: https://www.requestor.com
acquirer:
bin: '2'
merchant_id: '00000000'
browser:
accept_header: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip: 10.20.30.40
javascript_enabled: 'true'
java_enabled: 'false'
language: pt-BR
color_depth: '24'
screen_height: '864'
screen_width: '1536'
tz: '180'
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0)
Gecko/20100101 Firefox/75.0
cardholder:
card_expiry_date: '2212'
name: Joaquim
acct:
type: '02'
encrypted_number: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
merchant:
mcc: '1234'
country_code: BRA
name: Loja de Teste
message:
category: '01'
purchase:
amount: '10004'
currency: '986'
exponent: '2'
date: date
Data Only - Mastercard and Visa:
description: Data Only - Mastercard and Visa
value:
three_ds_comp_ind: 'Y'
pay_token_ind: 'false'
notification_url: https://www.requestor.com/notification
decoupled_notification_url: https://www.requestor.com/decoupled_notification
trans_type: '01'
three_ds_requestor:
authentication_ind: '01'
decoupled_max_time: '10'
id: id
name: Loja de Testes
url: https://www.requestor.com
acquirer:
bin: '2'
merchant_id: '00000000'
browser:
accept_header: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip: 10.20.30.40
javascript_enabled: 'true'
java_enabled: 'false'
language: pt-BR
color_depth: '24'
screen_height: '864'
screen_width: '1536'
tz: '180'
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0)
Gecko/20100101 Firefox/75.0
cardholder:
card_expiry_date: '2212'
name: Joaquim
acct:
type: '02'
encrypted_number: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
merchant:
mcc: mcc
country_code: BRA
name: Loja de Teste
message:
category: '80'
purchase:
amount: '10000'
currency: '986'
exponent: '2'
date: date
required: true
responses:
'200':
description: If successful, the HTTP response code will be 200
content:
'*/*':
examples:
Frictionless Flow Response:
description: Frictionless Flow Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: AUY
acs:
operator_id: acsOperatorID
reference_number: acsReferenceNumber
trans_id: 43214321-4321-4321-4321-432143214321
eci: '05'
device_channel: '02'
authentication:
value: '1234567890123456789012345678'
broad_info: broadInfo
ds:
reference_number: dsReferenceNumber
trans_id: 56785678-5678-5678-5678-567856875678
transaction:
status: 'Y'
message_version: 2.2.0
Challenge Flow Response:
description: Challenge Flow Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: AUC
acs:
challenge_mandated: 'Y'
operator_id: acsOperatorID
reference_number: acsReferenceNumber
trans_id: 43214321-4321-4321-4321-432143214321
url: https://www.acs.com/challenge
device_channel: '02'
authentication:
type: '01'
broad_info: broadInfo
ds:
reference_number: dsReferenceNumber
trans_id: 56785678-5678-5678-5678-567856875678
transaction:
status: C
message_version: 2.2.0
Data Only Response:
description: Data Only Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: AUU
acs:
operator_id: acsOperatorID
reference_number: acsReferenceNumber
trans_id: 43214321-4321-4321-4321-432143214321
eci: '04'
device_channel: '02'
broad_info: broadInfo
ds:
reference_number: dsReferenceNumber
trans_id: 56785678-5678-5678-5678-567856875678
transaction:
status: U
status_reason: '80'
'400':
description: Bad Request
content:
'*/*':
examples:
Card number out of range Response:
description: >-
The card number is outside of supported card range. Other
invalid inputs will also result in a "INV" status
value:
three_ds_server:
trans_id: 9f289031-3f9e-4874-afa8-db6fb7a4207c
status: INV
device_channel: '02'
error:
code: '305'
component: S
description: >-
Cardholder Account Number is not in a range belonging to
Issuer
detail: acctNumber
DS Communication error Response:
description: There was an error during communication with DS
value:
three_ds_server:
trans_id: 9f289031-3f9e-4874-afa8-db6fb7a4207c
status: ERR
device_channel: '02'
error:
code: '405'
component: S
description: DS communication failure
detail: acctNumber
DS error message Response:
description: DS returned an error message
value:
three_ds_server:
trans_id: 9f289031-3f9e-4874-afa8-db6fb7a4207c
status: ERM
device_channel: '02'
error:
code: ''
component: S
description: 3DS Server received an error message from DS
detail: acctNumber
default:
description: Any other code must be interpreted as an error
content:
'*/*':
examples:
Error Response:
description: Error Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: INV
device_channel: '02'
error:
code: '1'
component: S
description: Error description
detail: Error detail
/v2/authentication/{transId}:
put:
tags:
- authentication-controller
summary: Authentication service
description: >-
After creating the transaction, it's necessary to call the
authentication service to continue the flow. If the AUC status is
returned, a challenge must be initiated. For the AUD status, the
"decoupled" flow must be followed. Otherwise, further calls won't be
required.
operationId: doAuthentication
parameters:
- name: merchant_id
in: header
description: >-
Merchant code on 3DS Server. The production and certification codes
will be different.<br>Format < 15 AN, Mandatory YES
required: true
schema:
type: string
description: >-
Merchant code on 3DS Server. The production and certification
codes will be different.<br>Format < 15 AN, Mandatory YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: merchant_key
in: header
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
required: true
schema:
type: string
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat_merchant_id
in: header
description: >-
Carat merchant code must be sent only if the token field is sent in
the request.<br>Format < 15 AN, Mandatory COND
required: false
schema:
type: string
description: >-
Carat merchant code must be sent only if the token field is sent
in the request.<br>Format < 15 AN, Mandatory COND
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat_merchant_key
in: header
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
required: false
schema:
type: string
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
example: zzzzzzzzzzzzzz
example: zzzzzzzzzzzzzz
- name: transId
in: path
description: 3DS Server Transaction ID
required: true
schema:
type: string
description: 3DS Server Transaction ID
example: zzzzzzzzzzzzzz
example: zzzzzzzzzzzzzz
requestBody:
description: Below are some examples of the authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Server3DSRootModel'
examples:
Frictionless Flow:
description: Frictionless Flow
value:
three_ds_comp_ind: 'Y'
pay_token_ind: 'false'
notification_url: https://www.requestor.com/notification
trans_type: '01'
three_ds_requestor:
authentication_ind: '01'
id: id
name: Loja de Testes
url: https://www.requestor.com
acquirer:
bin: '2'
merchant_id: '00000000'
browser:
accept_header: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip: 10.20.30.40
javascript_enabled: 'true'
java_enabled: 'false'
language: pt-BR
color_depth: '24'
screen_height: '864'
screen_width: '1536'
tz: '180'
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0)
Gecko/20100101 Firefox/75.0
cardholder:
card_expiry_date: '2212'
name: Joaquim
acct:
type: '02'
number: '1234123412341234'
merchant:
mcc: '1234'
country_code: BRA
name: Loja de Teste
message:
category: '01'
purchase:
amount: '10000'
currency: '986'
exponent: '2'
date: date
Challenge Flow:
description: Challenge Flow
value:
three_ds_comp_ind: 'Y'
pay_token_ind: 'false'
notification_url: https://www.requestor.com/notification
trans_type: '01'
three_ds_requestor:
authentication_ind: '01'
id: id
name: Loja de Testes
url: https://www.requestor.com
acquirer:
bin: '2'
merchant_id: '00000000'
browser:
accept_header: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip: 10.20.30.40
javascript_enabled: 'true'
java_enabled: 'false'
language: pt-BR
color_depth: '24'
screen_height: '864'
screen_width: '1536'
tz: '180'
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0)
Gecko/20100101 Firefox/75.0
cardholder:
card_expiry_date: '2212'
name: Joaquim
acct:
type: '02'
number: '1234123412341234'
merchant:
mcc: '1234'
country_code: BRA
name: Loja de Teste
message:
category: '01'
purchase:
amount: '10004'
currency: '986'
exponent: '2'
date: date
Data Only - Mastercard and Visa:
description: Data Only - Mastercard and Visa
value:
three_ds_comp_ind: 'Y'
pay_token_ind: 'false'
notification_url: https://www.requestor.com/notification
decoupled_notification_url: https://www.requestor.com/decoupled_notification
trans_type: '01'
three_ds_requestor:
authentication_ind: '01'
decoupled_max_time: '10'
id: id
name: Loja de Testes
url: https://www.requestor.com
acquirer:
bin: '2'
merchant_id: '00000000'
browser:
accept_header: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip: 10.20.30.40
javascript_enabled: 'true'
java_enabled: 'false'
language: pt-BR
color_depth: '24'
screen_height: '864'
screen_width: '1536'
tz: '180'
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0)
Gecko/20100101 Firefox/75.0
cardholder:
card_expiry_date: '2212'
name: Joaquim
acct:
type: '02'
number: '1234123412341234'
merchant:
mcc: mcc
country_code: BRA
name: Loja de Teste
message:
category: '80'
purchase:
amount: '10000'
currency: '986'
exponent: '2'
date: date
required: true
responses:
'200':
description: If successful, the HTTP response code will be 200
content:
'*/*':
examples:
Frictionless Flow Response:
description: Frictionless Flow Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: AUY
acs:
operator_id: acsOperatorID
reference_number: acsReferenceNumber
trans_id: 43214321-4321-4321-4321-432143214321
eci: '05'
device_channel: '02'
authentication:
value: '1234567890123456789012345678'
broad_info: broadInfo
ds:
reference_number: dsReferenceNumber
trans_id: 56785678-5678-5678-5678-567856875678
transaction:
status: 'Y'
message_version: 2.2.0
Challenge Flow Response:
description: Challenge Flow Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: AUC
acs:
challenge_mandated: 'Y'
operator_id: acsOperatorID
reference_number: acsReferenceNumber
trans_id: 43214321-4321-4321-4321-432143214321
url: https://www.acs.com/challenge
device_channel: '02'
authentication:
type: '01'
broad_info: broadInfo
ds:
reference_number: dsReferenceNumber
trans_id: 56785678-5678-5678-5678-567856875678
transaction:
status: C
message_version: 2.2.0
Data Only Response:
description: Data Only Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: AUU
acs:
operator_id: acsOperatorID
reference_number: acsReferenceNumber
trans_id: 43214321-4321-4321-4321-432143214321
eci: '04'
device_channel: '02'
broad_info: broadInfo
ds:
reference_number: dsReferenceNumber
trans_id: 56785678-5678-5678-5678-567856875678
transaction:
status: U
status_reason: '80'
'400':
description: Bad Request
content:
'*/*':
examples:
Card number out of range Response:
description: >-
The card number is outside of supported card range. Other
invalid inputs will also result in a "INV" status
value:
three_ds_server:
trans_id: 9f289031-3f9e-4874-afa8-db6fb7a4207c
status: INV
device_channel: '02'
error:
code: '305'
component: S
description: >-
Cardholder Account Number is not in a range belonging to
Issuer
detail: acctNumber
DS Communication error Response:
description: There was an error during communication with DS
value:
three_ds_server:
trans_id: 9f289031-3f9e-4874-afa8-db6fb7a4207c
status: ERR
device_channel: '02'
error:
code: '405'
component: S
description: DS communication failure
detail: acctNumber
DS error message Response:
description: DS returned an error message
value:
three_ds_server:
trans_id: 9f289031-3f9e-4874-afa8-db6fb7a4207c
status: ERM
device_channel: '02'
error:
code: ''
component: S
description: 3DS Server received an error message from DS
detail: acctNumber
default:
description: Any other code must be interpreted as an error
content:
'*/*':
examples:
Error Response:
description: Error Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: INV
device_channel: '02'
error:
code: '1'
component: S
description: Error description
detail: Error detail
/v3/authentication:
post:
tags:
- authentication-controller
summary: Transaction creation service V3
description: "This call is required to obtain the 3DS Method URL corresponding to the card, besides creating a 3DS Server transaction, which will be used in the following steps of the flow.\r\nImportant: The value of the message_version field returned in the response must be used in the CREQ step (for challenge transactions)."
operationId: beginAuthenticationV3
parameters:
- name: Client-Request-Id
in: header
description: >-
UUID v4 generated following the RFC 4122 specification, unique to
each transaction.<br>Format = 26 H (UUID v4)
required: true
schema:
type: string
description: >-
UUID v4 generated following the RFC 4122 specification, unique to
each transaction.<br>Format = 26 H (UUID v4)
example: d608388f-8351-4ef7-a693-a48dc7651502
example: d608388f-8351-4ef7-a693-a48dc7651502
- name: Authorization
in: header
description: Generated HMAC signature.
required: true
schema:
type: string
description: Generated HMAC signature.
- name: Auth-Token-Type
in: header
description: Describes which Authorization type is being used.
required: true
schema:
type: string
description: Describes which Authorization type is being used.
example: HMAC
example: HMAC
- name: merchant-id
in: header
description: >-
Merchant code on 3DS Server. The production and certification codes
will be different.<br>Format < 15 AN, Mandatory YES
required: true
schema:
type: string
description: >-
Merchant code on 3DS Server. The production and certification
codes will be different.<br>Format < 15 AN, Mandatory YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: merchant-key
in: header
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
required: false
schema:
type: string
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat-merchant-id
in: header
description: >-
Carat merchant code must be sent only if the token field is sent in
the request.<br>Format < 15 AN, Mandatory COND
required: false
schema:
type: string
description: >-
Carat merchant code must be sent only if the token field is sent
in the request.<br>Format < 15 AN, Mandatory COND
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat-merchant-key
in: header
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
required: false
schema:
type: string
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
example: zzzzzzzzzzzzzz
example: zzzzzzzzzzzzzz
- name: api-key
in: header
description: HMAC key
required: true
schema:
type: string
description: HMAC key
example: xxxxxxxxxxxxxxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxxxxxxxxxxxxxx
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Server3DSRootModel'
examples:
Encrypted card number authentication:
description: >-
Payload using encrypted card number for this functionality
must have this format.
value:
cardholder:
acct:
encrypted_number: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
brand_id: '2'
required: true
responses:
'200':
description: If successful, the HTTP response code will be 200
content:
'*/*':
examples:
Encrypted Card number authentication:
description: >-
Response when using encrypted card number for this
functionality.
value:
three_ds_method_url: https://www.example.com
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: NEW
acs:
protocol_version:
start: 2.1.0
end: 2.2.0
device_channel: '02'
ds:
protocol_version:
start: 2.1.0
end: 2.2.0
message_version: 2.2.0
default:
description: Any other code must be interpreted as an error
content:
'*/*':
examples:
Error Response:
summary: Error Response
description: Error Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: INV
device_channel: '02'
error:
code: '1'
component: S
description: Error description
detail: Error detail
/v2/authentication:
post:
tags:
- authentication-controller
summary: Transaction creation service
description: "This call is required to obtain the 3DS Method URL corresponding to the card, besides creating a 3DS Server transaction, which will be used in the following steps of the flow.\r\nImportant: The value of the message_version field returned in the response must be used in the CREQ step (for challenge transactions)."
operationId: beginAuthentication
parameters:
- name: merchant_id
in: header
description: >-
Merchant code on 3DS Server. The production and certification codes
will be different.<br>Format < 15 AN, Mandatory YES
required: true
schema:
type: string
description: >-
Merchant code on 3DS Server. The production and certification
codes will be different.<br>Format < 15 AN, Mandatory YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: merchant_key
in: header
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
required: true
schema:
type: string
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format < 80 AN, Mandatory
YES
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat_merchant_id
in: header
description: >-
Carat merchant code must be sent only if the token field is sent in
the request.<br>Format < 15 AN, Mandatory COND
required: false
schema:
type: string
description: >-
Carat merchant code must be sent only if the token field is sent
in the request.<br>Format < 15 AN, Mandatory COND
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: carat_merchant_key
in: header
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
required: false
schema:
type: string
description: >-
The authentication key of the Carat merchant must be sent only if
the token field is sent in the request.<br>Format < 80 AN
example: zzzzzzzzzzzzzz
example: zzzzzzzzzzzzzz
- name: Authorization
in: header
description: >-
Merchant's signature in the Bearer {signature} format. Example:
Bearer {TOKEN_JWT_EXAMPLE} Format < 2000 AN
required: false
schema:
type: string
description: >-
Merchant's signature in the Bearer {signature} format. Example:
Bearer {TOKEN_JWT_EXAMPLE} Format < 2000 AN
example: >-
Bearer
{TOKEN_JWT_EXAMPLE}
example: >-
Bearer
{TOKEN_JWT_EXAMPLE}
requestBody:
description: It is possible to generate the signature using 2 different payloads
content:
application/json:
schema:
$ref: '#/components/schemas/Server3DSRootModel'
examples:
Card number authentication:
description: >-
Payload using card number for this functionality must have
this format.
value:
cardholder:
acct:
number: '1234123412341234'
brand_id: '2'
Token authentication:
description: >-
Payload using token for this functionality must have this
format.
value:
cardholder:
acct:
token: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
brand_id: '2'
required: true
responses:
'200':
description: If successful, the HTTP response code will be 200
content:
'*/*':
examples:
Card number authentication:
description: Response when using card number for this functionality.
value:
three_ds_method_url: https://www.example.com
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: NEW
acs:
protocol_version:
start: 2.1.0
end: 2.2.0
device_channel: '02'
ds:
protocol_version:
start: 2.1.0
end: 2.2.0
message_version: 2.2.0
Token authentication:
description: Response when using token for this functionality.
value:
three_ds_method_url: https://www.example.com
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: NEW
acs:
protocol_version:
start: 2.1.0
end: 2.2.0
device_channel: '02'
ds:
protocol_version:
start: 2.1.0
end: 2.2.0
message_version: 2.2.0
default:
description: Any other code must be interpreted as an error
content:
'*/*':
examples:
Error Response:
summary: Error Response
description: Error Response
value:
three_ds_server:
trans_id: 12341234-1234-1234-1234-123412341234
status: INV
device_channel: '02'
error:
code: '1'
component: S
description: Error description
detail: Error detail
/v3/transaction/{transId}:
get:
tags:
- transaction-controller
summary: Transaction query service V3
description: >-
This call allows 3DS Requestor to query the status of a transaction.
This operation must be used by 3DS Requestor in case of problems
receiving the CRes. We will return status, ECI and CAVV, which are
necessary to proceed with an authorization.
operationId: queryV3
parameters:
- name: transId
in: path
required: true
schema:
type: string
- name: Client-Request-Id
in: header
description: >-
UUID v4 generated following the RFC 4122 specification, unique to
each transaction.<br>Format = 26 H (UUID v4)
required: true
schema:
type: string
description: >-
UUID v4 generated following the RFC 4122 specification, unique to
each transaction.<br>Format = 26 H (UUID v4)
example: d608388f-8351-4ef7-a693-a48dc7651502
example: d608388f-8351-4ef7-a693-a48dc7651502
- name: Authorization
in: header
description: Generated HMAC signature.
required: true
schema:
type: string
description: Generated HMAC signature.
- name: Auth-Token-Type
in: header
description: Describes which Authorization type is being used.
required: true
schema:
type: string
description: Describes which Authorization type is being used.
example: HMAC
example: HMAC
- name: merchant-id
in: header
description: >-
Merchant code on 3DS Server. The production and certification codes
will be different.<br>Format <= 15 AN
required: true
schema:
type: string
description: >-
Merchant code on 3DS Server. The production and certification
codes will be different.<br>Format <= 15 AN
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: merchant-key
in: header
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format <= 80 AN
required: true
schema:
type: string
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format <= 80 AN
example: xxxxxxxxxxx
example: xxxxxxxxxxx
- name: api-key
in: header
description: HMAC key
required: true
schema:
type: string
description: HMAC key
example: xxxxxxxxxxxxxxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxxxxxxxxxxxxxx
responses:
'200':
description: If successful, the HTTP response code will be 200
content:
'*/*':
examples:
Default Response:
description: Default Response
value:
three_ds_server:
trans_id: 12345678-1234-1234-1234-123456789012
status: AUY
brand_id: '2'
eci: '05'
device_channel: '02'
authentication:
value: '1234567890123456789012345678'
message_version: 2.2.0
Challenge Cancel Response:
description: Challenge Cancel Response
value:
three_ds_server:
trans_id: 12345678-1234-1234-1234-123456789012
status: AUY
brand_id: '2'
challenge_cancel: '01'
eci: '05'
device_channel: '02'
authentication:
value: '1234567890123456789012345678'
message_version: 2.2.0
/v2/transaction/{transId}:
get:
tags:
- transaction-controller
summary: Transaction query service
description: >-
This call allows 3DS Requestor to query the status of a transaction.
This operation must be used by 3DS Requestor in case of problems
receiving the CRes. We will return status, ECI and CAVV, which are
necessary to proceed with an authorization.
operationId: query
parameters:
- name: transId
in: path
required: true
schema:
type: string
- name: merchant_id
in: header
description: >-
Merchant code on 3DS Server. The production and certification codes
will be different.<br>Format <= 15 AN
required: true
schema:
type: string
description: >-
Merchant code on 3DS Server. The production and certification
codes will be different.<br>Format <= 15 AN
example: xxxxxxxxxxxxxxx
example: xxxxxxxxxxxxxxx
- name: merchant_key
in: header
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format <= 80 AN
required: true
schema:
type: string
description: >-
Merchant authentication key on 3DS Server. The production and
certification keys will be different.<br>Format <= 80 AN
example: xxxxxxxxxxx
example: xxxxxxxxxxx
responses:
'200':
description: If successful, the HTTP response code will be 200
content:
'*/*':
examples:
Default Response:
description: Default Response
value:
three_ds_server:
trans_id: 12345678-1234-1234-1234-123456789012
status: AUY
brand_id: '2'
eci: '05'
device_channel: '02'
authentication:
value: '1234567890123456789012345678'
message_version: 2.2.0
Challenge Cancel Response:
description: Challenge Cancel Response
value:
three_ds_server:
trans_id: 12345678-1234-1234-1234-123456789012
status: AUY
brand_id: '2'
challenge_cancel: '01'
eci: '05'
device_channel: '02'
authentication:
value: '1234567890123456789012345678'
message_version: 2.2.0
components:
schemas:
AcctInfoModel:
type: object
description: Account Info Model
properties:
ch_acc_age_ind:
type: string
description: >-
Length of time that the cardholder has had the account with the 3DS
Requestor.<br>01 = No account (guest check-out)<br>02 = Created
during this transaction<br>03 = Less than 30 days<br>04 = 30-60
days<br>05 = More than 60 days<br>Format = 2 N
example: '02'
ch_acc_change:
type: string
description: >-
Date that the cardholder's account with the 3DS Requestor was last
changed, including Billing or Shipping address, new payment account,
or new user(s) added, in YYYYMMDD format.<br>Format = 8 N
example: 20250101
ch_acc_change_ind:
type: string
description: >-
Length of time since the cardholder's account information with the
3DS Requestor was last changed, including Billing or Shipping
address, new payment account, or new user(s) added.<br>01 = Changed
during this transaction<br>02 = Less than 30 days<br>03 = 30-60
days<br>04 = More than 60 days<br>Format = 2 N
example: '01'
ch_acc_date:
type: string
description: >-
Date that the cardholder opened the account with the 3DS Requestor
in YYYYMMDD format.<br>Format = 8 N
example: 20250101
ch_acc_pw_change:
type: string
description: >-
Date that cardholder's account with the 3DS Requestor had a password
change or account reset in YYYYMMDD format.<br>Format = 8 N
example: 20250101
ch_acc_pw_change_ind:
type: string
description: >-
Indicates the length of time since the cardholder's account with the
3DS Requestor had a password change or account reset.<br>01 = No
change<br>02 = Changed during this transaction<br>03 = Less than 30
days<br>04 = 30-60 days<br>05 = More than 60 days<br>= 2 N
example: '02'
nb_purchase_account:
type: string
description: >-
Number of purchases with this cardholder account during the previous
six months.<br>Format <= 4 N
example: 2
provision_attempts_day:
type: string
description: Number of Add Card attempts in the last 24 hours.<br>Format <= 3 N
example: 2
txn_activity_day:
type: string
description: >-
Number of transactions (successful and abandoned) for this
cardholder account with the 3DS Requestor across all payment
accounts in the previous 24 hours.<br>Format <= 3 N
example: 2
txn_activity_year:
type: string
description: >-
Number of transactions (successful and abandoned) for this
cardholder account with the 3DS Requestor across all payment
accounts in the previous year.<br>Format <= 3 N
example: 2
payment_acc_age:
type: string
description: >-
Date that the payment account was enrolled in the cardholder's
account with the 3DS Requestor in YYYYMMDD format.<br>Format = 8 N
example: 20250101
payment_acc_ind:
type: string
description: >-
Indicates the length of time that the payment account was enrolled
in the cardholder's account with the 3DS Requestor.<br>01 = No
account (guest check-out)<br>02 = During this transaction<br>03 =
Less than 30 days<br>04 = 30-60 days<br>05 = More than 60
days<br>Format = 2 N
example: '02'
ship_address_usage:
type: string
description: >-
Date when the shipping address used for this transaction was first
used with the 3DS Requestor in YYYYMMDD format.<br>Format = 8 N
example: 20250101
ship_address_usage_ind:
type: string
description: >-
Indicates when the shipping address used for this transaction was
first used with the 3DS Requestor.<br>01 = This transaction<br>02 =
Less than 30 days<br>03 = 30-60 days<br>04 = More than 60
days<br>Format = 2 N
example: '01'
ship_name_indicator:
type: string
description: >-
Indicates if the Cardholder Name on the account is identical to the
shipping Name used for this transaction.<br>01 = Account Name
identical to shipping Name<br>02 = Account Name different than
shipping Name<br>Format = 2 N
example: '01'
suspicious_acc_activity:
type: string
description: >-
Indicates whether the 3DS Requestor has experienced suspicious
activity (including previous fraud) on the cardholder account.<br>01
= No suspicious activity has been observed<br>02 = Suspicious
activity has been observed<br>Format = 2 N
example: '01'
AcctModel:
type: object
description: Account Model
properties:
type:
type: string
description: >-
Indicates the type of account. For example, for a multi-account card
product.<br>01 = Not Applicable<br>02 = Credit<br>03 =
Debit<br>Format = 2 N
example: '02'
number:
type: string
description: >-
Customer's card number (PAN), the number or token field must always
be sent in the request<br>Format = 19 N
example: 5555555555555555000
id:
type: string
description: >-
Additional information about the account optionally provided by the
3DS Requestor.<br>Format <= 64 AN
example: '02'
info:
$ref: '#/components/schemas/AcctInfoModel'
description: Account Info
token:
type: string
description: >-
HASH of a card stored in Carat, the number or token field must
always be sent in the request<br>Format = 88 AN
example: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
encrypted_number:
type: string
description: Encypted customer's card number (PAN)
example: >-
er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467
AcquirerModel:
type: object
description: Acquirer Model
properties:
bin:
type: string
description: >-
Acquiring institution identification code as assigned by the DS
receiving the AReq message.<br>Format <= 11 AN
merchant_id:
type: string
description: Acquirer-assigned Merchant identifier.<br>Format <= 35 AN
AcsModel:
type: object
description: ACS Model
properties:
challenge_mandated:
type: string
description: >-
Indication of whether a challenge is required for the transaction to
be authorised due to local/regional mandates or other variable.<br>Y
= Challenge is mandated<br>N = Challenge is not mandated<br>Format =
1 AN
example: 'Y'
operator_id:
type: string
description: DS assigned ACS identifier.<br>Format <= 32 N
example: acsOperatorID
reference_number:
type: string
description: >-
Unique identifier assigned by the EMVCo Secretariat upon Testing and
Approval.<br>Format <= 32 AN
example: acsReferenceNumber
trans_id:
type: string
description: >-
Universally Unique transaction identifier assigned by the ACS to
identify a single transaction.<br>Format = 36 AN
example: 43214321-4321-4321-4321-432143214321
url:
type: string
description: >-
Fully qualified URL of the ACS to be used for the
challenge.<br>Format <= 2048 AN
example: https://www.acs.com/challenge
decoupled_confirmation_ind:
type: string
description: >-
Indicates whether the ACS confirms utilisation of Decoupled
Authentication and agrees to utilise Decoupled Authentication to
authenticate the Cardholder.<br>Y = Confirms Decoupled
Authentication will be utilised<br>N = Decoupled Authentication will
not be utilised<br>Format = 1 AN
example: 'N'
signed_content:
type: string
description: >-
Contains the JWS object (represented as a string) created by the ACS
for the ARes message.<br>Format var. AN
iface:
type: string
description: >-
This the ACS interface that the challenge will present to the
cardholder.<br>01 = Native UI<br>02 = HTML UI<br>Format = 2 N
example: '02'
ui_template:
type: string
description: >-
Identifies the UI Template format that the ACS first presents to the
consumer.<br>01 = Text<br>02 = Single Select<br>03 = Multi
Select<br>04 = OOB<br>05 = HTML Other<br>Format = 2 N
example: '01'
protocol_version:
$ref: '#/components/schemas/ProtocolVersionModel'
description: Protocol Version
AuthenticationModel:
type: object
description: Authentication Model
properties:
type:
type: string
description: Authentication value (CAVV).<br>Format <= 22 AN
example: 1.2345678901234569e+27
value:
type: string
description: >-
Indicates the type of authentication method the Issuer will use to
challenge the Cardholder.01 = Static<br>02 = Dynamic<br>03 =
OOB<br>04 = Decoupled<br>Format = 2 AN
example: '01'
BrowserModel:
type: object
description: Browser Model
properties:
accept_header:
type: string
description: >-
Exact content of the HTTP accept headers as sent to the 3DS
Requestor from the Cardholder's browser.<br>Format <= 2048 AN
example: >-
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ip:
type: string
description: >-
IP address of the browser as returned by the HTTP headers to the 3DS
Requestor.<br>Format < 45 AN
example: 10.20.30.40
java_enabled:
type: string
description: >-
Boolean that represents the ability of the cardholder browser to
execute Java. Value is returned from the navigator.javaEnabled
property.<br>Format < 5 AN
example: false
javascript_enabled:
type: string
description: >-
Boolean that represents the ability of the cardholder browser to
execute JavaScript.<br>Format < 5 AN
example: true
language:
type: string
description: >-
Value representing the browser language as defined in IETF BCP47.
Returned from navigator.language property.<br>Format < 8 AN
example: pt-BR
color_depth:
type: string
description: >-
Value representing the bit depth of the colour palette for
displaying images, in bits per pixel. Obtained from Cardholder
browser using the screen.colorDepth property.<br>1 = 1 bit<br>4 = 4
bits<br>8 = 8 bits<br>15 = 15 bits<br>16 = 16 bits<br>24 = 24
bits<br>32 = 32 bits<br>48 = 48 bits<br>Note: If the value in the
request differs from the ones specified above, the nearest value
will be selected, always favoring the smaller one.<br>Example: 30
will be chosen as 24.<br>Format < 2 N
example: 24
screen_height:
type: string
description: >-
Total height of the Cardholder's screen in pixels. Value is returned
from the screen.height property.<br>Format < 6 N
example: 864
screen_width:
type: string
description: >-
Total width of the cardholder's screen in pixels. Value is returned
from the screen.width property.<br>Format < 6 AN
example: 1536
tz:
type: string
description: >-
Time-zone offset in minutes between UTC and the Cardholder browser
local time. Value is returned from the getTimezoneOffset()
method.<br>Format < 5 AN
example: 180
user_agent:
type: string
description: Exact content of the HTTP user-agent header.<br>Format < 2048 AN
example: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101
Firefox/75.0
CardholderAddressModel:
type: object
description: Cardholder Address Model
properties:
city:
type: string
description: >-
The city of the Cardholder address associated with the card used for
this purchase.<br>Format <= 50 AN
country:
type: string
description: >-
The ISO 3166-1 numeric three-digit country code of the Cardholder
address associated with the card used for this purchase.<br>Format =
3 N
line1:
type: string
description: >-
First line of the street address or equivalent local portion of the
Cardholder address associated with the card used for this
purchase.<br>Format <= 50 AN
line2:
type: string
description: >-
Second line of the street address or equivalent local portion of the
Cardholder address associated with the card used for this
purchase.<br>Format <= 50 AN
line3:
type: string
description: >-
Third line of the street address or equivalent local portion of the
Cardholder address associated with the card used for this
purchase.<br>Format <= 50 AN
post_code:
type: string
description: >-
ZIP or other postal code of the Cardholder address associated with
the card used for this purchase.<br>Format <= 16 AN
state:
type: string
description: >-
The state or province of the Cardholder address associated with the
card used for this purchase.<br>Format <= 3 AN
CardholderModel:
type: object
description: Cardholder Model
properties:
card_expiry_date:
type: string
description: >-
Expiry Date of the PAN or token supplied to the 3DS Requestor by the
Cardholder in YYMM format.<br>Format = 4 N
addr_match:
type: string
description: >-
Indicates whether the Cardholder Shipping Address and Cardholder
Billing Address are the same.<br>Y = Shipping Address matches
Billing Address<br>N = Shipping Address does not match Billing
Address<br>Format = 1 AN
email:
type: string
description: >-
While not mandatory, it is advisable to send this field as it aids
in risk assessment, increasing the likelihood of obtaining a silent
authentication. <br>Format <= 256 AN
info:
type: string
description: Name of the Cardholder.<br>Format <= 45 AN
home_phone:
$ref: '#/components/schemas/PhoneModel'
description: The home phone number provided by the Cardholder.
mobile_phone:
$ref: '#/components/schemas/PhoneModel'
description: >-
It is advisable to send this field, as it aids in risk assessment,
increasing the chances of obtaining a silent authentication.
work_phone:
$ref: '#/components/schemas/PhoneModel'
description: The work phone number provided by the Cardholder.
name:
type: string
description: Name of the Cardholder.<br>Format <= 45 AN
example: Joaquim
acct:
$ref: '#/components/schemas/AcctModel'
description: Account
bill_addr:
$ref: '#/components/schemas/CardholderAddressModel'
description: Cardholder Billing Address
ship_addr:
$ref: '#/components/schemas/CardholderAddressModel'
description: Cardholder Shipping Address
cardNumberAndTokenFilled:
type: boolean
DsModel:
type: object
description: DS Model
properties:
reference_number:
type: string
description: >-
EMVCo-assigned unique identifier to track approved DS.<br> Format <=
32 AN
trans_id:
type: string
description: >-
Universally unique transaction identifier assigned by the DS to
identify a single transaction.<br>Format = 36 AN
url:
type: string
description: URL
protocol_version:
$ref: '#/components/schemas/ProtocolVersionModel'
description: Protocol Version
ErrorModel:
type: object
description: Error Model
properties:
code:
type: string
description: >-
Error code.<br>1 - Invalid credentials (merchant_id &
merchant_key)<br>2 - Transaction not found<br>3 - Invalid
transaction status<br>101 - Unknown message type<br>201 - Empty
parameter (see error.detail for further details)<br>202 -
message.extension not recognized<br>203 - Invalid parameter (see
error.detail for further details)<br>301 - Transaction ID received
is not valid for the receiving component.<br>305 - Card not
supported by the issuer for 3DS 2.0 authentications.<br>402 -
Timeout when communicating with DS<br>404 - Unexpected error<br>405
- DS communication error<br>Format <= 3 N
example: 1
component:
type: string
description: >-
Indicates which component identified the error.<br>C = 3DS SDK<br>S
= 3DS Server<br>D = DS<br>A = ACS<br>Format = 1 AN
example: S
description:
type: string
description: Error description.<br>Format <= 2048 AN
example: Error description
detail:
type: string
description: Error details.<br>Format <= 28 AN
example: Error detail
MerchantModel:
type: object
description: Merchant
properties:
mcc:
type: string
description: >-
DS-specific code describing the Merchant's type of business, product
or service. Before sending the request to the DS, the 3DS
automatically checks the size of the mcc field entered. If the
length is less than 4 characters, the 3DS will add leading zeros
until the field reaches a total length of 4 characters.<br>Format =
4 N
country_code:
type: string
description: >-
ISO 3166-1 numeric three-digit country code of the
Merchant.<br>Format = 3 N
name:
type: string
description: >-
Merchant name assigned by the Acquirer or Payment System.<br>Format
<= 40 AN
risk_indicator:
$ref: '#/components/schemas/MerchantRiskIndicatorModel'
description: >-
Merchant's assessment of the level of fraud risk for the specific
authentication for both the cardholder and the authentication being
conducted.
MerchantRiskIndicatorModel:
type: object
description: Merchant Risk Indicator Model
properties:
delivery_email_address:
type: string
description: >-
For prepaid or gift card purchase, the purchase amount total of
prepaid or gift card(s) in major units (for example, USD 123.45 is
123).<br>Format < 15 N
delivery_timeframe:
type: string
description: >-
Indicates the merchandise delivery timeframe.<br>01 = Electronic
Delivery<br>02 = Same day shipping<br>03 = Overnight shipping<br>04
= Two-day or more shipping<br>Format = 2 N
gift_card_amount:
type: string
description: >-
For prepaid or gift card purchase, the purchase amount total of
prepaid or gift card(s) in major units (for example, USD 123.45 is
123).<br>Format < 15 N
gift_card_count:
type: string
description: >-
For prepaid or gift card purchase, total count of individual prepaid
or gift cards/codes purchased.<br>Format < 2 N
gift_card_curr:
type: string
description: >-
For prepaid or gift card purchase, ISO 4217 three-digit currency
code of the gift card.<br>Format = 3 N
pre_order_date:
type: string
description: >-
For a pre-ordered purchase, the expected date that the merchandise
will be available in YYYYMMDD format.<br>Format = 8 N
pre_order_purchase_ind:
type: string
description: >-
Indicates whether Cardholder is placing an order for merchandise
with a future availability or release date.<br>01 = Merchandise
available<br>02 = Future availability<br>Format = 2 N
reorder_items_ind:
type: string
description: >-
Indicates whether the cardholder is reordering previously purchased
merchandise.<br>01 = First time ordered<br>02 = Reordered<br>Format
= 2 N
ship_indicator:
type: string
description: >-
Indicates shipping method chosen for the transaction.<br>01 = Ship
to cardholder's billing address<br>02 = Ship to another verified
address on file with merchant<br>03 = Ship to address that is
different than the cardholder's billing address<br>04 = “Ship to
Store” / Pick-up at local store (Store address shall be populated in
shipping address fields)<br>05 = Digital goods (includes online
services, electronic gift cards and redemption codes)<br>06 = Travel
and Event tickets, not shipped<br>07 = Other (for example, Gaming,
digital services not shipped, emedia subscriptions, etc.)<br>Format
= 2 N
MessageExtensionModel:
type: object
description: Message Extension Model
properties:
criticality_indicator:
type: string
description: >-
A Boolean value indicating whether the recipient must understand the
contents of the extension to interpret the entire message.<br>Format
<= 5 AN
data:
description: The data carried in the extension.
id:
type: string
description: A unique identifier for the extension.<br>Format <= 64 AN
name:
type: string
description: >-
The name of the extension data set as defined by the extension
owner.<br>Format <= 64 AN
MessageModel:
type: object
description: Message Model
properties:
category:
type: string
description: >-
Identifies the category of the message for a specific use
case.<br>01 - Payment Authentication<br>02 - Non-Payment
Authentication<br>80 - Mastercard Identity Check Insights (Data
only) Authentication<br>Format = 2 N
example: '01'
extension:
type: array
description: >-
Data necessary to support requirements not otherwise defined in the
3-D Secure message are carried in a Message Extension.
items:
$ref: '#/components/schemas/MessageExtensionModel'
version:
type: string
description: Version
PhoneModel:
type: object
description: Phone Model
properties:
cc:
type: string
description: Country Code.<br>Format <= 3 N
example: 55
subscriber:
type: string
description: Subscriber.<br>Format <= 15 N
example: 999999999999999
ProtocolVersionModel:
type: object
description: Protocol Version Model
properties:
start:
type: string
description: Start
end:
type: string
description: End
PurchaseModel:
type: object
description: Purchase Model
properties:
amount:
type: string
description: >-
Purchase amount in minor units of currency with all punctuation
removed.<br>Format <= 48 N
example: 10000
currency:
type: string
description: >-
ISO 4217 three-digit currency code in which purchase amount is
expressed.<br>Format = 3 N
example: 986
exponent:
type: string
description: >-
Minor units of currency as specified in the ISO 4217 currency
exponent.<br>Format = 1 N
example: 2
date:
type: string
description: >-
Date and time of the purchase expressed in UTC in YYYYMMDDHHMMSS
format.<br>Format = 12 N
example: 20250101000000
instal_data:
type: string
description: >-
Indicates the maximum number of authorizations permitted for
instalment payments. Value shall be greater than 1.<br>Format <= 3 N
example: 2
RecurringModel:
type: object
description: Recurring Model
properties:
expiry:
type: string
description: >-
<br>Format Date after which no further authorizations shall be
performed in YYYYMMDD format. Mandatory when three_ds_requestor.
authentication_ind = 02 or 03.<br>Format = 8 N
frequency:
type: string
description: >-
Indicates the minimum number of days between authorizations.
Mandatory when three_ds_requestor. authentication_ind = 02 or
03.<br>Format <= 4 N
RequestorAuthenticationInfoModel:
type: object
description: Requestor Authentication Info Model
properties:
data:
description: >-
Data that documents and supports a specific authentication
process.<br>Format < 20000 AN
method:
type: string
description: >-
Mechanism used by the Cardholder to authenticate to the 3DS
Requestor.<br>01 = No 3DS Requestor authentication occurred (i.e.
cardholder “logged in” as guest)<br>02 = Login to the cardholder
account at the 3DS Requestor system using 3DS Requestor’s own
credentials<br>03 = Login to the cardholder account at the 3DS
Requestor system using federated ID<br>04 = Login to the cardholder
account at the 3DS Requestor system using issuer credentials<br>05 =
Login to the cardholder account at the 3DS Requestor system using
third-party authentication<br>06 = Login to the cardholder account
at the 3DS Requestor system using FIDO Authenticator<br>07 = Login
to the cardholder account at the 3DS Requestor system using FIDO
Authenticator (FIDO assurance data signed)<br>08 = SRC Assurance
Data<br>Format = 2 N
example: '02'
timestamp:
type: string
description: >-
Date and time in UTC of the cardholder authentication in
YYYYMMDDHHMM format.<br>Format = 12 N
RequestorPriorAuthenticationInfoModel:
type: object
properties:
data:
description: >-
Data that documents and supports a specific authentication
process.<br>Format <= 2048 AN
method:
type: string
description: >-
Mechanism used by the Cardholder to previously authenticate to the
3DS Requestor.<br>01 = Frictionless authentication occurred by
ACS<br>02 = Cardholder challenge occurred by ACS<br>03 = AVS
verified<br>04 = Other issuer methods<br>format = 2 N
example: '01'
timestamp:
type: string
description: >-
Date and time in UTC of the prior cardholder authentication in
YYYYMMDDHHMM format.<br>Format = 12 N
example: 202509091300
reference:
type: string
description: >-
This data element provides additional information to the ACS to
determine the best approach for handing a request.<br>Format <= 36
AN
SdkModel:
type: object
description: SDK Model
properties:
app_id:
type: string
description: >-
Universally unique ID created upon all installations of the 3DS
Requestor App on a Consumer Device. This will be newly generated and
stored by the 3DS SDK for each installation.<br>Format = 36 AN
enc_data:
type: string
description: >-
JWE Object (represented as a string) containing data encrypted by
the SDK for the DS to decrypt.<br>Format <= 64000 AN
ephem_pub_key:
description: >-
Public key component of the ephemeral key pair generated by the 3DS
SDK and used to establish session keys between the 3DS SDK and
ACS.<br>Format Object
reference_number:
type: string
description: >-
ndicates maximum amount of time (in minutes) for all
exchanges.<br>Format <= 2 N
trans_id:
type: string
description: >-
Universally unique transaction identifier assigned by the 3DS SDK to
identify a single transaction.<br>Format = 36 AN
max_timeout:
type: string
description: Max timeout
iface:
type: string
description: >-
Lists all of the SDK Interface types that the device supports for
displaying specific challenge user interfaces within the SDK.<br>01
= Native<br>02 = HTML<br>03 = Both<br>Format = 2 N
example: '01'
ui_type:
type: array
description: >-
Lists all UI types that the device supports for displaying specific
challenge user interfaces within the SDK.<br>01 = Text<br>02 =
Single Select<br>03 = Multi Select<br>04 = OOB<br>05 = HTML Other
(valid only for HTML UI)<br>Format = 2 N[]
example: '[01, 02]'
items:
type: string
Server3DSRootModel:
type: object
description: Server 3DS Root Model
properties:
three_ds_method_url:
type: string
description: 3DS Method URL
three_ds_server:
$ref: '#/components/schemas/ThreeDsServerModel'
description: 3DS Server Model
acs:
$ref: '#/components/schemas/AcsModel'
description: ACS
brand_id:
type: string
description: Brand ID.<br>Format <= 4 N
example: 2
three_ds_comp_ind:
type: string
description: >-
Indicates whether the 3DS Method successfully completed.<br>Y =
Successfully completed<br>N = Did not successfully complete<br>U =
Unavailable— there was no 3DS Method URL related to the
card.<br>Mandatory for device_channel = 02.<br>Format = 1 A
example: 'Y'
pay_token_ind:
type: string
description: >-
A value of true indicates that the transaction was de-tokenised
prior to being received by the ACS.<br>Format <= 5 AN
example: true
pay_token_source:
type: string
description: >-
Indicates where the de-tokenisation occurs.<br>01 - 3DS Server<br>02
- DS<br>Format = 2 N
example: '02'
notification_url:
type: string
description: >-
Fully qualified URL of the 3DS Requestor to receive the CRes
message. Mandatory for device_channel = 02.<br>Format <= 256 AN
example: https://www.requestor.com/notification
decoupled_notification_url:
type: string
description: Decoupled Notification URL
trans_type:
type: string
description: >-
Identifies the type of transaction being authenticated.<br>01 =
Goods/ Service Purchase<br>03 = Check Acceptance<br>10 = Account
Funding<br>11 = Quasi-Cash Transaction<br>28 = Prepaid Activation
and Load<br>Format = 2 N
example: '03'
eci:
type: string
description: Electronic Commerce Indicator.<br>Format <= 2 N
example: '05'
device_channel:
type: string
description: >-
Device channel. 01 = application (APP), 02 = browser
(BRW).<br>Format <= 2 N
example: '02'
three_ri_ind:
type: string
description: >-
Indicates the type of 3RI request.<br>01 = Recurring
transaction<br>02 = Instalment transaction<br>03 = Add card<br>04 =
Maintain card information<br>05 = Account verification<br>06 =
Split/delayed shipment<br>07 = Top-up<br>08 = Mail Order<br>09 =
Telephone Order<br>10 = Whitelist status check<br>11 = Other
payment<br>Mandatory for device_channel = 03.<br>Format = 2 N
example: '01'
challenge_cancel:
type: string
description: >-
Indicator that informs the ACS and DS that the authentication has
been canceled.<br>01 = The cardholder has initiated the
cancellation.<br>03 = Transaction expired. Decoupled flow<br>04 =
Transaction expired in the ACS<br>05 = Transaction expired in the
ACS. First CReq was not received by the ACS.<br>06 = Error in the
transaction.<br>08 = Transaction expired in the 3DS SDK<br>09 =
Error message in response to the CRes message sent by the ACS.<br>10
= Error message in response to the CReq message sent by the
ACS.<br>Format = 2 AN
example: '01'
authentication:
$ref: '#/components/schemas/AuthenticationModel'
description: Authentication
broad_info:
description: >-
Unstructured information sent between the 3DS Server, the DS and the
ACS.<br>Format Object
example: broadInfo
three_ds_requestor:
$ref: '#/components/schemas/ThreeDsRequestorModel'
description: 3DS Requestor
acquirer:
$ref: '#/components/schemas/AcquirerModel'
description: Acquirer
browser:
$ref: '#/components/schemas/BrowserModel'
description: These parameters are mandatory if device_channel = 02.
cardholder:
$ref: '#/components/schemas/CardholderModel'
description: Cardholder
ds:
$ref: '#/components/schemas/DsModel'
description: DS
merchant:
$ref: '#/components/schemas/MerchantModel'
description: Merchant
message:
$ref: '#/components/schemas/MessageModel'
description: Message
purchase:
$ref: '#/components/schemas/PurchaseModel'
description: Purchase
recurring:
$ref: '#/components/schemas/RecurringModel'
description: Recurring
transaction:
$ref: '#/components/schemas/TransactionModel'
description: Transaction
white_list:
$ref: '#/components/schemas/WhiteListModel'
error:
$ref: '#/components/schemas/ErrorModel'
description: Error
sdk:
$ref: '#/components/schemas/SdkModel'
description: SDK. These fields are mandatory for 3DS SDKs (device_channel = 01).
ds_rid:
type: string
description: ds RID
ds_info_version:
type: string
description: ds Info Version
lib_check:
type: string
description: Lib Check
sdk_check:
type: string
description: SDK Check
message_version:
type: string
description: >-
Transaction Version (This version must be used on CRes
request)<br>Format < 8 AN
example: 2.2.0
sdk_origin:
type: string
description: SDK Origin
ThreeDsRequestorModel:
type: object
description: 3DS Requestor
properties:
authentication_ind:
type: string
description: >-
Indicates the type of Authentication request.<br>01 = Payment
transaction<br>02 = Recurring transaction<br>03 = Instalment
transaction<br>04 = Add card<br>05 = Maintain card<br>06 =
Cardholder verification as part of EMV token ID&V<br>Format = 2 N
example: '01'
'authentication_method_ind ':
type: string
description: Authentication Method Indicator
decoupled_max_time:
type: string
description: Decoupled max time
decoupled_request_ind:
type: string
description: Decoupled Request indicator
authentication_info:
$ref: '#/components/schemas/RequestorAuthenticationInfoModel'
description: >-
Information about how the 3DS Requestor authenticated the cardholder
before or during the transaction.
challenge_ind:
type: string
description: >-
This field signals the merchant's preference for the completion (or
not) of the challenge, but unless the parties are aligned, the
issuer may not comply with this request. If this field is not sent,
it will be interpreted as "01 = No preference."<br>01 = No
preference<br>02 = No challenge requested<br>03 = Challenge
requested (3DS Requestor preference)<br>04 = Challenge requested
(Mandate)<br>05 = No challenge requested (transactional risk
analysis is already performed)<br>06 = No challenge requested (Data
share only)<br>07 = No challenge requested (strong consumer
authentication is already performed)<br>08 = No challenge requested
(utilise whitelist exemption if no challenge required)<br>09 =
Challenge requested (whitelist prompt requested if challenge
required)<br>Format = 2 N
example: '01'
id:
type: string
description: DS assigned 3DS Requestor identifier.<br>Format <= 35 AN
example: id
name:
type: string
description: DS assigned 3DS Requestor name.<br>Format <= 40 AN
example: Requestor Name
prior_authentication_info:
$ref: '#/components/schemas/RequestorPriorAuthenticationInfoModel'
description: >-
Information about how the 3DS Requestor authenticated the cardholder
as part of a previous 3DS transaction.
url:
type: string
description: >-
Fully qualified URL of 3DS Requestor website or customer care
site.<br>Format <= 2048 AN
example: https://www.requestor.com
ThreeDsServerModel:
type: object
description: 3DS Server Model
properties:
trans_id:
type: string
description: 3DS Server ID transaction.<br>Format = 35 AN
example: 12341234-1234-1234-1234-123412341234
status:
type: string
description: 3DS Server Status.<br>Format = 3 AN
enum:
- NEW
- INV
- ERR
- EXP
- ERM
- AUY
- AUN
- AUU
- AUA
- AUC
- AUR
- AUD
example: AUY
TransactionModel:
type: object
description: Transaction Model
properties:
status:
type: string
description: >-
Indicates whether a transaction qualifies as an authenticated
transaction or account verification.<br>Y = Authentication
Verification Successful.<br>N = Not Authenticated /Account Not
Verified; Transaction denied.<br>U = Authentication/ Account
Verification Could Not Be Performed; Technical or other problem, as
indicated in ARes or RReq.<br>A = Attempts Processing Performed; Not
Authenticated/Verified, but a proof of attempted
authentication/verification is provided.<br>C = Challenge Required;
Additional authentication is required using the CReq/CRes.<br>D =
Challenge Required; Decoupled Authentication confirmed.<br>R =
Authentication/ Account Verification Rejected; Issuer is rejecting
authentication/verification and request that authorisation not be
attempted.<br>Format = 1 AN
example: 'N'
status_reason:
type: string
description: >-
Provides information on why the Transaction Status field has the
specified value.<br>01 = Card authentication failed<br>02 = Unknown
Device<br>03 = Unsupported Device<br>04 = Exceeds authentication
frequency limit<br>05 = Expired card<br>06 = Invalid card
number<br>07 = Invalid transaction<br>08 = No Card record<br>09 =
Security failure<br>10 = Stolen card<br>11 = Suspected fraud<br>12 =
Transaction not permitted to cardholder<br>13 = Cardholder not
enrolled in service<br>14 = Transaction timed out at the ACS<br>15 =
Low confidence<br>16 = Medium confidence<br>17 = High
confidence<br>18 = Very High confidence<br>19 = Exceeds ACS maximum
challenges<br>20 = Non-Payment transaction not supported<br>21 = 3RI
transaction not supported<br>22 = ACS technical issue<br>23 =
Decoupled Authentication required by ACS but not requested by 3DS
Requestor<br>24 = 3DS Requestor Decoupled Max Expiry Time
exceeded<br>25 = Decoupled Authentication was provided insufficient
time to authenticate cardholder. ACS will not make attempt<br>26 =
Authentication attempted but not performed by the
cardholder<br>Format = 2 N
example: '01'
WhiteListModel:
type: object
description: White Liste Model
properties:
status:
type: string
description: >-
Enables the communication of trusted beneficiary/whitelist status
between the ACS, the DS and the 3DS Requestor.<br>Y = 3DS Requestor
is whitelisted by cardholder<br>N = 3DS Requestor is not whitelisted
by cardholder<br>E = Not eligible as determined by issuer<br>P =
Pending confirmation by cardholder<br>R = Cardholder rejected<br>U =
Whitelist status unknown, unavailable, or does not apply<br>Format =
1 AN
example: 'Y'
'status_source ':
type: string
description: >-
This data element will be populated by the system setting Whitelist
Status.<br>01 = 3DS Server<br>02 = DS<br>03 = ACS<br>Format = 2 N
example: '01'
JSON
{
"openapi": "3.1.0",
"info": {
"title": "OpenAPI definition",
"version": "v0"
},
"servers": [
{
"url": "https://localhost:8443",
"description": "Generated server url"
}
],
"paths": {
"/v3/authentication/{transId}": {
"put": {
"tags": [
"authentication-controller"
],
"summary": "Authentication service V3",
"description": "After creating the transaction, it's necessary to call the authentication service to continue the flow. If the AUC status is returned, a challenge must be initiated. For the AUD status, the \"decoupled\" flow must be followed. Otherwise, further calls won't be required.",
"operationId": "doAuthenticationV3",
"parameters": [
{
"name": "Client-Request-Id",
"in": "header",
"description": "UUID v4 generated following the RFC 4122 specification, unique to each transaction.<br>Format = 26 H (UUID v4)",
"required": true,
"schema": {
"type": "string",
"description": "UUID v4 generated following the RFC 4122 specification, unique to each transaction.<br>Format = 26 H (UUID v4)",
"example": "d608388f-8351-4ef7-a693-a48dc7651502"
},
"example": "d608388f-8351-4ef7-a693-a48dc7651502"
},
{
"name": "Authorization",
"in": "header",
"description": "Generated HMAC signature.",
"required": true,
"schema": {
"type": "string",
"description": "Generated HMAC signature."
}
},
{
"name": "Auth-Token-Type",
"in": "header",
"description": "Describes which Authorization type is being used.",
"required": true,
"schema": {
"type": "string",
"description": "Describes which Authorization type is being used.",
"example": "HMAC"
},
"example": "HMAC"
},
{
"name": "merchant-id",
"in": "header",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"required": true,
"schema": {
"type": "string",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "merchant-key",
"in": "header",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"required": false,
"schema": {
"type": "string",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat-merchant-id",
"in": "header",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"required": false,
"schema": {
"type": "string",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat-merchant-key",
"in": "header",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"required": false,
"schema": {
"type": "string",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"example": "zzzzzzzzzzzzzz"
},
"example": "zzzzzzzzzzzzzz"
},
{
"name": "api-key",
"in": "header",
"description": "HMAC key",
"required": true,
"schema": {
"type": "string",
"description": "HMAC key",
"example": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
{
"name": "transId",
"in": "path",
"description": "3DS Server Transaction ID",
"required": true,
"schema": {
"type": "string",
"description": "3DS Server Transaction ID",
"example": "zzzzzzzzzzzzzz"
},
"example": "zzzzzzzzzzzzzz"
}
],
"requestBody": {
"description": "Below are some examples of the authentication.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Server3DSRootModel"
},
"examples": {
"Frictionless Flow": {
"description": "Frictionless Flow",
"value": {
"three_ds_comp_ind": "Y",
"pay_token_ind": "false",
"notification_url": "https://www.requestor.com/notification",
"trans_type": "01",
"three_ds_requestor": {
"authentication_ind": "01",
"id": "id",
"name": "Loja de Testes",
"url": "https://www.requestor.com"
},
"acquirer": {
"bin": "2",
"merchant_id": "00000000"
},
"browser": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip": "10.20.30.40",
"javascript_enabled": "true",
"java_enabled": "false",
"language": "pt-BR",
"color_depth": "24",
"screen_height": "864",
"screen_width": "1536",
"tz": "180",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder": {
"card_expiry_date": "2212",
"name": "Joaquim",
"acct": {
"type": "02",
"encrypted_number": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"merchant": {
"mcc": "1234",
"country_code": "BRA",
"name": "Loja de Teste"
},
"message": {
"category": "01"
},
"purchase": {
"amount": "10000",
"currency": "986",
"exponent": "2",
"date": "date"
}
}
},
"Challenge Flow": {
"description": "Challenge Flow",
"value": {
"three_ds_comp_ind": "Y",
"pay_token_ind": "false",
"notification_url": "https://www.requestor.com/notification",
"trans_type": "01",
"three_ds_requestor": {
"authentication_ind": "01",
"id": "id",
"name": "Loja de Testes",
"url": "https://www.requestor.com"
},
"acquirer": {
"bin": "2",
"merchant_id": "00000000"
},
"browser": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip": "10.20.30.40",
"javascript_enabled": "true",
"java_enabled": "false",
"language": "pt-BR",
"color_depth": "24",
"screen_height": "864",
"screen_width": "1536",
"tz": "180",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder": {
"card_expiry_date": "2212",
"name": "Joaquim",
"acct": {
"type": "02",
"encrypted_number": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"merchant": {
"mcc": "1234",
"country_code": "BRA",
"name": "Loja de Teste"
},
"message": {
"category": "01"
},
"purchase": {
"amount": "10004",
"currency": "986",
"exponent": "2",
"date": "date"
}
}
},
"Data Only - Mastercard and Visa": {
"description": "Data Only - Mastercard and Visa",
"value": {
"three_ds_comp_ind": "Y",
"pay_token_ind": "false",
"notification_url": "https://www.requestor.com/notification",
"decoupled_notification_url": "https://www.requestor.com/decoupled_notification",
"trans_type": "01",
"three_ds_requestor": {
"authentication_ind": "01",
"decoupled_max_time": "10",
"id": "id",
"name": "Loja de Testes",
"url": "https://www.requestor.com"
},
"acquirer": {
"bin": "2",
"merchant_id": "00000000"
},
"browser": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip": "10.20.30.40",
"javascript_enabled": "true",
"java_enabled": "false",
"language": "pt-BR",
"color_depth": "24",
"screen_height": "864",
"screen_width": "1536",
"tz": "180",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder": {
"card_expiry_date": "2212",
"name": "Joaquim",
"acct": {
"type": "02",
"encrypted_number": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"merchant": {
"mcc": "mcc",
"country_code": "BRA",
"name": "Loja de Teste"
},
"message": {
"category": "80"
},
"purchase": {
"amount": "10000",
"currency": "986",
"exponent": "2",
"date": "date"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "If successful, the HTTP response code will be 200",
"content": {
"*/*": {
"examples": {
"Frictionless Flow Response": {
"description": "Frictionless Flow Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUY"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "Y"
},
"message_version": "2.2.0"
}
},
"Challenge Flow Response": {
"description": "Challenge Flow Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUC"
},
"acs": {
"challenge_mandated": "Y",
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321",
"url": "https://www.acs.com/challenge"
},
"device_channel": "02",
"authentication": {
"type": "01"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "C"
},
"message_version": "2.2.0"
}
},
"Data Only Response": {
"description": "Data Only Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUU"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "04",
"device_channel": "02",
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "U",
"status_reason": "80"
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"*/*": {
"examples": {
"Card number out of range Response": {
"description": "The card number is outside of supported card range. Other invalid inputs will also result in a \"INV\" status",
"value": {
"three_ds_server": {
"trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "305",
"component": "S",
"description": "Cardholder Account Number is not in a range belonging to Issuer",
"detail": "acctNumber"
}
}
},
"DS Communication error Response": {
"description": "There was an error during communication with DS",
"value": {
"three_ds_server": {
"trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
"status": "ERR"
},
"device_channel": "02",
"error": {
"code": "405",
"component": "S",
"description": "DS communication failure",
"detail": "acctNumber"
}
}
},
"DS error message Response": {
"description": "DS returned an error message",
"value": {
"three_ds_server": {
"trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
"status": "ERM"
},
"device_channel": "02",
"error": {
"code": "",
"component": "S",
"description": "3DS Server received an error message from DS",
"detail": "acctNumber"
}
}
}
}
}
}
},
"default": {
"description": "Any other code must be interpreted as an error",
"content": {
"*/*": {
"examples": {
"Error Response": {
"description": "Error Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "1",
"component": "S",
"description": "Error description",
"detail": "Error detail"
}
}
}
}
}
}
}
}
}
},
"/v2/authentication/{transId}": {
"put": {
"tags": [
"authentication-controller"
],
"summary": "Authentication service",
"description": "After creating the transaction, it's necessary to call the authentication service to continue the flow. If the AUC status is returned, a challenge must be initiated. For the AUD status, the \"decoupled\" flow must be followed. Otherwise, further calls won't be required.",
"operationId": "doAuthentication",
"parameters": [
{
"name": "merchant_id",
"in": "header",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"required": true,
"schema": {
"type": "string",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "merchant_key",
"in": "header",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"required": true,
"schema": {
"type": "string",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat_merchant_id",
"in": "header",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"required": false,
"schema": {
"type": "string",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat_merchant_key",
"in": "header",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"required": false,
"schema": {
"type": "string",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"example": "zzzzzzzzzzzzzz"
},
"example": "zzzzzzzzzzzzzz"
},
{
"name": "transId",
"in": "path",
"description": "3DS Server Transaction ID",
"required": true,
"schema": {
"type": "string",
"description": "3DS Server Transaction ID",
"example": "zzzzzzzzzzzzzz"
},
"example": "zzzzzzzzzzzzzz"
}
],
"requestBody": {
"description": "Below are some examples of the authentication.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Server3DSRootModel"
},
"examples": {
"Frictionless Flow": {
"description": "Frictionless Flow",
"value": {
"three_ds_comp_ind": "Y",
"pay_token_ind": "false",
"notification_url": "https://www.requestor.com/notification",
"trans_type": "01",
"three_ds_requestor": {
"authentication_ind": "01",
"id": "id",
"name": "Loja de Testes",
"url": "https://www.requestor.com"
},
"acquirer": {
"bin": "2",
"merchant_id": "00000000"
},
"browser": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip": "10.20.30.40",
"javascript_enabled": "true",
"java_enabled": "false",
"language": "pt-BR",
"color_depth": "24",
"screen_height": "864",
"screen_width": "1536",
"tz": "180",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder": {
"card_expiry_date": "2212",
"name": "Joaquim",
"acct": {
"type": "02",
"number": "1234123412341234"
}
},
"merchant": {
"mcc": "1234",
"country_code": "BRA",
"name": "Loja de Teste"
},
"message": {
"category": "01"
},
"purchase": {
"amount": "10000",
"currency": "986",
"exponent": "2",
"date": "date"
}
}
},
"Challenge Flow": {
"description": "Challenge Flow",
"value": {
"three_ds_comp_ind": "Y",
"pay_token_ind": "false",
"notification_url": "https://www.requestor.com/notification",
"trans_type": "01",
"three_ds_requestor": {
"authentication_ind": "01",
"id": "id",
"name": "Loja de Testes",
"url": "https://www.requestor.com"
},
"acquirer": {
"bin": "2",
"merchant_id": "00000000"
},
"browser": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip": "10.20.30.40",
"javascript_enabled": "true",
"java_enabled": "false",
"language": "pt-BR",
"color_depth": "24",
"screen_height": "864",
"screen_width": "1536",
"tz": "180",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder": {
"card_expiry_date": "2212",
"name": "Joaquim",
"acct": {
"type": "02",
"number": "1234123412341234"
}
},
"merchant": {
"mcc": "1234",
"country_code": "BRA",
"name": "Loja de Teste"
},
"message": {
"category": "01"
},
"purchase": {
"amount": "10004",
"currency": "986",
"exponent": "2",
"date": "date"
}
}
},
"Data Only - Mastercard and Visa": {
"description": "Data Only - Mastercard and Visa",
"value": {
"three_ds_comp_ind": "Y",
"pay_token_ind": "false",
"notification_url": "https://www.requestor.com/notification",
"decoupled_notification_url": "https://www.requestor.com/decoupled_notification",
"trans_type": "01",
"three_ds_requestor": {
"authentication_ind": "01",
"decoupled_max_time": "10",
"id": "id",
"name": "Loja de Testes",
"url": "https://www.requestor.com"
},
"acquirer": {
"bin": "2",
"merchant_id": "00000000"
},
"browser": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"ip": "10.20.30.40",
"javascript_enabled": "true",
"java_enabled": "false",
"language": "pt-BR",
"color_depth": "24",
"screen_height": "864",
"screen_width": "1536",
"tz": "180",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
},
"cardholder": {
"card_expiry_date": "2212",
"name": "Joaquim",
"acct": {
"type": "02",
"number": "1234123412341234"
}
},
"merchant": {
"mcc": "mcc",
"country_code": "BRA",
"name": "Loja de Teste"
},
"message": {
"category": "80"
},
"purchase": {
"amount": "10000",
"currency": "986",
"exponent": "2",
"date": "date"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "If successful, the HTTP response code will be 200",
"content": {
"*/*": {
"examples": {
"Frictionless Flow Response": {
"description": "Frictionless Flow Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUY"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "Y"
},
"message_version": "2.2.0"
}
},
"Challenge Flow Response": {
"description": "Challenge Flow Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUC"
},
"acs": {
"challenge_mandated": "Y",
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321",
"url": "https://www.acs.com/challenge"
},
"device_channel": "02",
"authentication": {
"type": "01"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "C"
},
"message_version": "2.2.0"
}
},
"Data Only Response": {
"description": "Data Only Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "AUU"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "43214321-4321-4321-4321-432143214321"
},
"eci": "04",
"device_channel": "02",
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "56785678-5678-5678-5678-567856875678"
},
"transaction": {
"status": "U",
"status_reason": "80"
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"*/*": {
"examples": {
"Card number out of range Response": {
"description": "The card number is outside of supported card range. Other invalid inputs will also result in a \"INV\" status",
"value": {
"three_ds_server": {
"trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "305",
"component": "S",
"description": "Cardholder Account Number is not in a range belonging to Issuer",
"detail": "acctNumber"
}
}
},
"DS Communication error Response": {
"description": "There was an error during communication with DS",
"value": {
"three_ds_server": {
"trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
"status": "ERR"
},
"device_channel": "02",
"error": {
"code": "405",
"component": "S",
"description": "DS communication failure",
"detail": "acctNumber"
}
}
},
"DS error message Response": {
"description": "DS returned an error message",
"value": {
"three_ds_server": {
"trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
"status": "ERM"
},
"device_channel": "02",
"error": {
"code": "",
"component": "S",
"description": "3DS Server received an error message from DS",
"detail": "acctNumber"
}
}
}
}
}
}
},
"default": {
"description": "Any other code must be interpreted as an error",
"content": {
"*/*": {
"examples": {
"Error Response": {
"description": "Error Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "1",
"component": "S",
"description": "Error description",
"detail": "Error detail"
}
}
}
}
}
}
}
}
}
},
"/v3/authentication": {
"post": {
"tags": [
"authentication-controller"
],
"summary": "Transaction creation service V3",
"description": "This call is required to obtain the 3DS Method URL corresponding to the card, besides creating a 3DS Server transaction, which will be used in the following steps of the flow.\r\nImportant: The value of the message_version field returned in the response must be used in the CREQ step (for challenge transactions).",
"operationId": "beginAuthenticationV3",
"parameters": [
{
"name": "Client-Request-Id",
"in": "header",
"description": "UUID v4 generated following the RFC 4122 specification, unique to each transaction.<br>Format = 26 H (UUID v4)",
"required": true,
"schema": {
"type": "string",
"description": "UUID v4 generated following the RFC 4122 specification, unique to each transaction.<br>Format = 26 H (UUID v4)",
"example": "d608388f-8351-4ef7-a693-a48dc7651502"
},
"example": "d608388f-8351-4ef7-a693-a48dc7651502"
},
{
"name": "Authorization",
"in": "header",
"description": "Generated HMAC signature.",
"required": true,
"schema": {
"type": "string",
"description": "Generated HMAC signature."
}
},
{
"name": "Auth-Token-Type",
"in": "header",
"description": "Describes which Authorization type is being used.",
"required": true,
"schema": {
"type": "string",
"description": "Describes which Authorization type is being used.",
"example": "HMAC"
},
"example": "HMAC"
},
{
"name": "merchant-id",
"in": "header",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"required": true,
"schema": {
"type": "string",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "merchant-key",
"in": "header",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"required": false,
"schema": {
"type": "string",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat-merchant-id",
"in": "header",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"required": false,
"schema": {
"type": "string",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat-merchant-key",
"in": "header",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"required": false,
"schema": {
"type": "string",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"example": "zzzzzzzzzzzzzz"
},
"example": "zzzzzzzzzzzzzz"
},
{
"name": "api-key",
"in": "header",
"description": "HMAC key",
"required": true,
"schema": {
"type": "string",
"description": "HMAC key",
"example": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Server3DSRootModel"
},
"examples": {
"Encrypted card number authentication": {
"description": "Payload using encrypted card number for this functionality must have this format.",
"value": {
"cardholder": {
"acct": {
"encrypted_number": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"brand_id": "2"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "If successful, the HTTP response code will be 200",
"content": {
"*/*": {
"examples": {
"Encrypted Card number authentication": {
"description": "Response when using encrypted card number for this functionality.",
"value": {
"three_ds_method_url": "https://www.example.com",
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"message_version": "2.2.0"
}
}
}
}
}
},
"default": {
"description": "Any other code must be interpreted as an error",
"content": {
"*/*": {
"examples": {
"Error Response": {
"summary": "Error Response",
"description": "Error Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "1",
"component": "S",
"description": "Error description",
"detail": "Error detail"
}
}
}
}
}
}
}
}
}
},
"/v2/authentication": {
"post": {
"tags": [
"authentication-controller"
],
"summary": "Transaction creation service",
"description": "This call is required to obtain the 3DS Method URL corresponding to the card, besides creating a 3DS Server transaction, which will be used in the following steps of the flow.\r\nImportant: The value of the message_version field returned in the response must be used in the CREQ step (for challenge transactions).",
"operationId": "beginAuthentication",
"parameters": [
{
"name": "merchant_id",
"in": "header",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"required": true,
"schema": {
"type": "string",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format < 15 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "merchant_key",
"in": "header",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"required": true,
"schema": {
"type": "string",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format < 80 AN, Mandatory YES",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat_merchant_id",
"in": "header",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"required": false,
"schema": {
"type": "string",
"description": "Carat merchant code must be sent only if the token field is sent in the request.<br>Format < 15 AN, Mandatory COND",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "carat_merchant_key",
"in": "header",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"required": false,
"schema": {
"type": "string",
"description": "The authentication key of the Carat merchant must be sent only if the token field is sent in the request.<br>Format < 80 AN",
"example": "zzzzzzzzzzzzzz"
},
"example": "zzzzzzzzzzzzzz"
},
{
"name": "Authorization",
"in": "header",
"description": "Merchant's signature in the Bearer {signature} format. Example: Bearer {TOKEN_JWT_EXAMPLE} Format < 2000 AN",
"required": false,
"schema": {
"type": "string",
"description": "Merchant's signature in the Bearer {signature} format. Example: Bearer {TOKEN_JWT_EXAMPLE} Format < 2000 AN",
"example": "Bearer {TOKEN_JWT_EXAMPLE}"
},
"example": "Bearer {TOKEN_JWT_EXAMPLE}"
}
],
"requestBody": {
"description": "It is possible to generate the signature using 2 different payloads",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Server3DSRootModel"
},
"examples": {
"Card number authentication": {
"description": "Payload using card number for this functionality must have this format.",
"value": {
"cardholder": {
"acct": {
"number": "1234123412341234"
}
},
"brand_id": "2"
}
},
"Token authentication": {
"description": "Payload using token for this functionality must have this format.",
"value": {
"cardholder": {
"acct": {
"token": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
},
"brand_id": "2"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "If successful, the HTTP response code will be 200",
"content": {
"*/*": {
"examples": {
"Card number authentication": {
"description": "Response when using card number for this functionality.",
"value": {
"three_ds_method_url": "https://www.example.com",
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"message_version": "2.2.0"
}
},
"Token authentication": {
"description": "Response when using token for this functionality.",
"value": {
"three_ds_method_url": "https://www.example.com",
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"message_version": "2.2.0"
}
}
}
}
}
},
"default": {
"description": "Any other code must be interpreted as an error",
"content": {
"*/*": {
"examples": {
"Error Response": {
"summary": "Error Response",
"description": "Error Response",
"value": {
"three_ds_server": {
"trans_id": "12341234-1234-1234-1234-123412341234",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "1",
"component": "S",
"description": "Error description",
"detail": "Error detail"
}
}
}
}
}
}
}
}
}
},
"/v3/transaction/{transId}": {
"get": {
"tags": [
"transaction-controller"
],
"summary": "Transaction query service V3",
"description": "This call allows 3DS Requestor to query the status of a transaction. This operation must be used by 3DS Requestor in case of problems receiving the CRes. We will return status, ECI and CAVV, which are necessary to proceed with an authorization.",
"operationId": "queryV3",
"parameters": [
{
"name": "transId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Client-Request-Id",
"in": "header",
"description": "UUID v4 generated following the RFC 4122 specification, unique to each transaction.<br>Format = 26 H (UUID v4)",
"required": true,
"schema": {
"type": "string",
"description": "UUID v4 generated following the RFC 4122 specification, unique to each transaction.<br>Format = 26 H (UUID v4)",
"example": "d608388f-8351-4ef7-a693-a48dc7651502"
},
"example": "d608388f-8351-4ef7-a693-a48dc7651502"
},
{
"name": "Authorization",
"in": "header",
"description": "Generated HMAC signature.",
"required": true,
"schema": {
"type": "string",
"description": "Generated HMAC signature."
}
},
{
"name": "Auth-Token-Type",
"in": "header",
"description": "Describes which Authorization type is being used.",
"required": true,
"schema": {
"type": "string",
"description": "Describes which Authorization type is being used.",
"example": "HMAC"
},
"example": "HMAC"
},
{
"name": "merchant-id",
"in": "header",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format <= 15 AN",
"required": true,
"schema": {
"type": "string",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format <= 15 AN",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "merchant-key",
"in": "header",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format <= 80 AN",
"required": true,
"schema": {
"type": "string",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format <= 80 AN",
"example": "xxxxxxxxxxx"
},
"example": "xxxxxxxxxxx"
},
{
"name": "api-key",
"in": "header",
"description": "HMAC key",
"required": true,
"schema": {
"type": "string",
"description": "HMAC key",
"example": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
],
"responses": {
"200": {
"description": "If successful, the HTTP response code will be 200",
"content": {
"*/*": {
"examples": {
"Default Response": {
"description": "Default Response",
"value": {
"three_ds_server": {
"trans_id": "12345678-1234-1234-1234-123456789012",
"status": "AUY"
},
"brand_id": "2",
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"message_version": "2.2.0"
}
},
"Challenge Cancel Response": {
"description": "Challenge Cancel Response",
"value": {
"three_ds_server": {
"trans_id": "12345678-1234-1234-1234-123456789012",
"status": "AUY"
},
"brand_id": "2",
"challenge_cancel": "01",
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"message_version": "2.2.0"
}
}
}
}
}
}
}
}
},
"/v2/transaction/{transId}": {
"get": {
"tags": [
"transaction-controller"
],
"summary": "Transaction query service",
"description": "This call allows 3DS Requestor to query the status of a transaction. This operation must be used by 3DS Requestor in case of problems receiving the CRes. We will return status, ECI and CAVV, which are necessary to proceed with an authorization.",
"operationId": "query",
"parameters": [
{
"name": "transId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "merchant_id",
"in": "header",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format <= 15 AN",
"required": true,
"schema": {
"type": "string",
"description": "Merchant code on 3DS Server. The production and certification codes will be different.<br>Format <= 15 AN",
"example": "xxxxxxxxxxxxxxx"
},
"example": "xxxxxxxxxxxxxxx"
},
{
"name": "merchant_key",
"in": "header",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format <= 80 AN",
"required": true,
"schema": {
"type": "string",
"description": "Merchant authentication key on 3DS Server. The production and certification keys will be different.<br>Format <= 80 AN",
"example": "xxxxxxxxxxx"
},
"example": "xxxxxxxxxxx"
}
],
"responses": {
"200": {
"description": "If successful, the HTTP response code will be 200",
"content": {
"*/*": {
"examples": {
"Default Response": {
"description": "Default Response",
"value": {
"three_ds_server": {
"trans_id": "12345678-1234-1234-1234-123456789012",
"status": "AUY"
},
"brand_id": "2",
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"message_version": "2.2.0"
}
},
"Challenge Cancel Response": {
"description": "Challenge Cancel Response",
"value": {
"three_ds_server": {
"trans_id": "12345678-1234-1234-1234-123456789012",
"status": "AUY"
},
"brand_id": "2",
"challenge_cancel": "01",
"eci": "05",
"device_channel": "02",
"authentication": {
"value": "1234567890123456789012345678"
},
"message_version": "2.2.0"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AcctInfoModel": {
"type": "object",
"description": "Account Info Model",
"properties": {
"ch_acc_age_ind": {
"type": "string",
"description": "Length of time that the cardholder has had the account with the 3DS Requestor.<br>01 = No account (guest check-out)<br>02 = Created during this transaction<br>03 = Less than 30 days<br>04 = 30-60 days<br>05 = More than 60 days<br>Format = 2 N",
"example": "02"
},
"ch_acc_change": {
"type": "string",
"description": "Date that the cardholder's account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added, in YYYYMMDD format.<br>Format = 8 N",
"example": 20250101
},
"ch_acc_change_ind": {
"type": "string",
"description": "Length of time since the cardholder's account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.<br>01 = Changed during this transaction<br>02 = Less than 30 days<br>03 = 30-60 days<br>04 = More than 60 days<br>Format = 2 N",
"example": "01"
},
"ch_acc_date": {
"type": "string",
"description": "Date that the cardholder opened the account with the 3DS Requestor in YYYYMMDD format.<br>Format = 8 N",
"example": 20250101
},
"ch_acc_pw_change": {
"type": "string",
"description": "Date that cardholder's account with the 3DS Requestor had a password change or account reset in YYYYMMDD format.<br>Format = 8 N",
"example": 20250101
},
"ch_acc_pw_change_ind": {
"type": "string",
"description": "Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.<br>01 = No change<br>02 = Changed during this transaction<br>03 = Less than 30 days<br>04 = 30-60 days<br>05 = More than 60 days<br>= 2 N",
"example": "02"
},
"nb_purchase_account": {
"type": "string",
"description": "Number of purchases with this cardholder account during the previous six months.<br>Format <= 4 N",
"example": 2
},
"provision_attempts_day": {
"type": "string",
"description": "Number of Add Card attempts in the last 24 hours.<br>Format <= 3 N",
"example": 2
},
"txn_activity_day": {
"type": "string",
"description": "Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.<br>Format <= 3 N",
"example": 2
},
"txn_activity_year": {
"type": "string",
"description": "Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.<br>Format <= 3 N",
"example": 2
},
"payment_acc_age": {
"type": "string",
"description": "Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor in YYYYMMDD format.<br>Format = 8 N",
"example": 20250101
},
"payment_acc_ind": {
"type": "string",
"description": "Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.<br>01 = No account (guest check-out)<br>02 = During this transaction<br>03 = Less than 30 days<br>04 = 30-60 days<br>05 = More than 60 days<br>Format = 2 N",
"example": "02"
},
"ship_address_usage": {
"type": "string",
"description": "Date when the shipping address used for this transaction was first used with the 3DS Requestor in YYYYMMDD format.<br>Format = 8 N",
"example": 20250101
},
"ship_address_usage_ind": {
"type": "string",
"description": "Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.<br>01 = This transaction<br>02 = Less than 30 days<br>03 = 30-60 days<br>04 = More than 60 days<br>Format = 2 N",
"example": "01"
},
"ship_name_indicator": {
"type": "string",
"description": "Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.<br>01 = Account Name identical to shipping Name<br>02 = Account Name different than shipping Name<br>Format = 2 N",
"example": "01"
},
"suspicious_acc_activity": {
"type": "string",
"description": "Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.<br>01 = No suspicious activity has been observed<br>02 = Suspicious activity has been observed<br>Format = 2 N",
"example": "01"
}
}
},
"AcctModel": {
"type": "object",
"description": "Account Model",
"properties": {
"type": {
"type": "string",
"description": "Indicates the type of account. For example, for a multi-account card product.<br>01 = Not Applicable<br>02 = Credit<br>03 = Debit<br>Format = 2 N",
"example": "02"
},
"number": {
"type": "string",
"description": "Customer's card number (PAN), the number or token field must always be sent in the request<br>Format = 19 N",
"example": 5555555555555555000
},
"id": {
"type": "string",
"description": "Additional information about the account optionally provided by the 3DS Requestor.<br>Format <= 64 AN",
"example": "02"
},
"info": {
"$ref": "#/components/schemas/AcctInfoModel",
"description": "Account Info"
},
"token": {
"type": "string",
"description": "HASH of a card stored in Carat, the number or token field must always be sent in the request<br>Format = 88 AN",
"example": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
},
"encrypted_number": {
"type": "string",
"description": "Encypted customer's card number (PAN)",
"example": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
}
}
},
"AcquirerModel": {
"type": "object",
"description": "Acquirer Model",
"properties": {
"bin": {
"type": "string",
"description": "Acquiring institution identification code as assigned by the DS receiving the AReq message.<br>Format <= 11 AN"
},
"merchant_id": {
"type": "string",
"description": "Acquirer-assigned Merchant identifier.<br>Format <= 35 AN"
}
}
},
"AcsModel": {
"type": "object",
"description": "ACS Model",
"properties": {
"challenge_mandated": {
"type": "string",
"description": "Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.<br>Y = Challenge is mandated<br>N = Challenge is not mandated<br>Format = 1 AN",
"example": "Y"
},
"operator_id": {
"type": "string",
"description": "DS assigned ACS identifier.<br>Format <= 32 N",
"example": "acsOperatorID"
},
"reference_number": {
"type": "string",
"description": "Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.<br>Format <= 32 AN",
"example": "acsReferenceNumber"
},
"trans_id": {
"type": "string",
"description": "Universally Unique transaction identifier assigned by the ACS to identify a single transaction.<br>Format = 36 AN",
"example": "43214321-4321-4321-4321-432143214321"
},
"url": {
"type": "string",
"description": "Fully qualified URL of the ACS to be used for the challenge.<br>Format <= 2048 AN",
"example": "https://www.acs.com/challenge"
},
"decoupled_confirmation_ind": {
"type": "string",
"description": "Indicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder.<br>Y = Confirms Decoupled Authentication will be utilised<br>N = Decoupled Authentication will not be utilised<br>Format = 1 AN",
"example": "N"
},
"signed_content": {
"type": "string",
"description": "Contains the JWS object (represented as a string) created by the ACS for the ARes message.<br>Format var. AN"
},
"iface": {
"type": "string",
"description": "This the ACS interface that the challenge will present to the cardholder.<br>01 = Native UI<br>02 = HTML UI<br>Format = 2 N",
"example": "02"
},
"ui_template": {
"type": "string",
"description": "Identifies the UI Template format that the ACS first presents to the consumer.<br>01 = Text<br>02 = Single Select<br>03 = Multi Select<br>04 = OOB<br>05 = HTML Other<br>Format = 2 N",
"example": "01"
},
"protocol_version": {
"$ref": "#/components/schemas/ProtocolVersionModel",
"description": "Protocol Version"
}
}
},
"AuthenticationModel": {
"type": "object",
"description": "Authentication Model",
"properties": {
"type": {
"type": "string",
"description": "Authentication value (CAVV).<br>Format <= 22 AN",
"example": 1.2345678901234569e+27
},
"value": {
"type": "string",
"description": "Indicates the type of authentication method the Issuer will use to challenge the Cardholder.01 = Static<br>02 = Dynamic<br>03 = OOB<br>04 = Decoupled<br>Format = 2 AN",
"example": "01"
}
}
},
"BrowserModel": {
"type": "object",
"description": "Browser Model",
"properties": {
"accept_header": {
"type": "string",
"description": "Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser.<br>Format <= 2048 AN",
"example": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8"
},
"ip": {
"type": "string",
"description": "IP address of the browser as returned by the HTTP headers to the 3DS Requestor.<br>Format < 45 AN",
"example": "10.20.30.40"
},
"java_enabled": {
"type": "string",
"description": "Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.<br>Format < 5 AN",
"example": false
},
"javascript_enabled": {
"type": "string",
"description": "Boolean that represents the ability of the cardholder browser to execute JavaScript.<br>Format < 5 AN",
"example": true
},
"language": {
"type": "string",
"description": "Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.<br>Format < 8 AN",
"example": "pt-BR"
},
"color_depth": {
"type": "string",
"description": "Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.<br>1 = 1 bit<br>4 = 4 bits<br>8 = 8 bits<br>15 = 15 bits<br>16 = 16 bits<br>24 = 24 bits<br>32 = 32 bits<br>48 = 48 bits<br>Note: If the value in the request differs from the ones specified above, the nearest value will be selected, always favoring the smaller one.<br>Example: 30 will be chosen as 24.<br>Format < 2 N",
"example": 24
},
"screen_height": {
"type": "string",
"description": "Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.<br>Format < 6 N",
"example": 864
},
"screen_width": {
"type": "string",
"description": "Total width of the cardholder's screen in pixels. Value is returned from the screen.width property.<br>Format < 6 AN",
"example": 1536
},
"tz": {
"type": "string",
"description": "Time-zone offset in minutes between UTC and the Cardholder browser local time. Value is returned from the getTimezoneOffset() method.<br>Format < 5 AN",
"example": 180
},
"user_agent": {
"type": "string",
"description": "Exact content of the HTTP user-agent header.<br>Format < 2048 AN",
"example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
}
}
},
"CardholderAddressModel": {
"type": "object",
"description": "Cardholder Address Model",
"properties": {
"city": {
"type": "string",
"description": "The city of the Cardholder address associated with the card used for this purchase.<br>Format <= 50 AN"
},
"country": {
"type": "string",
"description": "The ISO 3166-1 numeric three-digit country code of the Cardholder address associated with the card used for this purchase.<br>Format = 3 N"
},
"line1": {
"type": "string",
"description": "First line of the street address or equivalent local portion of the Cardholder address associated with the card used for this purchase.<br>Format <= 50 AN"
},
"line2": {
"type": "string",
"description": "Second line of the street address or equivalent local portion of the Cardholder address associated with the card used for this purchase.<br>Format <= 50 AN"
},
"line3": {
"type": "string",
"description": "Third line of the street address or equivalent local portion of the Cardholder address associated with the card used for this purchase.<br>Format <= 50 AN"
},
"post_code": {
"type": "string",
"description": "ZIP or other postal code of the Cardholder address associated with the card used for this purchase.<br>Format <= 16 AN"
},
"state": {
"type": "string",
"description": "The state or province of the Cardholder address associated with the card used for this purchase.<br>Format <= 3 AN"
}
}
},
"CardholderModel": {
"type": "object",
"description": "Cardholder Model",
"properties": {
"card_expiry_date": {
"type": "string",
"description": "Expiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder in YYMM format.<br>Format = 4 N"
},
"addr_match": {
"type": "string",
"description": "Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.<br>Y = Shipping Address matches Billing Address<br>N = Shipping Address does not match Billing Address<br>Format = 1 AN"
},
"email": {
"type": "string",
"description": "While not mandatory, it is advisable to send this field as it aids in risk assessment, increasing the likelihood of obtaining a silent authentication. <br>Format <= 256 AN"
},
"info": {
"type": "string",
"description": "Name of the Cardholder.<br>Format <= 45 AN"
},
"home_phone": {
"$ref": "#/components/schemas/PhoneModel",
"description": "The home phone number provided by the Cardholder."
},
"mobile_phone": {
"$ref": "#/components/schemas/PhoneModel",
"description": "It is advisable to send this field, as it aids in risk assessment, increasing the chances of obtaining a silent authentication."
},
"work_phone": {
"$ref": "#/components/schemas/PhoneModel",
"description": "The work phone number provided by the Cardholder."
},
"name": {
"type": "string",
"description": "Name of the Cardholder.<br>Format <= 45 AN",
"example": "Joaquim"
},
"acct": {
"$ref": "#/components/schemas/AcctModel",
"description": "Account"
},
"bill_addr": {
"$ref": "#/components/schemas/CardholderAddressModel",
"description": "Cardholder Billing Address"
},
"ship_addr": {
"$ref": "#/components/schemas/CardholderAddressModel",
"description": "Cardholder Shipping Address"
},
"cardNumberAndTokenFilled": {
"type": "boolean"
}
}
},
"DsModel": {
"type": "object",
"description": "DS Model",
"properties": {
"reference_number": {
"type": "string",
"description": "EMVCo-assigned unique identifier to track approved DS.<br> Format <= 32 AN"
},
"trans_id": {
"type": "string",
"description": "Universally unique transaction identifier assigned by the DS to identify a single transaction.<br>Format = 36 AN"
},
"url": {
"type": "string",
"description": "URL"
},
"protocol_version": {
"$ref": "#/components/schemas/ProtocolVersionModel",
"description": "Protocol Version"
}
}
},
"ErrorModel": {
"type": "object",
"description": "Error Model",
"properties": {
"code": {
"type": "string",
"description": "Error code.<br>1 - Invalid credentials (merchant_id & merchant_key)<br>2 - Transaction not found<br>3 - Invalid transaction status<br>101 - Unknown message type<br>201 - Empty parameter (see error.detail for further details)<br>202 - message.extension not recognized<br>203 - Invalid parameter (see error.detail for further details)<br>301 - Transaction ID received is not valid for the receiving component.<br>305 - Card not supported by the issuer for 3DS 2.0 authentications.<br>402 - Timeout when communicating with DS<br>404 - Unexpected error<br>405 - DS communication error<br>Format <= 3 N",
"example": 1
},
"component": {
"type": "string",
"description": "Indicates which component identified the error.<br>C = 3DS SDK<br>S = 3DS Server<br>D = DS<br>A = ACS<br>Format = 1 AN",
"example": "S"
},
"description": {
"type": "string",
"description": "Error description.<br>Format <= 2048 AN",
"example": "Error description"
},
"detail": {
"type": "string",
"description": "Error details.<br>Format <= 28 AN",
"example": "Error detail"
}
}
},
"MerchantModel": {
"type": "object",
"description": "Merchant",
"properties": {
"mcc": {
"type": "string",
"description": "DS-specific code describing the Merchant's type of business, product or service. Before sending the request to the DS, the 3DS automatically checks the size of the mcc field entered. If the length is less than 4 characters, the 3DS will add leading zeros until the field reaches a total length of 4 characters.<br>Format = 4 N"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 numeric three-digit country code of the Merchant.<br>Format = 3 N"
},
"name": {
"type": "string",
"description": "Merchant name assigned by the Acquirer or Payment System.<br>Format <= 40 AN"
},
"risk_indicator": {
"$ref": "#/components/schemas/MerchantRiskIndicatorModel",
"description": "Merchant's assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted."
}
}
},
"MerchantRiskIndicatorModel": {
"type": "object",
"description": "Merchant Risk Indicator Model",
"properties": {
"delivery_email_address": {
"type": "string",
"description": "For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).<br>Format < 15 N"
},
"delivery_timeframe": {
"type": "string",
"description": "Indicates the merchandise delivery timeframe.<br>01 = Electronic Delivery<br>02 = Same day shipping<br>03 = Overnight shipping<br>04 = Two-day or more shipping<br>Format = 2 N"
},
"gift_card_amount": {
"type": "string",
"description": "For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).<br>Format < 15 N"
},
"gift_card_count": {
"type": "string",
"description": "For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.<br>Format < 2 N"
},
"gift_card_curr": {
"type": "string",
"description": "For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.<br>Format = 3 N"
},
"pre_order_date": {
"type": "string",
"description": "For a pre-ordered purchase, the expected date that the merchandise will be available in YYYYMMDD format.<br>Format = 8 N"
},
"pre_order_purchase_ind": {
"type": "string",
"description": "Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.<br>01 = Merchandise available<br>02 = Future availability<br>Format = 2 N"
},
"reorder_items_ind": {
"type": "string",
"description": "Indicates whether the cardholder is reordering previously purchased merchandise.<br>01 = First time ordered<br>02 = Reordered<br>Format = 2 N"
},
"ship_indicator": {
"type": "string",
"description": "Indicates shipping method chosen for the transaction.<br>01 = Ship to cardholder's billing address<br>02 = Ship to another verified address on file with merchant<br>03 = Ship to address that is different than the cardholder's billing address<br>04 = “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)<br>05 = Digital goods (includes online services, electronic gift cards and redemption codes)<br>06 = Travel and Event tickets, not shipped<br>07 = Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)<br>Format = 2 N"
}
}
},
"MessageExtensionModel": {
"type": "object",
"description": "Message Extension Model",
"properties": {
"criticality_indicator": {
"type": "string",
"description": "A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.<br>Format <= 5 AN"
},
"data": {
"description": "The data carried in the extension."
},
"id": {
"type": "string",
"description": "A unique identifier for the extension.<br>Format <= 64 AN"
},
"name": {
"type": "string",
"description": "The name of the extension data set as defined by the extension owner.<br>Format <= 64 AN"
}
}
},
"MessageModel": {
"type": "object",
"description": "Message Model",
"properties": {
"category": {
"type": "string",
"description": "Identifies the category of the message for a specific use case.<br>01 - Payment Authentication<br>02 - Non-Payment Authentication<br>80 - Mastercard Identity Check Insights (Data only) Authentication<br>Format = 2 N",
"example": "01"
},
"extension": {
"type": "array",
"description": "Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in a Message Extension.",
"items": {
"$ref": "#/components/schemas/MessageExtensionModel"
}
},
"version": {
"type": "string",
"description": "Version"
}
}
},
"PhoneModel": {
"type": "object",
"description": "Phone Model",
"properties": {
"cc": {
"type": "string",
"description": "Country Code.<br>Format <= 3 N",
"example": 55
},
"subscriber": {
"type": "string",
"description": "Subscriber.<br>Format <= 15 N",
"example": 999999999999999
}
}
},
"ProtocolVersionModel": {
"type": "object",
"description": "Protocol Version Model",
"properties": {
"start": {
"type": "string",
"description": "Start"
},
"end": {
"type": "string",
"description": "End"
}
}
},
"PurchaseModel": {
"type": "object",
"description": "Purchase Model",
"properties": {
"amount": {
"type": "string",
"description": "Purchase amount in minor units of currency with all punctuation removed.<br>Format <= 48 N",
"example": 10000
},
"currency": {
"type": "string",
"description": "ISO 4217 three-digit currency code in which purchase amount is expressed.<br>Format = 3 N",
"example": 986
},
"exponent": {
"type": "string",
"description": "Minor units of currency as specified in the ISO 4217 currency exponent.<br>Format = 1 N",
"example": 2
},
"date": {
"type": "string",
"description": "Date and time of the purchase expressed in UTC in YYYYMMDDHHMMSS format.<br>Format = 12 N",
"example": 20250101000000
},
"instal_data": {
"type": "string",
"description": "Indicates the maximum number of authorizations permitted for instalment payments. Value shall be greater than 1.<br>Format <= 3 N",
"example": 2
}
}
},
"RecurringModel": {
"type": "object",
"description": "Recurring Model",
"properties": {
"expiry": {
"type": "string",
"description": "<br>Format Date after which no further authorizations shall be performed in YYYYMMDD format. Mandatory when three_ds_requestor. authentication_ind = 02 or 03.<br>Format = 8 N"
},
"frequency": {
"type": "string",
"description": "Indicates the minimum number of days between authorizations. Mandatory when three_ds_requestor. authentication_ind = 02 or 03.<br>Format <= 4 N"
}
}
},
"RequestorAuthenticationInfoModel": {
"type": "object",
"description": "Requestor Authentication Info Model",
"properties": {
"data": {
"description": "Data that documents and supports a specific authentication process.<br>Format < 20000 AN"
},
"method": {
"type": "string",
"description": "Mechanism used by the Cardholder to authenticate to the 3DS Requestor.<br>01 = No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest)<br>02 = Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials<br>03 = Login to the cardholder account at the 3DS Requestor system using federated ID<br>04 = Login to the cardholder account at the 3DS Requestor system using issuer credentials<br>05 = Login to the cardholder account at the 3DS Requestor system using third-party authentication<br>06 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator<br>07 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO assurance data signed)<br>08 = SRC Assurance Data<br>Format = 2 N",
"example": "02"
},
"timestamp": {
"type": "string",
"description": "Date and time in UTC of the cardholder authentication in YYYYMMDDHHMM format.<br>Format = 12 N"
}
}
},
"RequestorPriorAuthenticationInfoModel": {
"type": "object",
"properties": {
"data": {
"description": "Data that documents and supports a specific authentication process.<br>Format <= 2048 AN"
},
"method": {
"type": "string",
"description": "Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.<br>01 = Frictionless authentication occurred by ACS<br>02 = Cardholder challenge occurred by ACS<br>03 = AVS verified<br>04 = Other issuer methods<br>format = 2 N",
"example": "01"
},
"timestamp": {
"type": "string",
"description": "Date and time in UTC of the prior cardholder authentication in YYYYMMDDHHMM format.<br>Format = 12 N",
"example": 202509091300
},
"reference": {
"type": "string",
"description": "This data element provides additional information to the ACS to determine the best approach for handing a request.<br>Format <= 36 AN"
}
}
},
"SdkModel": {
"type": "object",
"description": "SDK Model",
"properties": {
"app_id": {
"type": "string",
"description": "Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation.<br>Format = 36 AN"
},
"enc_data": {
"type": "string",
"description": "JWE Object (represented as a string) containing data encrypted by the SDK for the DS to decrypt.<br>Format <= 64000 AN"
},
"ephem_pub_key": {
"description": "Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.<br>Format Object"
},
"reference_number": {
"type": "string",
"description": "ndicates maximum amount of time (in minutes) for all exchanges.<br>Format <= 2 N"
},
"trans_id": {
"type": "string",
"description": "Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.<br>Format = 36 AN"
},
"max_timeout": {
"type": "string",
"description": "Max timeout"
},
"iface": {
"type": "string",
"description": "Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.<br>01 = Native<br>02 = HTML<br>03 = Both<br>Format = 2 N",
"example": "01"
},
"ui_type": {
"type": "array",
"description": "Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.<br>01 = Text<br>02 = Single Select<br>03 = Multi Select<br>04 = OOB<br>05 = HTML Other (valid only for HTML UI)<br>Format = 2 N[]",
"example": "[01, 02]",
"items": {
"type": "string"
}
}
}
},
"Server3DSRootModel": {
"type": "object",
"description": "Server 3DS Root Model",
"properties": {
"three_ds_method_url": {
"type": "string",
"description": "3DS Method URL"
},
"three_ds_server": {
"$ref": "#/components/schemas/ThreeDsServerModel",
"description": "3DS Server Model"
},
"acs": {
"$ref": "#/components/schemas/AcsModel",
"description": "ACS"
},
"brand_id": {
"type": "string",
"description": "Brand ID.<br>Format <= 4 N",
"example": 2
},
"three_ds_comp_ind": {
"type": "string",
"description": "Indicates whether the 3DS Method successfully completed.<br>Y = Successfully completed<br>N = Did not successfully complete<br>U = Unavailable— there was no 3DS Method URL related to the card.<br>Mandatory for device_channel = 02.<br>Format = 1 A",
"example": "Y"
},
"pay_token_ind": {
"type": "string",
"description": "A value of true indicates that the transaction was de-tokenised prior to being received by the ACS.<br>Format <= 5 AN",
"example": true
},
"pay_token_source": {
"type": "string",
"description": "Indicates where the de-tokenisation occurs.<br>01 - 3DS Server<br>02 - DS<br>Format = 2 N",
"example": "02"
},
"notification_url": {
"type": "string",
"description": "Fully qualified URL of the 3DS Requestor to receive the CRes message. Mandatory for device_channel = 02.<br>Format <= 256 AN",
"example": "https://www.requestor.com/notification"
},
"decoupled_notification_url": {
"type": "string",
"description": "Decoupled Notification URL"
},
"trans_type": {
"type": "string",
"description": "Identifies the type of transaction being authenticated.<br>01 = Goods/ Service Purchase<br>03 = Check Acceptance<br>10 = Account Funding<br>11 = Quasi-Cash Transaction<br>28 = Prepaid Activation and Load<br>Format = 2 N",
"example": "03"
},
"eci": {
"type": "string",
"description": "Electronic Commerce Indicator.<br>Format <= 2 N",
"example": "05"
},
"device_channel": {
"type": "string",
"description": "Device channel. 01 = application (APP), 02 = browser (BRW).<br>Format <= 2 N",
"example": "02"
},
"three_ri_ind": {
"type": "string",
"description": "Indicates the type of 3RI request.<br>01 = Recurring transaction<br>02 = Instalment transaction<br>03 = Add card<br>04 = Maintain card information<br>05 = Account verification<br>06 = Split/delayed shipment<br>07 = Top-up<br>08 = Mail Order<br>09 = Telephone Order<br>10 = Whitelist status check<br>11 = Other payment<br>Mandatory for device_channel = 03.<br>Format = 2 N",
"example": "01"
},
"challenge_cancel": {
"type": "string",
"description": "Indicator that informs the ACS and DS that the authentication has been canceled.<br>01 = The cardholder has initiated the cancellation.<br>03 = Transaction expired. Decoupled flow<br>04 = Transaction expired in the ACS<br>05 = Transaction expired in the ACS. First CReq was not received by the ACS.<br>06 = Error in the transaction.<br>08 = Transaction expired in the 3DS SDK<br>09 = Error message in response to the CRes message sent by the ACS.<br>10 = Error message in response to the CReq message sent by the ACS.<br>Format = 2 AN",
"example": "01"
},
"authentication": {
"$ref": "#/components/schemas/AuthenticationModel",
"description": "Authentication"
},
"broad_info": {
"description": "Unstructured information sent between the 3DS Server, the DS and the ACS.<br>Format Object",
"example": "broadInfo"
},
"three_ds_requestor": {
"$ref": "#/components/schemas/ThreeDsRequestorModel",
"description": "3DS Requestor"
},
"acquirer": {
"$ref": "#/components/schemas/AcquirerModel",
"description": "Acquirer"
},
"browser": {
"$ref": "#/components/schemas/BrowserModel",
"description": "These parameters are mandatory if device_channel = 02."
},
"cardholder": {
"$ref": "#/components/schemas/CardholderModel",
"description": "Cardholder"
},
"ds": {
"$ref": "#/components/schemas/DsModel",
"description": "DS"
},
"merchant": {
"$ref": "#/components/schemas/MerchantModel",
"description": "Merchant"
},
"message": {
"$ref": "#/components/schemas/MessageModel",
"description": "Message"
},
"purchase": {
"$ref": "#/components/schemas/PurchaseModel",
"description": "Purchase"
},
"recurring": {
"$ref": "#/components/schemas/RecurringModel",
"description": "Recurring"
},
"transaction": {
"$ref": "#/components/schemas/TransactionModel",
"description": "Transaction"
},
"white_list": {
"$ref": "#/components/schemas/WhiteListModel"
},
"error": {
"$ref": "#/components/schemas/ErrorModel",
"description": "Error"
},
"sdk": {
"$ref": "#/components/schemas/SdkModel",
"description": "SDK. These fields are mandatory for 3DS SDKs (device_channel = 01)."
},
"ds_rid": {
"type": "string",
"description": "ds RID"
},
"ds_info_version": {
"type": "string",
"description": "ds Info Version"
},
"lib_check": {
"type": "string",
"description": "Lib Check"
},
"sdk_check": {
"type": "string",
"description": "SDK Check"
},
"message_version": {
"type": "string",
"description": "Transaction Version (This version must be used on CRes request)<br>Format < 8 AN",
"example": "2.2.0"
},
"sdk_origin": {
"type": "string",
"description": "SDK Origin"
}
}
},
"ThreeDsRequestorModel": {
"type": "object",
"description": "3DS Requestor",
"properties": {
"authentication_ind": {
"type": "string",
"description": "Indicates the type of Authentication request.<br>01 = Payment transaction<br>02 = Recurring transaction<br>03 = Instalment transaction<br>04 = Add card<br>05 = Maintain card<br>06 = Cardholder verification as part of EMV token ID&V<br>Format = 2 N",
"example": "01"
},
"authentication_method_ind ": {
"type": "string",
"description": "Authentication Method Indicator"
},
"decoupled_max_time": {
"type": "string",
"description": "Decoupled max time"
},
"decoupled_request_ind": {
"type": "string",
"description": "Decoupled Request indicator"
},
"authentication_info": {
"$ref": "#/components/schemas/RequestorAuthenticationInfoModel",
"description": "Information about how the 3DS Requestor authenticated the cardholder before or during the transaction."
},
"challenge_ind": {
"type": "string",
"description": "This field signals the merchant's preference for the completion (or not) of the challenge, but unless the parties are aligned, the issuer may not comply with this request. If this field is not sent, it will be interpreted as \"01 = No preference.\"<br>01 = No preference<br>02 = No challenge requested<br>03 = Challenge requested (3DS Requestor preference)<br>04 = Challenge requested (Mandate)<br>05 = No challenge requested (transactional risk analysis is already performed)<br>06 = No challenge requested (Data share only)<br>07 = No challenge requested (strong consumer authentication is already performed)<br>08 = No challenge requested (utilise whitelist exemption if no challenge required)<br>09 = Challenge requested (whitelist prompt requested if challenge required)<br>Format = 2 N",
"example": "01"
},
"id": {
"type": "string",
"description": "DS assigned 3DS Requestor identifier.<br>Format <= 35 AN",
"example": "id"
},
"name": {
"type": "string",
"description": "DS assigned 3DS Requestor name.<br>Format <= 40 AN",
"example": "Requestor Name"
},
"prior_authentication_info": {
"$ref": "#/components/schemas/RequestorPriorAuthenticationInfoModel",
"description": "Information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction."
},
"url": {
"type": "string",
"description": "Fully qualified URL of 3DS Requestor website or customer care site.<br>Format <= 2048 AN",
"example": "https://www.requestor.com"
}
}
},
"ThreeDsServerModel": {
"type": "object",
"description": "3DS Server Model",
"properties": {
"trans_id": {
"type": "string",
"description": "3DS Server ID transaction.<br>Format = 35 AN",
"example": "12341234-1234-1234-1234-123412341234"
},
"status": {
"type": "string",
"description": "3DS Server Status.<br>Format = 3 AN",
"enum": [
"NEW",
"INV",
"ERR",
"EXP",
"ERM",
"AUY",
"AUN",
"AUU",
"AUA",
"AUC",
"AUR",
"AUD"
],
"example": "AUY"
}
}
},
"TransactionModel": {
"type": "object",
"description": "Transaction Model",
"properties": {
"status": {
"type": "string",
"description": "Indicates whether a transaction qualifies as an authenticated transaction or account verification.<br>Y = Authentication Verification Successful.<br>N = Not Authenticated /Account Not Verified; Transaction denied.<br>U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.<br>A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.<br>C = Challenge Required; Additional authentication is required using the CReq/CRes.<br>D = Challenge Required; Decoupled Authentication confirmed.<br>R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.<br>Format = 1 AN",
"example": "N"
},
"status_reason": {
"type": "string",
"description": "Provides information on why the Transaction Status field has the specified value.<br>01 = Card authentication failed<br>02 = Unknown Device<br>03 = Unsupported Device<br>04 = Exceeds authentication frequency limit<br>05 = Expired card<br>06 = Invalid card number<br>07 = Invalid transaction<br>08 = No Card record<br>09 = Security failure<br>10 = Stolen card<br>11 = Suspected fraud<br>12 = Transaction not permitted to cardholder<br>13 = Cardholder not enrolled in service<br>14 = Transaction timed out at the ACS<br>15 = Low confidence<br>16 = Medium confidence<br>17 = High confidence<br>18 = Very High confidence<br>19 = Exceeds ACS maximum challenges<br>20 = Non-Payment transaction not supported<br>21 = 3RI transaction not supported<br>22 = ACS technical issue<br>23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor<br>24 = 3DS Requestor Decoupled Max Expiry Time exceeded<br>25 = Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt<br>26 = Authentication attempted but not performed by the cardholder<br>Format = 2 N",
"example": "01"
}
}
},
"WhiteListModel": {
"type": "object",
"description": "White Liste Model",
"properties": {
"status": {
"type": "string",
"description": "Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.<br>Y = 3DS Requestor is whitelisted by cardholder<br>N = 3DS Requestor is not whitelisted by cardholder<br>E = Not eligible as determined by issuer<br>P = Pending confirmation by cardholder<br>R = Cardholder rejected<br>U = Whitelist status unknown, unavailable, or does not apply<br>Format = 1 AN",
"example": "Y"
},
"status_source ": {
"type": "string",
"description": "This data element will be populated by the system setting Whitelist Status.<br>01 = 3DS Server<br>02 = DS<br>03 = ACS<br>Format = 2 N",
"example": "01"
}
}
}
}
}
}