3DS Swagger

YAML

openapi: 3.1.0

info:

title: OpenAPI definition

version: v0

servers:

- url: https://localhost:8901

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: 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'

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: 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

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 JHVGytfdgauygdauiw78264284527852897hagdg Format < 2000 AN

required: false

schema:

type: string

description: >-

Merchant's signature in the Bearer {signature} format. Example:

Bearer JHVGytfdgauygdauiw78264284527852897hagdg Format < 2000 AN

example: >-

Bearer

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M

example: >-

Bearer

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M

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

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:8901",

"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": 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",

"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": 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"

}

],

"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 JHVGytfdgauygdauiw78264284527852897hagdg Format < 2000 AN",

"required": false,

"schema": {

"type": "string",

"description": "Merchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg Format < 2000 AN",

"example": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M"

},

"example": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M"

}

],

"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"

}

],

"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"

}

}

}

}

}

}