Secure 3D

3-D Secure flow: enrol → authenticate → fetch result. Drop in to satisfy SCA on cardholder-present transactions.

Enrollment

POST /v1/3d/enrollment/{init}

Check 3-D Secure enrollment for a card

Verifies whether the supplied card is enrolled in a 3-D Secure programme — the first step of the 3DS flow. The card can be provided as a raw PAN (card_number), as a saved card token (card), or via an init session token (from POST/v1/init, passed as the {init} path parameter). When an init token is used, the card and merchant configuration are taken from the session and the request body may be empty — any fields supplied alongside the init token are ignored. No financial transaction occurs. A positive result is normally followed by POST/v1/3d/authenticate.

Path parameters

Name	Example	Description
`init` string required	`—`	Session token from POST /v1/init. When supplied, the card and merchant configuration are taken from the session; the body may be empty and any fields supplied are ignored.

Request body

Field	Type	Description
`card_number`	string (0,any)	Full PAN. Required when no init token and no card token is supplied. Must pass the Luhn check. Must not be combined with card.
`card`	string (0,any)	Saved card token (from /v1/init). Alternative to card_number.
`merchant`	string (0,any)	Paynetics merchant token. Provide either merchant or three_domain_merchant_id.
`three_domain_merchant_id`	string (0,any)	MPI merchant ID assigned to the merchant. Provided only when the merchant has a dedicated MPI configuration; sent instead of merchant. Provide either three_domain_merchant_id or merchant.

Example request

With an init token, the card and merchant configuration are taken from the session created by POST /v1/init (passed as the {init} path parameter). The request body may be empty; any fields supplied alongside an init token are ignored.

"{}"

The full PAN is supplied directly in the body together with the Paynetics merchant token. No init token is used.

{
    "card_number": "5555555555554444",
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027"
}

A saved card token (from /v1/init) is supplied instead of the raw PAN, together with the merchant token.

{
    "card": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027"
}

The MPI merchant ID is sent instead of the merchant token; used when the merchant has a dedicated MPI configuration.

{
    "card_number": "5555555555554444",
    "three_domain_merchant_id": "PYNXXXXX"
}

Response

Field Type Description

code integer (0,any) Result code. 0 = success.

data object required

Field	Type	Description
`enrolled`	boolean required	true if the card is enrolled in 3-D Secure.

Example response

{
    "code": 0,
    "data": {
        "enrolled": true
    }
}

Authenticate

POST /v1/3d/authenticate/{init}

Authenticate a cardholder via 3-D Secure (v2)

Initiates 3-D Secure authentication for a transaction. When an init session token is supplied, the amount, currency, card data and merchant configuration are taken from the session; otherwise they must be provided in the request body. For 3DS v2, full browser information is required so the issuer can perform risk-based (frictionless) authentication. The response indicates the resolution: proceed without challenge, or redirect the cardholder to the issuer's ACS (bank_redirect_url, or rendered html when html=true) for a challenge. The returned eci, cavv and directory_transaction_id must be passed to the subsequent acquiring operation.

Path parameters

Name	Example	Description
`init` string required	`—`	Session token. When supplied, amount, currency, card data and merchant config are loaded from the session and need not be resent.

Request body

Field	Type	Description
`html`	boolean	If true, returns HTML which has to be printed (rendered challenge page).
`version`	integer (0,any) required	Version of 3DS 2. `2`
`amount`	number (0,any)	Transaction amount in major currency units (e.g. 50.00 = fifty euros). Required when no init token is supplied; otherwise taken from the session.
`currency`	string (0,any)	Transaction currency. Required when no init token is supplied; otherwise taken from the session.
`merchant_name`	string (0,40)	Defaults to the acquirer card-acceptor name if omitted.
`merchant_id`	string (0,any)	MPI merchant ID. Honored only if the merchant's configuration allows it. Provide either merchant_id or merchant.
`merchant`	string (0,any)	Paynetics merchant token. Provide either merchant or merchant_id.
`notification_url`	string (0,256) required	Redirect-back URL after the ACS challenge. Receives the CRes or Error message posted by the ACS via the cardholder browser at the end of the challenge.
`transaction_type`	string (0,any)	Type of transaction being authenticated: 01 Goods/Service Purchase · 03 Check Acceptance · 10 Account Funding · 11 Quasi-Cash · 28 Prepaid Activation & Load. `0103101128`
`authentication_type`	string (0,any)	Type of authentication request: 01 Payment · 02 Recurring · 03 Instalment · 04 Add Card · 05 Maintain Card · 06 Cardholder Verification. `010203040506`
`challenge_indication`	string (0,any)	Whether a challenge is requested: 01 No Preference · 02 No Challenge Requested · 03 Challenge Requested · 04 Challenge Requested (Mandate) · 05 No Challenge Requested (LVP). `0102030405`
`account_type`	string (0,any)	Account type (e.g. for multi-account card products): 01 Not Applicable · 02 Credit · 03 Debit. `010203`
`acquirer_merchant_id`	string (0,any)	Acquirer-side merchant ID.
`email`	string (0,254)	Cardholder email.
`mcc`	string (0,4)	Merchant category code.
`merchant_country_code`	string (0,any)	Merchant country code.
`install`	string (0,any)	Installment indicator.
`exponent`	string (0,any)	Currency exponent.
`transaction_id`	string (0,any)	Merchant transaction reference. Auto-generated (UUID v4) if omitted.
`recurring_frequency`	integer (0,any)	Number of days between authorizations (e.g. 28 for monthly).
`recurring_end_date`	string (0,any)	End date for recurring payment schedule. Date after which no further authorizations should be performed.
`recurring_expiry`	string (0,8)
`purchase_date`	string (0,any)	Purchase timestamp.
`transaction_description`	string (0,any)	Free-text transaction description.
`account_id`	string (0,any)	Cardholder account reference.
`billing_city`	string (0,50)	Billing city.
`billing_country`	string (0,any)	Billing country.
`billing_address_line1`	string (0,50)	Billing address line 1.
`billing_address_line2`	string (0,50)	Billing address line 2.
`billing_address_line3`	string (0,50)	Billing address line 3.
`billing_post_code`	string (0,16)	Billing postal code.
`billing_state`	string (0,3)	Billing state/region.
`browser_accept_header`	string (0,2048) required	Browser Accept header.
`browser_ip`	string (0,45) required	Cardholder browser IP
`browser_java_enabled`	boolean required	Whether the browser has Java enabled.
`browser_language`	string (0,8) required	Browser language.
`browser_color_depth`	string (0,any) required	Browser colour depth (bits). `1481516243248`
`browser_screen_height`	string (0,8) required	Browser screen height (px).
`browser_screen_width`	string (0,any) required	Browser screen width (px).
`browser_tz`	string (0,6) required	Timezone difference in minutes.
`browser_user_agent`	string (0,any) required	Browser user agent.
`card`	string (0,any)	Saved card token. Provide either card or card_number.
`card_number`	string (0,any)	Full PAN. Must pass the Luhn check. Provide either card_number or card.
`cardholder_name`	string (2,45)	Name as printed on the card. Required for PAN payments — i.e. when a card token is not used (card).
`card_expiration_month`	string (0,any)	Card expiry month (01 = January, 12 = December). Required for new card (PAN) payments. `010203040506070809101112`
`card_expiration_year`	string (0,any)	Card expiry year in YY format. Required for PAN payments.
`shipping_city`	string (0,50)	Shipping city.
`shipping_country`	string (0,any)	Shipping country.
`shipping_address_line1`	string (0,50)	Shipping address line 1.
`shipping_address_line2`	string (0,50)	Shipping address line 2.
`shipping_address_line3`	string (0,50)	Shipping address line 3.
`shipping_state`	string (0,3)	Shipping state/region.
`shipping_post_code`	string (0,16)	Shipping postal code.
`shipping_billing_addresses_are_same`	string (0,any)	Whether shipping and billing addresses match. `YN`

Example request

The amount, currency, card and merchant are taken from the session created by POST /v1/init (passed as the {init} path parameter); only the 3DS and browser fields are supplied in the body.

{
    "version": 2,
    "html": true,
    "notification_url": "https://partner.com/3ds/callback",
    "browser_accept_header": "text/html",
    "browser_ip": "127.0.0.1",
    "browser_java_enabled": true,
    "browser_language": "BG",
    "browser_color_depth": "32",
    "browser_screen_height": "1920",
    "browser_screen_width": "1080",
    "browser_tz": "180",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

The full PAN, card details, amount, currency and merchant token are supplied directly in the body. No init token is used.

{
    "version": 2,
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 50,
    "currency": "EUR",
    "card_number": "5555555555554444",
    "cardholder_name": "John Smith",
    "card_expiration_month": "12",
    "card_expiration_year": "27",
    "transaction_type": "01",
    "notification_url": "https://partner.com/3ds/callback",
    "browser_accept_header": "text/html",
    "browser_ip": "127.0.0.1",
    "browser_java_enabled": true,
    "browser_language": "BG",
    "browser_color_depth": "32",
    "browser_screen_height": "1920",
    "browser_screen_width": "1080",
    "browser_tz": "180",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

A challenge is explicitly requested (challenge_indication=03) and the cardholder billing address is supplied to support risk assessment.

{
    "version": 2,
    "html": true,
    "challenge_indication": "03",
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 120,
    "currency": "EUR",
    "card_number": "5555555555554444",
    "cardholder_name": "John Smith",
    "card_expiration_month": "12",
    "card_expiration_year": "27",
    "email": "john.doe@example.com",
    "notification_url": "https://partner.com/3ds/callback",
    "billing_city": "Sofia",
    "billing_country": "BG",
    "billing_address_line1": "Street",
    "billing_post_code": "1000",
    "billing_state": "Sofia",
    "browser_accept_header": "text/html",
    "browser_ip": "127.0.0.1",
    "browser_java_enabled": true,
    "browser_language": "BG",
    "browser_color_depth": "32",
    "browser_screen_height": "1920",
    "browser_screen_width": "1080",
    "browser_tz": "180",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

Recurring transaction (authentication_type=02) with the recurring schedule details.

{
    "version": 2,
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 9.99,
    "currency": "EUR",
    "card_number": "5555555555554444",
    "cardholder_name": "John Smith",
    "card_expiration_month": "12",
    "card_expiration_year": "27",
    "authentication_type": "02",
    "recurring_frequency": 28,
    "recurring_end_date": "2027-12-12",
    "notification_url": "https://partner.com/3ds/callback",
    "browser_accept_header": "text/html",
    "browser_ip": "127.0.0.1",
    "browser_java_enabled": true,
    "browser_language": "BG",
    "browser_color_depth": "32",
    "browser_screen_height": "1920",
    "browser_screen_width": "1080",
    "browser_tz": "180",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

Account-funding transaction (transaction_type=10).

{
    "version": 2,
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 100,
    "currency": "EUR",
    "card_number": "5555555555554444",
    "cardholder_name": "John Smith",
    "card_expiration_month": "12",
    "card_expiration_year": "27",
    "transaction_type": "10",
    "notification_url": "https://partner.com/3ds/callback",
    "browser_accept_header": "text/html",
    "browser_ip": "127.0.0.1",
    "browser_java_enabled": true,
    "browser_language": "BG",
    "browser_color_depth": "32",
    "browser_screen_height": "1920",
    "browser_screen_width": "1080",
    "browser_tz": "180",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

Response

Field Type Description

code integer (0,any) Result code. 0 = success.

data object required

Field	Type	Description
`challenge`	string (0,any)	Challenge payload (when applicable).
`xid`	string (0,any)	Transaction identifier. Submit in the next acquiring operation.
`cavv`	string (0,any)	Cardholder Authentication Verification Value. Submit in the next acquiring operation.
`eci`	string (0,any)	Electronic Commerce Indicator. Submit in the next acquiring operation.
`resolution`	string (0,any)	`proceedrejectproceed_sslproceed_3dsproceed_3ds_attempted`
`status`	string (0,any)	`unable-to-authenticatefailedsuccessfulattempted`
`status_reason`	string (0,any)	Reason detail for the status.
`version`	string (0,any)	3DS protocol version used.
`bank_redirect_url`	string (0,any)	ACS challenge URL — redirect the cardholder here.
`acs_transaction_id`	string (0,any)	ACS transaction ID.
`mpi_transaction_id`	string (0,any)	MPI transaction ID.
`directory_transaction_id`	string (0,any)	Directory Server transaction ID (dsTransID).
`type`	string (0,any)
`method`	string (0,any)
`html`	string (0,any)	Rendered challenge HTML (returned when html=true).

Example response

The issuer authenticated the cardholder without a challenge. Pass eci, cavv and xid to the subsequent acquiring operation.

{
    "code": 0,
    "data": {
        "resolution": "proceed_3ds",
        "status": "successful",
        "version": "2",
        "eci": "05",
        "cavv": "jJ81HADVRtXfCBATEp01CJUAAAA=",
        "xid": "MDAwMDAwMDAwMDAwMDAwMTIzNDU="
    }
}

The issuer requires a challenge — redirect the cardholder to bank_redirect_url (or render the returned html when html=true).

{
    "code": 0,
    "data": {
        "resolution": "proceed_3ds",
        "status": "attempted",
        "version": "2",
        "bank_redirect_url": "https://acs.issuer.com/challenge?id=abc123",
        "acs_transaction_id": "f8c1...",
        "directory_transaction_id": "a1b2..."
    }
}

Result

POST /v1/3d/result/{version}/{init}

Submit the 3-D Secure challenge result

Completes a challenged 3-D Secure authentication by submitting the result returned from the issuer's ACS — the raw CRes for 3DS v2, Base64-encoded in the response field. The version path parameter selects the protocol. Returns the final authentication outcome, including the eci, cavv and directory_transaction_id to be forwarded to the acquiring operation.

Path parameters

Name	Example	Description
`version` integer required	`—`	3-D Secure protocol version. `2`
`init` string required	`—`	Session token.

Request body

Field	Type	Description
`response`	string (0,any) required	Raw response from the 3DS result — CRes for v2.

Example request

3DS v2 (CRes)

The Base64-encoded CRes returned by the issuer's ACS is submitted in the response field.

{
    "response": "ZWFzdXJlLg=="
}

Response

Field Type Description

code integer (0,any) Result code. 0 = success.

data object required

Field	Type	Description
`challenge`	string (0,any)	Challenge payload (when applicable).
`xid`	string (0,any)	Transaction identifier. Submit in the next acquiring operation.
`cavv`	string (0,any)	Cardholder Authentication Verification Value. Submit in the next acquiring operation.
`eci`	string (0,any)	Electronic Commerce Indicator. Submit in the next acquiring operation.
`resolution`	string (0,any)	`proceedrejectproceed_sslproceed_3dsproceed_3ds_attempted`
`status`	string (0,any)	`unable-to-authenticatefailedsuccessfulattempted`
`status_reason`	string (0,any)	Reason detail for the status.
`version`	string (0,any)	3DS protocol version used.
`bank_redirect_url`	string (0,any)	ACS challenge URL — redirect the cardholder here.
`acs_transaction_id`	string (0,any)	ACS transaction ID.
`mpi_transaction_id`	string (0,any)	MPI transaction ID.
`directory_transaction_id`	string (0,any)	Directory Server transaction ID (dsTransID).
`type`	string (0,any)
`method`	string (0,any)
`html`	string (0,any)	Rendered challenge HTML (returned when html=true).

Example response

{
    "code": 0,
    "data": {
        "resolution": "proceed_3ds",
        "status": "successful",
        "version": "2",
        "eci": "05",
        "cavv": "jJ81HADVRtXfCBATEp01CJUAAAA=",
        "xid": "MDAwMDAwMDAwMDAwMDAwMTIzNDU="
    }
}

{
    "code": 0,
    "data": {
        "resolution": "proceed_3ds",
        "status": "attempted",
        "version": "2",
        "bank_redirect_url": "https://acs.issuer.com/challenge?id=abc123",
        "acs_transaction_id": "f8c1...",
        "directory_transaction_id": "a1b2..."
    }
}

Base URL · Production

GET https://acquiring.paynetics.net

Base URL · Sandbox

GET https://secure.payoo.cloud

On this page

Enrollment Authenticate Result