Skip to main content

Create Payment (3D Challenge)

POST 
/payments/{payment-id}/challenge

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

Request​

Path Parameters

    payment-id stringrequired

    Payment ID generated by REST API

    Example: 49900038994789921

Header Parameters

    idempotency-key string

    Idempotency Key for the request

    Example: 31f9952c-0058-458b-8244-4ae110ef1556

Body

required

    processingEntityId uuidrequired

    Processing entityId provided by Nuvei.

    cRes stringrequired

    The message that holds the challenge response.

    Possible values: non-empty and <= 1024 characters

Responses​

OK

Schema

    paymentId idType (string)
    Example: 2f00eba7-66ad-4d8b-8d54-b8c9183e664f
    transactionId transactionId (string)

    Nuvei Digital Payments Gateway Transaction ID

    Possible values: <= 20 characters

    externalTransactionId ExternalTransactionId (string)

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

    Possible values: <= 50 characters

    amount number

    The transaction amount.

    currency string

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

    transactionType transactionType (string)

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

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

    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

    Example: 7000.1000
    reason string

    Possible values: <= 400 characters

    Example: Internal Processing Error
    reference string

    Internal reference for troubleshooting

    Possible values: <= 400 characters

    Example: 110.1290
    authCode string

    The authorization code of the transaction.

    Possible values: <= 128 characters

    cvv2Code string

    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.

    Possible values: <= 1 characters

    avsCode string

    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.

    Possible values: <= 1 characters

    partialApproval

    object

    Partial approval is when the deposit completes with a processed amount lower than the requested amount due to a lack of sufficient funds in the consumer payment method.

    requestedAmount numberrequired
    requestedCurrency stringrequired

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

    providerResponseDetails

    object

    code string

    Possible values: <= 100 characters

    reason string

    Possible values: <= 400 characters

    aftDetails

    object

    isAftTransaction boolean
    isAftOverriden boolean
    mcc string

    nameVerification

    object

    result OverallInquiryStatus (string)

    Possible values: [noMatch, partialMatch, match, unverified, notPerformed, notSupported]

    firstName NameInquiryStatus (string)

    Possible values: [noMatch, partialMatch, match, unverified]

    middleName NameInquiryStatus (string)

    Possible values: [noMatch, partialMatch, match, unverified]

    lastName NameInquiryStatus (string)

    Possible values: [noMatch, partialMatch, match, unverified]

    paymentOption

    object

    card

    object

    cardHolderName string

    The cardholder name.

    Possible values: <= 70 characters

    maskedCardNumber string

    The masked credit card number.

    Possible values: <= 20 characters

    bin string

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

    Possible values: <= 8 characters

    last4Digits string

    The last four digits of the card number.

    Possible values: <= 4 characters

    expirationMonth string

    The card expiration month.

    Possible values: <= 2 characters

    expirationYear string

    The card expiration year.

    Possible values: <= 4 characters

    acquirerId string

    The ID of the acquirer that processed the transaction.

    Possible values: <= 2 characters

    cardType string

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

    Possible values: <= 20 characters

    cardBrand string

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

    Possible values: <= 20 characters

    paymentAccountReference string

    Possible values: <= 29 characters

    paymentTokenId tokenId (string)

    Payment Token ID

    merchantReference merchantReference (string)

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

    Possible values: <= 50 characters

    Example: 12391284AF87C7D2

    threeD

    object

    version string

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

    Possible values: <= 10 characters

    Example: 2.1.0
    dsTransId uuid

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

    eci string

    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.

    Possible values: <= 2 characters

    Example: 2
    cavv string

    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.

    Possible values: <= 40 characters

    whiteListStatus WhiteListStatus (string)

    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

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

    acsChallengeMandate AcsChallengeMandate (string)

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

    Possible values: [Y, N]

    authenticationType AuthenticationType (string)

    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

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

    authenticationResult AuthenticationResult (string)

    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)

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

    flow Flow (string)

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

    Possible values: [Challenge, Frictionless, Exemption, NoLiability, 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.

    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

    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.

    networkToken

    object

    provider TokenProvider (string)

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

    Possible values: [ApplePay, GooglePay, Click2Pay, Paze]

    eciIndicator string

    Possible values: <= 100 characters

    expirationMonth string

    The card expiration month.

    Possible values: <= 2 characters

    expirationYear string

    The card expiration year.

    Possible values: <= 4 characters

    cardHolderName string

    The card holder name.

    Possible values: <= 70 characters

    maskedCardNumber string

    The masked credit card number.

    Possible values: <= 20 characters

    bin string

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

    Possible values: <= 8 characters

    last4Digits string

    The last four digits of the card number.

    Possible values: <= 4 characters

    acquirerId string

    The ID of the acquirer that processed the transaction.

    Possible values: <= 2 characters

    cardType string

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

    Possible values: <= 20 characters

    cardBrand string

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

    Possible values: <= 20 characters

    paymentTokenId tokenId (string)

    Payment Token ID

    merchantReference merchantReference (string)

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

    Possible values: <= 50 characters

    Example: 12391284AF87C7D2

    threeD

    object

    version string

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

    Possible values: <= 10 characters

    Example: 2.1.0
    dsTransId uuid

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

    eci string

    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.

    Possible values: <= 2 characters

    Example: 2
    cavv string

    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.

    Possible values: <= 40 characters

    whiteListStatus WhiteListStatus (string)

    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

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

    acsChallengeMandate AcsChallengeMandate (string)

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

    Possible values: [Y, N]

    authenticationType AuthenticationType (string)

    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

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

    authenticationResult AuthenticationResult (string)

    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)

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

    flow Flow (string)

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

    Possible values: [Challenge, Frictionless, Exemption, NoLiability, 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.

    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

    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.

Loading...