Skip to main content

Create a payment (3D Challenge)

POST 
/payment/{paymentId}/challenge

Processes a payment request after the Challenge step in the 3D payment flow.

Request​

Path Parameters

    paymentId stringrequired

    Payment ID generated by REST API

    Example: 49900038994789921

Body

required

    idempotencyId string

    Possible values: <= 255 characters

    ID of the API request in the merchant system.

    processingEntityId uuidrequired

    Processing entityId provided by Nuvei.

    cRes stringrequired

    Possible values: non-empty and <= 1024 characters

    The message that holds the challenge response.

Responses​

OK

Schema

    paymentId idType (string)
    transactionId transactionId (string)

    Possible values: <= 20 characters

    Nuvei Digital Payments Gateway Transaction ID

    externalTransactionId ExternalTransactionId (string)

    Possible values: <= 50 characters

    The transaction ID of the transaction in the event that an external service is used.

    amount number

    The transaction amount.

    currency string

    Possible values: >= 3 characters and <= 3 characters

    transactionType transactionType (string)

    Possible values: [Auth, Sale, PreAuth, Settle, Void, Refund, InitAuth3D, Auth3D, Sale3D]

    Determines the transaction type that is sent to the Gateway, when it comes to performing the fiscal transaction. Default is Sale.

    result

    object

    required

    status stringrequired

    Possible values: [approved, authorizedOnly, declined, error, pending, redirect, challenge, fingerprint, authenticated, authenticationNotSupported]

    errors

    object

    code string

    Possible values: <= 11 characters

    reason string

    Possible values: <= 400 characters

    authCode string

    Possible values: <= 128 characters

    The authorization code of the transaction.

    cvv2Code string

    Possible values: <= 1 characters

    The CVV2 (card verification value) response. Values: M = CVV2 Match | N = CVV2 No Match | P = Not Processed | U = Issuer is not certified and/or has not provided Visa the encryption keys | S = CVV2 processor is unavailable.

    avsCode string

    Possible values: <= 1 characters

    The address verification service (AVS) response. Values: A = The street address matches, the ZIP code does not. | W = Postal code matches, the street address does not. | Y = Postal code and the street address match. | X = An exact match of both the 9-digit ZIP code and the street address. | Z = Postal code matches, the street code does not. | U = Issuer is unavailable. | S = AVS not supported by issuer. | R = Retry. | B = Not authorized (declined). | N = Both the street address and postal code do not match.

    partialApproval

    object

    requestedAmount numberrequired
    requestedCurrency stringrequired

    Possible values: >= 3 characters and <= 3 characters

    redirectUrl string

    Possible values: <= 2000 characters

    paymentOption

    object

    card

    object

    cardHolderName string

    Possible values: <= 70 characters

    The card holder name.

    maskedCardNumber string

    Possible values: <= 20 characters

    The masked credit card number.

    bin string

    Possible values: <= 8 characters

    The first six digits from the credit card number for identifying the processing bank. The rest of the number is not displayed.

    last4Digits string

    Possible values: <= 4 characters

    The last four digits of the card number.

    expirationMonth string

    Possible values: <= 2 characters

    The card expiration month.

    expirationYear string

    Possible values: <= 4 characters

    The card expiration year.

    acquirerId string

    Possible values: <= 2 characters

    The ID of the acquirer that processed the transaction.

    cardType string

    Possible values: <= 20 characters

    The type of card used in the transaction. Values: Credit, Debit

    cardBrand string

    Possible values: <= 20 characters

    The card brand used in the transaction. Values: VISA, MASTERCARD, AMEX

    paymentAccountReference string

    Possible values: <= 29 characters

    paymentTokenId uuid

    Payment Token ID

    merchantReference merchantReference (string)

    Possible values: <= 50 characters

    Merchant Reference for a business entity (token, subscription, etc.)

    threeD

    object

    fingerprintUrl string

    The URL to which to post the fingerprintPayload to perform device fingerprinting.

    fingerprintPayload string

    The payload to be posted to the fingerprintUrl to perform the device fingerprinting.

    dsTransId uuid

    The transaction ID of the Directory Server (part of the fingerprintPayload).

    isExemptionRequestInAuthentication boolean
    acsUrl string

    The URL of the Access Control Server to perform the challenge request.

    cReq string

    The payload to be posted to the acsUrl to perform the challenge request.

    acsTransId uuid

    The transaction ID of the Access Control Server (part of the cReq).

    version string

    Possible values: <= 10 characters

    The full version of the 3DS protocol for the transaction.

    serverTransId uuid

    The transaction ID received from the MPI for 3D-Secure v2.

    eci string

    Possible values: <= 2 characters

    The Electronic Commerce Indicator (ECI) that indicates the level of security used in a 3D-Secure program when the cardholder provides payment information to the merchant. Visa values: 5 = The cardholder was successfully authenticated. | 6 = The issuer or cardholder does not participate in a 3D-Secure program. | 7 = Payment authentication was not performed. Mastercard values: 2 = The cardholder was successfully authenticated. | 1 = The issuer or cardholder does not participate in a 3D-Secure program. | 6 = Payment authentication was not performed. | 7 = The cardholder was successfully authenticated for the initial MIT.

    cavv string

    Possible values: <= 40 characters

    Cardholder Authentication Verification Value – cryptographically secure hash of various pieces of information related to the transaction that can be used as a proof for the 3DS authentication.

    whiteListStatus WhiteListStatus (string)

    Possible values: [Y, N, E, P, R, U]

    Indicates if this consumer defined this merchant as whitelist or not. If the consumer defined the merchant, then this is the reason the challenge did not happen. Values: Y = 3DS Requestor is whitelisted by cardholder | N = 3DS Requestor is not whitelisted by cardholder | E = Not eligible as determined by issuer | P = Pending confirmation by cardholder | R = Cardholder rejected | U = Whitelist status unknown, unavailable, or does not apply

    acsChallengeMandate AcsChallengeMandate (string)

    Possible values: [Y, N]

    The 3D Secure 2.0 challenge indication. Values: N = not required | Y = required

    authenticationType AuthenticationType (string)

    Possible values: >= 2 characters and <= 2 characters

    The type of authentication performed during the 3D Secure 2.0 challenge. If the merchant wants to react differently for each authentication type, then they can, per the value returned. Values: 01 = Static | 02 = Dynamic | 03 = OOB | 04 = Decoupled | 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) | 80–99 = Reserved for DS use

    authenticationResult AuthenticationResult (string)

    Possible values: [Y, N, U, A, C, D, R, I]

    Indicates whether a transaction qualifies as an authenticated transaction or account verification. Note: The Final CRes message can contain only a value of Y or N. Values: Y = Authentication Verification Successful | N = Not Authenticated /Account Not Verified; Transaction denied | U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq | A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided | C = Challenge Required; Additional authentication is required using the CReq/CRes | D = Challenge Required; Decoupled Authentication confirmed | R = Authentication/ Account Verification Rejected; Issuer is rejecting | I = Informational only (issuer approved SCA exemption)

    flow Flow (string)

    Possible values: [Challenge, Frictionless, Exemption, NoLiability, Stop]

    The 3D-Secure flow required by the issuer. Values: 1 = Challenge | 2 = Frictionless | 3 = Exemption | 4 = NoLiability | 5 = Stop

    reasonId string

    Possible values: >= 2 characters and <= 2 characters

    reason string
    cardholderInfoText string

    The text provided by the ACS/Issuer to the cardholder during a frictionless transaction that was not authenticated by the ACS/Issuer. For example: “Additional authentication is needed for this transaction. Please contact [Issuer Name] at xxx-xxx-xxxx.” If this parameter is populated, the merchant must display the information to the cardholder.

    merchantId string

    The Merchant ID provided by Nuvei.

    challengePreferenceReason string

    This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge. Press here for more information.

    acquirerDecision string

    The acquirer's request from the merchant to perform a certain flow. Values: ChallengeRequest, ExemptionRequest

    decisionReason string

    The description of the acquirer's decision. Press here to see a table that presents the possible values.

    challengeCancelReason string

    Reason description for a canceled 3D-Secure authorization as received from the issuer.

    challengeCancelReasonId string

    Reason ID for a canceled 3D-Secure authorization as received from the issuer.

    isLiabilityOnIssuer boolean

    Indicates if there is 3D-Secure liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null – No liability shift has occurred.

    alternativePaymentMethod

    object

    name stringrequired

    Possible values: non-empty and <= 50 characters

    data

    object

    property name* string
    merchantReference merchantReference (string)

    Possible values: <= 50 characters

    Merchant Reference for a business entity (token, subscription, etc.)

    paymentTokenId uuid

    Payment Token ID

    eWallet

    object

    provider TokenProvider (string)required

    Possible values: [ApplePay, GooglePay]

    The name of the external token provider Possible values: [ApplePay, GooglePay]

    eciIndicator string

    Possible values: <= 100 characters

    expirationMonth string

    Possible values: <= 2 characters

    The card expiration month.

    expirationYear string

    Possible values: <= 4 characters

    The card expiration year.

    cardHolderName string

    Possible values: <= 70 characters

    The card holder name.

    maskedCardNumber string

    Possible values: <= 20 characters

    The masked credit card number.

    bin string

    Possible values: <= 8 characters

    The first six digits from the credit card number for identifying the processing bank. The rest of the number is not displayed.

    last4Digits string

    Possible values: <= 4 characters

    The last four digits of the card number.

    acquirerId string

    Possible values: <= 2 characters

    The ID of the acquirer that processed the transaction.

    cardType string

    Possible values: <= 20 characters

    The type of card used in the transaction. Values: Credit, Debit

    cardBrand string

    Possible values: <= 20 characters

    The card brand used in the transaction. Values: VISA, MASTERCARD, AMEX

    providerResponseDetails

    object

    code string

    Possible values: <= 100 characters

    reason string

    Possible values: <= 400 characters

    additionalTransactionInfo

    object

    additionalTransactionBankId string
    referenceId string
Loading...