Skip to main content

Create 3DS Authentication

POST 
/v1/payin/three-ds/authentications
<b>Tag</b>: api-payments-gateway-post-payin

<b>3DS Authentication Flow:</b>
1. <b>Initial Request:</b> Send card and transaction details to this endpoint.
2. <b>Status Response:</b> You'll receive one of these authentication status:
   - PENDING: Authentication is being processed.
   - WAITING_AUTHENTICATION: Internal processing, no user action needed.
   - WAITING_CHALLENGE: User needs to complete additional authentication.
   - ACCEPTED: Authentication successful.
   - REJECTED: Authentication rejected.
   - FAILED: Process error.

<b>Authentication Scenarios:</b>
- <b>Frictionless:</b> When status is ACCEPTED, don't require further user action. Proceed with payment (POST: v1/payments).
- <b>Challenge:</b> When status is WAITING_CHALLENGE, redirect user to the provided challenge URL for additional verification.
  - You need to send a POST request with the Challenge URL, Authentication ID, and iframe data. The response will return the HTML content that should be rendered inside an iframe.

Request​

Header Parameters

    x-wallet-uuid string

    Sender Wallet UUID (if empty, your default Wallet UUID will be settled)

    x-transaction-uuid stringrequired

    The transaction ID is a UUID (v7) used to uniquely identify the object that will be created. All objects must have an identifier.

    nonce stringrequired

    The nonce ID is a UUID (v4) used to uniquely identify the request. All requests must have an identifier.

    x-lang string

    Possible values: [pt-BR, en-US]

    Indicates the preferred language. Defaults to Brazilian Portuguese if unspecified.

    x-product-uuid string

    The product ID is a UUID (v4) used to identify the Z.ro product configuration.

    x-product-target-user-uuid string

    The product target user ID is a UUID (v4) used to identify what user account this request must be executed. Require: x-product-uuid.

Body

required
    country stringrequired

    Country code for the payment.

    payment_method stringrequired

    Possible values: [DEBIT_CARD]

    Payment method used in the transaction.

    amount_total numberrequired

    Payment amount in cents. Min value is 1000 cents.

    currency_tag stringrequired

    Possible values: [BRL, USD]

    Payment currency tag.

    third_part_name stringrequired

    Third Part name. It must contain at least first name and last name.

    third_part_email stringrequired

    Third Part email address.

    third_part_phone stringrequired

    Third Part phone number.

    third_part_address_zip_code stringrequired

    User Address Zip Code.

    third_part_address_street stringrequired

    User Address Street.

    third_part_address_number stringrequired

    User Address number.

    third_part_address_city stringrequired

    User Address City.

    third_part_address_federative_unit stringrequired

    User Address Federative Unit.

    third_part_address_country stringrequired

    User Address Country.

    third_part_address_neighborhood string

    User Address Neighborhood.

    third_part_address_complement stringrequired

    User Address Complement.

    third_part_navigator_language stringrequired

    Browser language.

    third_part_navigator_java_enabled booleanrequired

    Java enabled status.

    third_part_navigator_color_depth numberrequired

    Color depth in bits.

    third_part_navigator_screen_height numberrequired

    Screen height in pixels.

    third_part_navigator_screen_width numberrequired

    Screen width in pixels.

    third_part_navigator_time_difference numberrequired

    Time difference in minutes.

    third_part_navigator_user_agent stringrequired

    User agent string.

    third_part_navigator_http_accept_content stringrequired

    HTTP Accept content.

    merchant_url stringrequired

    Merchant URL.

    merchant_challenge_window_size stringrequired

    Possible values: [SMALL, MEDIUM, LARGE, XLARGE, FULL_PAGE]

    Merchant Challenge Window Size.

    merchant_transaction_mode stringrequired

    Possible values: [ECOMMERCE, MOBILE, TABLET]

    Merchant Transaction Mode.

    device_channel stringrequired

    Possible values: [SDK, BROWSER]

    Device channel.

    payment_card objectrequired
    card_number stringrequired

    Card number.

    card_cvv stringrequired

    Card CVV.

    card_name stringrequired

    Card Holder Name.

    card_expiry_date stringrequired

    Card Expiry Date in MM-YYYY format.

Responses​

3DS Authentication created successfully.

Schema
    id stringrequired

    Three DS authentication ID.

    status stringrequired

    Possible values: [PENDING, WAITING_AUTHENTICATION, WAITING_CHALLENGE, ACCEPTED, REJECTED, FAILED, ERROR]

    Three DS authentication status.

    created_at date-timerequired

    Three DS authentication creation date.

    updated_at date-timerequired

    Three DS authentication last update date.

Loading...