Skip to main content

paymentHandleRequest

oneOf
card object

Card details to be used for the transaction

cardNumstringrequired

This is the card number used for the request.

Possible values: >= 8 characters and <= 20 characters

Example: 4111111111111111
cardExpiry object

This is the card's expiry date.

monthnumberrequired

This is the card expiry month.

Possible values: <= 12

Example: 12
yearnumberrequired

This is the card expiry year.

Possible values: <= 9999

Example: 2022
cvvstring

This is the 3- or 4-digit security code that appears on the card following the card number.

Possible values: >= 3 characters and <= 4 characters, Value must match regular expression ^([0-9]{3,4})$

holderNamestring

This is the name of the card holder.

Possible values: <= 50 characters

Example: Suresh's card
cardTypestring

This is type of card used for the request.

  • AM – American Express

  • DI – Discover

  • JC – JCB

  • MC – Mastercard

  • MD – Maestro

  • SO – Solo

  • VI – Visa

  • VD – Visa Debit

  • VE – Visa Electron

Possible values: [AM, DI, JC, MC, MD, SO, VI, VD, VE]

lastDigitsstring

These are the last four digits of the card used for the request.

nickNamestring

This is the nickname the merchant has for the card holder.

cardBinstring

These are the first 6 digits of the card Bank Identification Number (BIN), for example: the first 6 digits of the card number.

Possible values: <= 6 characters

Example: 411111
merchantRefNumstringrequired

This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.

Possible values: <= 255 characters

Example: merchantRefNum-101
transactionTypestringrequired

This specifies the transaction type for which the Payment Handle is created.

  • PAYMENT - Payment Handle is created to continue the Payment.

  • STANDALONE_CREDIT - Payment Handle is created to continue the Standalone Credit.

Possible values: [PAYMENT, STANDALONE_CREDIT]

accountIdstring

If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.

Possible values: <= 10 characters

Example: 9876543210
paymentTypestringrequired

This is the payment type associated with the Payment Handle used for this request.

Possible values: [CARD, RAPID_TRANSFER, BANK_TRANSFER, ACH]

amountnumberrequired

This is the amount of the request, in minor units.

Note: This field is mandatory if transactionType is included.

The amount specified in the Payment Handle request must match the amount specified in the Payments API request the paymentHandleToken is used for.

Possible values: <= 99999999999

Example: 500
currencyCodestringrequired

This is the currency of the merchant account, e.g., USD or CAD. See Currency Codes.

Note: This field is mandatory if transactionType is included. The currencyCode specified in the Payment Handle request must match the currencyCode specified in the Payments API request the paymentHandleToken is used for.

Possible values: <= 3 characters

Example: USD
paymentHandleTokenFromstring

This is an existing Customer Payment Handle, from which the payment instrument and profile details are retrieved. If this parameter is included you can omit the billingDetails object.

Possible values: <= 36 characters

Example: SCyGZDlUuZ9zxjyd
profile object

This is customer's profile details.

idstring

The customer's profile id in the system. If this is present rest all other fields are not required.

statusstring

The status of customer in the system, returned in the response.

merchantCustomerIdstring

This is the reference number for the customer created by the merchant and submitted as part of the request. It must be unique for each customer.

Note: This value is mandatory when fundingTransaction is used.

Possible values: <= 10 characters

localestringrequired

This indicates the customer's locale preference.

Note: Optional for GiroPay, Vippreferred-Direct-Registration. Not required for Paysafe Card Payouts.

Possible values: [en_US, fr_CA, en_GB, en_CA]

firstNamestringrequired

This is the customer’s first name.

Possible values: <= 80 characters

Example: Venkata Suresh
lastNamestringrequired

This is the customer’s last name.

Possible values: <= 80 characters

Example: Chagalamarri
emailstringrequired

This is the customer's email address.

Possible values: <= 255 characters

Example: paysafe@gmail.com
phonestring

This is the customer's phone number.

Note: Optional for GiroPay. Not required for Paysafe Card Payouts.

Possible values: <= 40 characters

Example: 1234567891
dateOfBirth object

This is the recipient's date of birth.

daynumberrequired

This is the day of birth.

Possible values: <= 31

Example: 6
monthnumberrequired

This is the month of birth.

Possible values: <= 12

Example: 5
yearnumberrequired

This is the year of birth.

Possible values: >= 1900

Example: 1998
mobilestring

Customer's mobile number.

Possible values: <= 40 characters

Example: 9846573804
genderstring

This field indicates the Customer's gender.

M - Male

F - Female

Possible values: [M, F]

Example: M
nationalitystring

This field indicates the Customer's nationality.

Possible values: <= 30 characters

Example: Indian
identityDocuments object[]
  • Array [
    • identityDocuments object[]required

    This is array of 2 JSON objects.

    • 1st object contains SSN
    • 2nd object contains Identity document details.
  • Array [
    • anyOf
  • ]
  • ]
    • billingDetails object

    Customer's billing details.

    Note: For single-use Payment Handles, this address information will be ignored if the paymentHandleTokenFrom parameter is included in the Payment Handle creation request and there is already address information associated with that customer.

    idstring

    This is the ID of the billing address, returned in the response.

    Possible values: <= 36 characters

    statusstring

    This is the status of the address.

    nickNamestring

    This is the nickname the merchant has for the billing address.

    Possible values: <= 50 characters

    Example: Home
    streetstringrequired

    This is the first line of the customer's street address.

    Possible values: <= 50 characters

    Example: Street
    street1string

    This is the first line of the street address.

    Note: Mandatory for VIPPreferred

    Possible values: <= 50 characters

    Example: street1
    street2string

    This is the second line of the street address, if required (e.g., apartment number).

    Possible values: <= 50 characters

    Example: street2
    citystringrequired

    This is the city where the address is located.

    Possible values: <= 40 characters

    Example: Toronto
    statestring

    This is the state/province/region in which the customer lives.

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

    Example: ON
    countrystringrequired

    This is the country where the address is located. See Country Codes.

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

    Example: CA
    zipstringrequired

    This is the zip, postal, or post code of the customer's address.

    Possible values: <= 10 characters

    Example: M5H 2N2
    phonestring

    This is the customer's telephone number.

    Possible values: <= 40 characters

    Example: 8765846321
    splitpay object

    This object should be used only for Splitpay transactions only, an array containing the linked accounts and the amount shared with each. You must include either amount or percent. However, you cannot include both values.

    linkedAccountstringrequired

    This is the ID of the linked account. This account must already be linked to the merchant account.

    Example: 123124124
    amountnumber

    This is the amount to transfer to the linked account in minor currency units. The total amount to all linked accounts cannot exceed the transaction total.

    Example: 505
    percentnumber

    This is the percentage of the total transaction amount to transfer to that account. The total percentage to all linked accounts cannot exceed 100%.

    Example: 5
    merchantDescriptor object

    This is the merchant descriptor that will be displayed on the customer's card or bank statement.

    dynamicDescriptorstringrequired

    This is a merchant descriptor that will be displayed on a customer’s card statement.

    Possible values: <= 20 characters

    Example: OnlineStore
    phonestring

    This is the merchant’s phone number, which is appended to the merchant descriptor on a customer’s card statement.

    Possible values: <= 13 characters

    Example: 12345678
    returnLinks object

    The URL endpoints to redirect the customer to after a redirection to an alternative payment or 3D Secure site. You can customize the return URL based on the transaction status.

    relstringrequired

    This is the link type that allows different endpoints to be targeted depending on the end state of the transaction.

    • on_completed - Paysafe will return to this merchant url post successful payment.

    • on_failed - Paysafe will return to this merchant url post if payment is failed.

    • on_cancelled - Paysafe will return to this merchant url post if payment is cancelled.

    • default - The default return URL that will be used if specific status return URL is not defined.

    Possible values: [default, on_completed, on_failed, on_cancelled]

    hrefstringrequired

    This is the URI of the resource.

    Example: https://US_commerce_site/payment/return/success
    methodstringrequired

    This is the HTTP method.

    Example: GET
    customerIpstring

    This is the customer's IP address.

    Possible values: <= 39 characters

    Example: 111.111.111.111
    transactionIntent object

    The transactionIntent property is used to identify the intent of the authorization requests. The value of the transactionIntent shows if the transaction is crypto or quasi-cash related one.

    • It is an optional enum field applicable for every MCC.

    • It is required only if the use cases explained below are applicable for the merchants or the default behavior is not acceptable for them.

    • The merchant needs to add in the request transactionIntent property value as shown in the example below.

    Use cases and applicable valid enum transactionIntent options:

    |Use case |MCC |Valid transactionIntent value | |--- |--- |--- | |The consumer is acquiring cryptocurrency in a transaction. |6012, 6051 |CRYPTO_ON_RAMP | |The consumer is loading a cryptocurrency wallet or exchange account with fiat. *Applicable only in combination with valid fundingTransaction object. |6012, 6051 |WALLET_CRYPTO_ON_RAMP | |The consumer is acquiring quasi-cash in a transaction. *Quasi cash transactions represent the purchase of foreign currencies or items (including, but not limited to, casino chips, money orders, lottery tickets and travelers cheques) which may be convertible to cash.|4829, 6012, 6051|QUASI_CASH | |For purchases of goods or services that leverage a live conversion of fiat into non - fiat currency. |ANY |BUY_WITH_CRYPTO |

    Default transactionIntent definition by Paysafe

    • All authorizations processed by MCC 6051 will be classified as crypto related with transactionIntent "CRYPTO_ON_RAMP" or "WALLET_CRYPTO_ON_RAMP" (when funding a wallet), except their account is not configured by Paysafe for quasi-cash transactions.

    • All authorizations processed by MCC 6051 will be classified as crypto related with transactionIntent "CRYPTO_ON_RAMP" or "WALLET_CRYPTO_ON_RAMP" (when funding a wallet), except their account is not configured by Paysafe for quasi-cash transactions.All authorizations processed by MCC 6051 or 4829 with quasi-cash configuration turned on will be classified as quasi-cash related with transactionIntent "QUASI_CASH" .

    Expected errors related to invalid transactioIntent values:

    • If you send transactionIntent type in the authorization request with value not applicable for your MCC, the transaction will be declined with error 3072 - "Your request has been declined because the requested transactionIntent value is not applicable for your merchant category code (MCC)".

    • If you send transactionIntent type WALLET_CRYPTO_ON_RAMP in the authorization request, but you didn't classify the transaction as "funding" one with the respective valid fundingTransaction object, the transaction will be declined with error 3071 - Your request has been declined because of mismatch between the requested transactionIntent and fundingTransaction type.

    Note: More about the usage of transactionIntent in standalone credit request can be found here DRAFT - Transaction intent field in standalone credits - Technical documentation for merchant's comms (dev center address to be added).

    transactionIntentstring

    Possible values: [CRYPTO_ON_RAMP, WALLET_CRYPTO_ON_RAMP, QUASI_CASH, BUY_WITH_CRYPTO]

    singleUseCustomerTokenstring

    This is the single use customer token of the profile on which customer operation (ADD/EDIT/DELETE) needs to be done.

    Note: Mandatory, if customerOperation is EDIT or DELETE.

    Possible values: <= 36 characters

    threeDs object

    Denotes the status of threeDs object. If true and is configured in the backend for the respective accountId, it is mandatory to pass this parameters. If false, parameters need not be passed.

    iduuid

    This is the unique ID returned in the response.

    Possible values: <= 36 characters

    deviceFingerprintingIduuid

    This is the UUID used with device fingerprinting.

    Possible values: <= 36 characters

    merchantRefNumstring

    This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.

    Possible values: <= 255 characters

    Example: fc5b62df1202e491475d
    processboolean

    This is an indicator representing whether to call authenticate end point or not.

    merchantUrlstring

    This is the fully qualified URL of the merchant's commercial or customer care website.

    Possible values: <= 2048 characters

    Example: https://api.qa.paysafe.com/checkout/v2/demo-store/index.html
    deviceChannelstring

    This is the type of channel interface used to initiate the transaction.

    Possible values: [BROWSER, APP, 3RI]

    Example: BROWSER
    requestorChallengePreferencestring

    This indicates whether a challenge is requested for this transaction.

    Possible values: [NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED, CHALLENGE_MANDATED]

    messageCategorystring

    This is the category of the message for a specific use case.

    Possible values: [PAYMENT, NON_PAYMENT]

    Example: PAYMENT
    transactionIntentstring

    This identifies the type of transaction being authenticated.

    Possible values: [GOODS_OR_SERVICE_PURCHASE, CHECK_ACCEPTANCE, ACCOUNT_FUNDING, QUASI_CASH_TRANSACTION, PREPAID_ACTIVATION]

    authenticationPurposestring

    This is the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request.

    Possible values: [PAYMENT_TRANSACTION, RECURRING_TRANSACTION, INSTALMENT_TRANSACTION, ADD_CARD, MAINTAIN_CARD, EMV_TOKEN_VERIFICATION]

    Example: PAYMENT_TRANSACTION
    billingCycle object

    Details of the billing cycle information for recurring payments.

    Note: This object is required if authenticationPurpose = INSTALMENT_TRANSACTION or RECURRING_TRANSACTION.

    endDatedate

    This is the date after which no further authorizations will be performed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    frequencynumber

    This is the minimum number of days between authorizations.

    orderItemDetails object
    preOrderItemAvailabilityDatedate

    For a pre-ordered purchase, this is the date that the merchandise is expected to be available. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    preOrderPurchaseIndicatorstring

    This indicates whether the cardholder is placing an order for available merchandise or merchandise with a future availability or release date.

    Possible values: [MERCHANDISE_AVAILABLE, FUTURE_AVAILABILITY]

    reorderItemsIndicatorstring

    This indicates whether the cardholder is reordering merchandise.

    Possible values: [FIRST_TIME_ORDER, REORDER]

    shippingIndicatorstring

    This is the shipping method for the transaction.

    Possible values: [SHIP_TO_BILLING_ADDRESS, SHIP_TO_VERIFIED_ADDRESS, SHIP_TO_DIFFERENT_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TRAVEL_AND_EVENT_TICKETS, OTHER]

    purchasedGiftCardDetails object
    amountnumber

    This is the amount of the gift card, in minor units.

    Possible values: <= 99999999999

    Example: 1234
    countnumber

    This is the total count of individual prepaid or gift cards or codes purchased.

    Possible values: <= 99

    Example: 2
    currencystring

    This is the currency of the gift card, e.g., USD or CAD. See Currency Codes

    Example: USD
    userAccountDetails object

    These are the user account details from the merchant website.

    addCardAttemptsForLastDaynumber

    This is the number of Add Card attempts in the last 24 hours.

    changedDatedate

    This is the date that the cardholder’s account with the 3DS Requestor was last changed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    changedRangestring

    This is the length of time between the most recent change to the cardholder’s account information and the API call of the current transaction.

    Possible values: [DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    createdDatedate

    This is the date when the cardholder opened the account with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    createdRangestring

    This is the length of time between the cardholder opening the account with the 3DS Requestor and the API call of the current transaction.

    Possible values: [NO_ACCOUNT, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    passwordChangedDatedate

    This is the date when the cardholder’s account was reset or the password was changed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    passwordChangedRangestring

    This is the length of time between the most recent password change or cardholder account reset and the API call of the current transaction.

    Possible values: [NO_CHANGE, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    suspiciousAccountActivityboolean

    This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.

    totalPurchasesSixMonthCountnumber

    This is the total number of purchases from this cardholder account in the previous six months.

    Possible values: <= 9999

    transactionCountForPreviousDaynumber

    This is the number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

    Possible values: <= 999

    transactionCountForPreviousYearnumber

    This is the number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

    Possible values: <= 999

    shippingDetailsUsage object

    This is the shipping usage information.

    cardHolderNameMatchboolean

    This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.

    initialUsageDatedate

    This is the date when the shipping address for this transaction was first used with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    initialUsageRangestring

    Possible values: [CURRENT_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    userLogin object

    This is the cardholder login information.

    authenticationMethodstring

    This is the mechanism used by the cardholder to authenticate to the 3DS Requestor.

    Possible values: [NO_LOGIN, INTERNAL_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARY_AUTHENTICATION, FIDO_AUTHENTICATOR]

    datastring

    This field is reserved for future iterations of 3D Secure 2.

    Possible values: <= 2048 characters

    Example: Some up to 2048 bytes undefined data
    timedate-time

    This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

    paymentAccountDetails object

    These are the details of the current payment account of the cardholder.

    createdRangestring

    This indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.

    Possible values: [NO_ACCOUNT, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    createdDatedate

    This is the date that the cardholder opened the account with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.e.

    priorThreeDSAuthentication object

    This is the previous authentication information used with current merchant, cardholder, and card.

    idstring

    This is the previous authentication ID for the cardholder.

    Note: For recurring payments, this is the authenticationId of the first authentication.

    Possible values: <= 36 characters

    Example: 123e4567-e89b-12d3-a456-426655440000
    datastring

    This field is reserved for future iterations of 3D Secure 2.

    Example: Some up to 2048 bytes undefined data
    methodstring

    This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor.

    Possible values: [FRICTIONLESS_AUTHENTICATION, ACS_CHALLENGE, AVS_VERIFIED, OTHER_ISSUER_METHOD]

    timedate-time

    This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

    travelDetails object

    These are the Amex-specific travel details.

    isAirTravelboolean

    This indicates whether the transaction is an air travel related purchase, e.g., a ticket purchase

    Default value: false
    airlineCarrierstring

    This is the selected airline carrier.

    Possible values: <= 256 characters

    departureDatedate

    This is the date of departure in the time zone of the departure location. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    destinationstring

    This is the airport code of the destination airport.

    Possible values: <= 5 characters

    originstring

    This is the airport code of the originating airport.

    Possible values: <= 5 characters

    passengerFirstNamestring

    This is the first name of the cardholder from the billing details.

    Possible values: <= 99 characters

    passengerLastNamestring

    This is the last name of the cardholder from the billing details.

    Possible values: <= 99 characters

    priorThreeDSAuthentication object

    This is the previous authentication information used with current merchant, cardholder, and card.

    idstring

    This is the previous authentication ID for the cardholder.

    Note: For recurring payments, this is the authenticationId of the first authentication.

    Possible values: <= 36 characters

    Example: 123e4567-e89b-12d3-a456-426655440000
    datastring

    This field is reserved for future iterations of 3D Secure 2.

    Example: Some up to 2048 bytes undefined data
    methodstring

    This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor.

    Possible values: [FRICTIONLESS_AUTHENTICATION, ACS_CHALLENGE, AVS_VERIFIED, OTHER_ISSUER_METHOD]

    timedate-time

    This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

    shippingDetailsUsage object

    This is the shipping usage information.

    cardHolderNameMatchboolean

    This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.

    initialUsageDatedate

    This is the date when the shipping address for this transaction was first used with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    initialUsageRangestring

    Possible values: [CURRENT_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    suspiciousAccountActivityboolean

    This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.

    totalPurchasesSixMonthCountnumber

    Transaction count for last 6 months.

    Possible values: <= 9999

    transactionCountForPreviousDaynumber

    Transaction count for last 24 hours

    Possible values: <= 999

    transactionCountForPreviousYearnumber

    Transaction count for last 1 year.

    Possible values: <= 999

    travelDetails object

    These are the Amex-specific travel details.

    isAirTravelboolean

    This indicates whether the transaction is an air travel related purchase, e.g., a ticket purchase

    Default value: false
    airlineCarrierstring

    This is the selected airline carrier.

    Possible values: <= 256 characters

    departureDatedate

    This is the date of departure in the time zone of the departure location. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

    destinationstring

    This is the airport code of the destination airport.

    Possible values: <= 5 characters

    originstring

    This is the airport code of the originating airport.

    Possible values: <= 5 characters

    passengerFirstNamestring

    This is the first name of the cardholder from the billing details.

    Possible values: <= 99 characters

    passengerLastNamestring

    This is the last name of the cardholder from the billing details.

    Possible values: <= 99 characters

    userLogin object

    This is the cardholder login information.

    authenticationMethodstring

    This is the mechanism used by the cardholder to authenticate to the 3DS Requestor.

    Possible values: [NO_LOGIN, INTERNAL_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARY_AUTHENTICATION, FIDO_AUTHENTICATOR]

    datastring

    This field is reserved for future iterations of 3D Secure 2.

    Possible values: <= 2048 characters

    Example: Some up to 2048 bytes undefined data
    timedate-time

    This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

    browserDetails object

    These are the browser details.

    Note: This object is not required if the Paysafe SDK is used for device fingerprinting.

    acceptHeaderstringrequired

    This is the exact content of the HTTP accept header as sent to the 3DS Requestor from the cardholder’s browser.

    Possible values: <= 2048 characters

    colorDepthBitsstringrequired

    This is the bit depth of the color palette for displaying images, in bits per pixel.

    Possible values: [1, 4, 5, 15, 16, 24, 32, 48]

    customerIpstringrequired

    This is the customer's IP address. Valid Ip address format are IPv4 / IPv6.

    javaEnabledbooleanrequired

    This indicates whether the cardholder's browser is able to execute Java.

    javascriptEnabledbooleanrequired

    This indicates whether the cardholder's browser is able to execute JavaScript.

    languagestringrequired

    This is the language in the browser.

    Possible values: <= 8 characters

    screenHeightnumberrequired

    This is the total height of the cardholder’s screen in pixels.

    Possible values: <= 999999

    screenWidthnumberrequired

    This is the total width of the cardholder’s screen in pixels.

    Possible values: <= 999999

    timezoneOffsetnumberrequired

    This is the time-zone offset in minutes between UTC and the local time of the cardholder's browser.

    Possible values: <= 99999

    userAgentstringrequired

    This is the User-Agent header from the customer's browser. For example:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36

    Possible values: <= 256 characters

    cavvstring

    This is the Cardholder Authentication Verification Value, indicating that the transaction has been authenticated.

    ecinumber

    This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated.

    statusstring

    This is the status of the authentication request.

    • COMPLETED – The transaction has been completed.

    • PENDING – The transaction has not been completed yet.

    • FAILED – The authentication request failed.

    Possible values: [COMPLETED, PENDING, FAILED]

    threeDResultstring

    ThreeDResult possible values are:

    • Y - AUTHENTICATION_SUCCESSFUL
    • A - AUTHENTICATION_ATTEMPTED
    • N - AUTHENTICATION_FAILED
    • U - AUTHENTICATION_UNAVAILABLE
    • E - AUTHENTICATION_ERROR
    • C - CHALLENGE_REQUIRED
    • R - REJECTED_TRANSACTION

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

    txnTimestring

    This is the date and time the request was processed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

    directoryServerTransactionIduuid

    This is the directory server transaction ID required for Mastercard.

    Note: This exists only for 3D Secure 2.

    Possible values: <= 36 characters

    threeDSecureVersionstring

    This is the 3D Secure protocol version, returned in the response.

    Note: If version 2 is not available for the card provided, the value defaults to 1.0.2.

    Possible values: >= 5 characters and <= 8 characters

    acsUrlstring

    This is the fully qualified URL to redirect the consumer to complete the payer authentication transaction.

    payloadstring

    This is the encoded Payment Authentication Request generated by the merchant authentication processing system (MAPS).

    sdkChallengePayloadstring

    This is a payload that, if returned, should be passed to the challenge function of the JavaScript SDK to continue with the challenge.

    xidstring

    This is the transaction identifier returned by the card issuer.

    Note: This exists only for 3DS 1.0.2.

    Possible values: <= 40 characters

    threeDEnrollmentstring

    Possible values for ThreeDEnrollment are:

    • Y - AVAILABLE
    • N - NOT_ENROLLED
    • U - UNAVAILABLE

    Possible values: [Y, N, U]

    maxAuthorizationsForInstalmentPaymentnumber

    This is the maxAuthorizationsForInstalmentPayment of the request, in minor units.

    Possible values: >= 1 and <= 999

    electronicDelivery object
    emailstring

    This is the email address to which the merchandise was delivered.

    Possible values: <= 240 characters

    Example: example@example.com
    isElectronicDeliveryboolean

    This indicates whether there is an electronic delivery for the product.

    initialPurchaseTimestring

    This is the date and time of the purchase. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

    Note: This element is required only if messageCategory=NON_PAYMENT and authenticationPurpose=INSTALMENT_TRANSACTION or RECURRING_TRANSACTION.

    amountnumber

    This is the amount of the request, in minor units.

    Possible values: <= 99999999999

    deviceDetails object

    This is part of Interac e-Transfer withdrawal Payment Handle request. It is used by Interac Online for risk assessment

    deviceIdstring

    This is part of Interac e-Transfer withdrawal Payment Handle request. This parameter is mandatory if "browserDetails" json object is not passed as a part of Interac e-Transfer withdrawal Payment Handle request. It is used by Interac Online for risk assessment.

    Example: 876313
    shippingDetails object
    shipMethodstring

    This is the method of shipment. Possible values are:

    • N – Next Day/Overnight
    • T – Two-Day Service
    • C – Lowest Cost
    • O – Other
    • S – Same Day
    Example: Vishnu
    streetstring

    This is the recipient's street address.

    Possible values: <= 50 characters

    Example: 20735 Stevens Creek Blvd
    street2string

    This is the second line of the street address in the shipping address, if required (e.g., apartment number).

    Possible values: <= 255 characters

    Example: Montessori
    citystring

    This is the city in which the recipient resides.

    Possible values: <= 40 characters

    Example: Cupertino
    statestring

    This is the state/province/region in which the recipient lives.

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

    Example: ON
    countrystring

    This is the country where the address is located. See Country Codes.

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

    Example: CA
    zipstring

    This is the recipient's postal/zip code.

    Possible values: <= 10 characters

    Example: 95014
    wallet object

    Embedded wallet details for the operation.

    customerIdstringrequired

    The customer wallet id.

    Possible values: <= 50 characters

    feeinteger

    The fee to be applied on this transaction.

    feeSettlementCurrencystring

    This is the currency for fee settlement into the merchant account, e.g., USD or CAD, returned in the request response. See Currency Codes.

    Note: If not specified the fee will be settled using the payment currency.

    Possible values: <= 3 characters

    Example: USD
    feeWalletIdstring

    Id of the merchant wallet where merchant fee is collected.

    slipIdstring

    Wallet slip id. The wallet slip is a collection of all transactions associated with specic wallet operation (deposit, withdrawal or transfer).

    Possible values: <= 50 characters

    customerAccount object

    The customer wallet account id. If this is not provided, a wallet account id is automatically created in the processing currency. If provided, and processing currency specified is different than the wallet account currency, then an error is returned.

    In the case of Standalone Credits, this field is mandatory. If there is insufficient funds in the specified account, then an error is returned for Standalone Credit.

    idstring

    The wallet account id

    Possible values: <= 50 characters

    verifiedInstrumentbooleandeprecated

    It specifies if the instrument (card, sepa, fasterPayments etc) has been previously verfied.

    The default value for this is false. If this is specified as false, Paysafe will verify the instrument and rejects the transaction, if the verification fails. This is applicable only for STANDALONE_CREDIT.

    Default value: false
    risk object

    Embedded wallet risk related parameters.

    customerRiskRatingnumber

    risk rating for the customer at time of transaction or wallet creation

    isScaPerformedboolean
    isCustomerIPTrustedboolean
    isBeneficiaryTrustedboolean
    paymentHandleRequest
    {
      "merchantRefNum": "merchantRefNum-101",
      "transactionType": "PAYMENT",
      "accountId": "9876543210",
      "paymentType": "CARD",
      "amount": 500,
      "currencyCode": "USD",
      "paymentHandleTokenFrom": "SCyGZDlUuZ9zxjyd",
      "profile": {
        "id": "string",
        "status": "string",
        "merchantCustomerId": "string",
        "locale": "en_US",
        "firstName": "Venkata Suresh",
        "lastName": "Chagalamarri",
        "email": "paysafe@gmail.com",
        "phone": "1234567891",
        "dateOfBirth": {
          "day": 6,
          "month": 5,
          "year": 1998
        },
        "mobile": "9846573804",
        "gender": "M",
        "nationality": "Indian",
        "identityDocuments": [
          {
            "identityDocuments": [
              {
                "type": "SOCIAL_SECURITY",
                "documentNumber": "SSN123456"
              },
              {
                "type": "PASSPORT",
                "documentNumber": "1234567",
                "issuingCountry": "USA",
                "issuingCountrySubdvision": "SA",
                "expiryDate": {
                  "month": 12,
                  "year": 2022
                }
              }
            ]
          }
        ]
      },
      "billingDetails": {
        "id": "string",
        "status": "string",
        "nickName": "Home",
        "street": "Street",
        "street1": "street1",
        "street2": "street2",
        "city": "Toronto",
        "state": "ON",
        "country": "CA",
        "zip": "M5H 2N2",
        "phone": "8765846321"
      },
      "splitpay": {
        "linkedAccount": "123124124",
        "amount": 505,
        "percent": 5
      },
      "merchantDescriptor": {
        "dynamicDescriptor": "OnlineStore",
        "phone": "999-8888"
      },
      "returnLinks": {
        "rel": "default",
        "href": "https://US_commerce_site/payment/return/success",
        "method": "GET"
      },
      "customerIp": "111.111.111.111",
      "transactionIntent": {
        "transactionIntent": "CRYPTO_ON_RAMP"
      },
      "singleUseCustomerToken": "string",
      "threeDs": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "deviceFingerprintingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantRefNum": "fc5b62df1202e491475d",
        "process": true,
        "merchantUrl": "https://api.qa.paysafe.com/checkout/v2/demo-store/index.html",
        "deviceChannel": "BROWSER",
        "requestorChallengePreference": "NO_PREFERENCE",
        "messageCategory": "PAYMENT",
        "transactionIntent": "GOODS_OR_SERVICE_PURCHASE",
        "authenticationPurpose": "PAYMENT_TRANSACTION",
        "billingCycle": {
          "endDate": "2024-07-29",
          "frequency": 0
        },
        "orderItemDetails": {
          "preOrderItemAvailabilityDate": "2024-07-29",
          "preOrderPurchaseIndicator": "MERCHANDISE_AVAILABLE",
          "reorderItemsIndicator": "FIRST_TIME_ORDER",
          "shippingIndicator": "SHIP_TO_BILLING_ADDRESS"
        },
        "purchasedGiftCardDetails": {
          "amount": 1234,
          "count": 2,
          "currency": "USD"
        },
        "userAccountDetails": {
          "addCardAttemptsForLastDay": 0,
          "changedDate": "2024-07-29",
          "changedRange": "DURING_TRANSACTION",
          "createdDate": "2024-07-29",
          "createdRange": "NO_ACCOUNT",
          "passwordChangedDate": "2024-07-29",
          "passwordChangedRange": "NO_CHANGE",
          "suspiciousAccountActivity": true,
          "totalPurchasesSixMonthCount": 0,
          "transactionCountForPreviousDay": 0,
          "transactionCountForPreviousYear": 0,
          "shippingDetailsUsage": {
            "cardHolderNameMatch": true,
            "initialUsageDate": "2024-07-29",
            "initialUsageRange": "CURRENT_TRANSACTION"
          },
          "userLogin": {
            "authenticationMethod": "NO_LOGIN",
            "data": "Some up to 2048 bytes undefined data",
            "time": "2024-07-29T15:51:28.071Z"
          },
          "paymentAccountDetails": {
            "createdRange": "NO_ACCOUNT",
            "createdDate": "2024-07-29"
          },
          "priorThreeDSAuthentication": {
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "data": "Some up to 2048 bytes undefined data",
            "method": "FRICTIONLESS_AUTHENTICATION",
            "time": "2024-07-29T15:51:28.071Z"
          },
          "travelDetails": {
            "isAirTravel": false,
            "airlineCarrier": "string",
            "departureDate": "2024-07-29",
            "destination": "string",
            "origin": "string",
            "passengerFirstName": "string",
            "passengerLastName": "string"
          }
        },
        "priorThreeDSAuthentication": {
          "id": "123e4567-e89b-12d3-a456-426655440000",
          "data": "Some up to 2048 bytes undefined data",
          "method": "FRICTIONLESS_AUTHENTICATION",
          "time": "2024-07-29T15:51:28.071Z"
        },
        "shippingDetailsUsage": {
          "cardHolderNameMatch": true,
          "initialUsageDate": "2024-07-29",
          "initialUsageRange": "CURRENT_TRANSACTION"
        },
        "suspiciousAccountActivity": true,
        "totalPurchasesSixMonthCount": 0,
        "transactionCountForPreviousDay": 0,
        "transactionCountForPreviousYear": 0,
        "travelDetails": {
          "isAirTravel": false,
          "airlineCarrier": "string",
          "departureDate": "2024-07-29",
          "destination": "string",
          "origin": "string",
          "passengerFirstName": "string",
          "passengerLastName": "string"
        },
        "userLogin": {
          "authenticationMethod": "NO_LOGIN",
          "data": "Some up to 2048 bytes undefined data",
          "time": "2024-07-29T15:51:28.071Z"
        },
        "browserDetails": {
          "acceptHeader": "string",
          "colorDepthBits": "1",
          "customerIp": "string",
          "javaEnabled": true,
          "javascriptEnabled": true,
          "language": "string",
          "screenHeight": 0,
          "screenWidth": 0,
          "timezoneOffset": 0,
          "userAgent": "string"
        },
        "cavv": "string",
        "eci": 0,
        "status": "COMPLETED",
        "threeDResult": "Y",
        "txnTime": "string",
        "directoryServerTransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "threeDSecureVersion": "string",
        "acsUrl": "string",
        "payload": "string",
        "sdkChallengePayload": "string",
        "xid": "string",
        "threeDEnrollment": "Y",
        "maxAuthorizationsForInstalmentPayment": 0,
        "electronicDelivery": {
          "email": "example@example.com",
          "isElectronicDelivery": true
        },
        "initialPurchaseTime": "string",
        "amount": 0
      },
      "deviceDetails": {
        "deviceId": "876313"
      },
      "shippingDetails": {
        "shipMethod": "Vishnu",
        "street": "20735 Stevens Creek Blvd",
        "street2": "Montessori",
        "city": "Cupertino",
        "state": "ON",
        "country": "CA",
        "zip": "95014"
      },
      "wallet": {
        "customerId": "string",
        "fee": 0,
        "feeSettlementCurrency": "USD",
        "feeWalletId": "string",
        "slipId": "string",
        " customerAccount": {
          "id": "string"
        },
        "risk": {
          "customerRiskRating": 0,
          "isScaPerformed": true,
          "isCustomerIPTrusted": true,
          "isBeneficiaryTrusted": true
        }
      },
      "card": {
        "cardNum": "4111111111111111",
        "cardExpiry": {
          "month": 12,
          "year": 2022
        },
        "cvv": "string",
        "holderName": "Suresh's card",
        "cardType": "AM",
        "lastDigits": "string",
        "nickName": "string",
        "cardBin": "411111"
      }
    }