Skip to main content

Create a Payment Handle

POST 
/v1/paymenthandles

Paysafe Embedded Wallet leverages PaymentHandle to initiate deposit and withdrawal operations.

  • Deposits - correspond to paymentType=PAYMENT
  • Withdrawals - correspond to paymentType=STANDALONE_CREDIT
  • For all Paysafe Wallet operations the additional wallet property is required to be present.

A Payment Handle represents tokenized information about the payment method that you set up for your customer. Once the Payment Handle is created, you can then include the paymentHandleToken returned in the Payment Handle request response in a new payment request.

Note: A Payment Handle can be used in a Payment request only if it has the status of PAYABLE.

  • A Payment Handle for a standard credit card deposit
  • A Payment Handle for a credit card deposit that is registered for 3D Secure - the response for this request will contain a redirect to present to the customer so they can validate their 3D Secure credentials
  • A Payment Handle for a credit card withdraw (Standalone Credit)
  • A Payment Handle for a RapidTransfer deposit

Note: The status of Payment Handles will remain INITIATED for the following cases:

  • When the customer is redirected to a redirect_payment URL until the customer verifies the payment instrument.
  • When the requested amount is more than the maximum amount configured in the Business Portal.
  • When Alternate Payment Methods like RapidTransfer, Paysafecash are selected by the customer.

Request​

Header Parameters

    Simulator string

    Possible values: [EXTERNAL, INTERNAL]

    Default value: EXTERNAL

    Content-Type string

    Possible values: [application/json]

Body

    oneOf

    card

    object

    Card details to be used for the transaction

    cardNum stringrequired

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

    This is the card number used for the request.

    cardExpiry

    object

    This is the card's expiry date.

    month numberrequired

    Possible values: <= 12

    This is the card expiry month.

    year numberrequired

    Possible values: <= 9999

    This is the card expiry year.

    cvv string

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

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

    cardType string

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

    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

    nickName string

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

    merchantRefNum stringrequired

    Possible values: <= 255 characters

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

    transactionType stringrequired

    Possible values: [PAYMENT, STANDALONE_CREDIT]

    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.

    accountId string

    Possible values: <= 10 characters

    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.

    paymentType stringrequired

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

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

    amount numberrequired

    Possible values: <= 99999999999

    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.

    currencyCode stringrequired

    Possible values: <= 3 characters

    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.

    paymentHandleTokenFrom string

    Possible values: <= 36 characters

    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.

    profile

    object

    This is customer's profile details.

    merchantCustomerId string

    Possible values: <= 10 characters

    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.

    locale stringrequired

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

    This indicates the customer's locale preference.

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

    firstName stringrequired

    Possible values: <= 80 characters

    This is the customer’s first name.

    lastName stringrequired

    Possible values: <= 80 characters

    This is the customer’s last name.

    email stringrequired

    Possible values: <= 255 characters

    This is the customer's email address.

    phone string

    Possible values: <= 40 characters

    This is the customer's phone number.

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

    dateOfBirth

    object

    This is the recipient's date of birth.

    day numberrequired

    Possible values: <= 31

    This is the day of birth.

    month numberrequired

    Possible values: <= 12

    This is the month of birth.

    year numberrequired

    Possible values: >= 1900

    This is the year of birth.

    mobile string

    Possible values: <= 40 characters

    Customer's mobile number.

    gender string

    Possible values: [M, F]

    This field indicates the Customer's gender.

    M - Male

    F - Female

    nationality string

    Possible values: <= 30 characters

    This field indicates the Customer's nationality.

    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

    type stringrequired

    Possible values: [SOCIAL_SECURITY]

    Default value: SOCIAL_SECURITY

    Value will always be "SOCIAL_SECURITY" This is part of 1st JSON object.

    documentNumber stringrequired

    Possible values: <= 9 characters

    The customer’s social security number.

  • ]

  • ]

    • 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.

    nickName string

    Possible values: <= 50 characters

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

    street stringrequired

    Possible values: <= 50 characters

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

    street1 string

    Possible values: <= 50 characters

    This is the first line of the street address.

    Note: Mandatory for VIPPreferred

    street2 string

    Possible values: <= 50 characters

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

    city stringrequired

    Possible values: <= 40 characters

    This is the city where the address is located.

    state string

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

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

    country stringrequired

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

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

    zip stringrequired

    Possible values: <= 10 characters

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

    phone string

    Possible values: <= 40 characters

    This is the customer's telephone number.

    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.

    linkedAccount stringrequired

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

    amount number

    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.

    percent number

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

    merchantDescriptor

    object

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

    dynamicDescriptor stringrequired

    Possible values: <= 20 characters

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

    phone string

    Possible values: <= 13 characters

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

    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.

    rel stringrequired

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

    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.

    href stringrequired

    This is the URI of the resource.

    method stringrequired

    This is the HTTP method.

    customerIp string

    Possible values: <= 39 characters

    This is the customer's IP address.

    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 caseMCCValid transactionIntent value
    The consumer is acquiring cryptocurrency in a transaction.6012, 6051CRYPTO_ON_RAMP
    The consumer is loading a cryptocurrency wallet or exchange account with fiat. *Applicable only in combination with valid fundingTransaction object.6012, 6051WALLET_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, 6051QUASI_CASH
    For purchases of goods or services that leverage a live conversion of fiat into non - fiat currency.ANYBUY_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).

    transactionIntent string

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

    singleUseCustomerToken string

    Possible values: <= 36 characters

    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.

    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.

    deviceFingerprintingId uuid

    Possible values: <= 36 characters

    This is the UUID used with device fingerprinting.

    merchantRefNum string

    Possible values: <= 255 characters

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

    process boolean

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

    merchantUrl string

    Possible values: <= 2048 characters

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

    deviceChannel string

    Possible values: [BROWSER, APP, 3RI]

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

    requestorChallengePreference string

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

    This indicates whether a challenge is requested for this transaction.

    messageCategory string

    Possible values: [PAYMENT, NON_PAYMENT]

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

    transactionIntent string

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

    This identifies the type of transaction being authenticated.

    authenticationPurpose string

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

    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.

    billingCycle

    object

    Details of the billing cycle information for recurring payments.

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

    endDate date

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

    frequency number

    This is the minimum number of days between authorizations.

    orderItemDetails

    object

    preOrderItemAvailabilityDate date

    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.

    preOrderPurchaseIndicator string

    Possible values: [MERCHANDISE_AVAILABLE, FUTURE_AVAILABILITY]

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

    reorderItemsIndicator string

    Possible values: [FIRST_TIME_ORDER, REORDER]

    This indicates whether the cardholder is reordering merchandise.

    shippingIndicator string

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

    This is the shipping method for the transaction.

    purchasedGiftCardDetails

    object

    amount number

    Possible values: <= 99999999999

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

    count number

    Possible values: <= 99

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

    currency string

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

    userAccountDetails

    object

    These are the user account details from the merchant website.

    changedDate date

    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.

    changedRange string

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

    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.

    createdDate date

    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.

    createdRange string

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

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

    passwordChangedDate date

    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.

    passwordChangedRange string

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

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

    suspiciousAccountActivity boolean

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

    totalPurchasesSixMonthCount number

    Possible values: <= 9999

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

    transactionCountForPreviousDay number

    Possible values: <= 999

    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.

    transactionCountForPreviousYear number

    Possible values: <= 999

    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.

    shippingDetailsUsage

    object

    This is the shipping usage information.

    cardHolderNameMatch boolean

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

    initialUsageDate date

    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.

    initialUsageRange string

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

    userLogin

    object

    This is the cardholder login information.

    authenticationMethod string

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

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

    data string

    Possible values: <= 2048 characters

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

    time date-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.

    createdRange string

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

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

    createdDate date

    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.

    id string

    Possible values: <= 36 characters

    This is the previous authentication ID for the cardholder.

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

    data string

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

    method string

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

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

    time date-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.

    isAirTravel boolean

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

    airlineCarrier string

    Possible values: <= 256 characters

    This is the selected airline carrier.

    departureDate date

    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.

    destination string

    Possible values: <= 5 characters

    This is the airport code of the destination airport.

    origin string

    Possible values: <= 5 characters

    This is the airport code of the originating airport.

    passengerFirstName string

    Possible values: <= 99 characters

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

    passengerLastName string

    Possible values: <= 99 characters

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

    priorThreeDSAuthentication

    object

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

    id string

    Possible values: <= 36 characters

    This is the previous authentication ID for the cardholder.

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

    data string

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

    method string

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

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

    time date-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.

    cardHolderNameMatch boolean

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

    initialUsageDate date

    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.

    initialUsageRange string

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

    suspiciousAccountActivity boolean

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

    totalPurchasesSixMonthCount number

    Possible values: <= 9999

    Transaction count for last 6 months.

    transactionCountForPreviousDay number

    Possible values: <= 999

    Transaction count for last 24 hours

    transactionCountForPreviousYear number

    Possible values: <= 999

    Transaction count for last 1 year.

    travelDetails

    object

    These are the Amex-specific travel details.

    isAirTravel boolean

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

    airlineCarrier string

    Possible values: <= 256 characters

    This is the selected airline carrier.

    departureDate date

    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.

    destination string

    Possible values: <= 5 characters

    This is the airport code of the destination airport.

    origin string

    Possible values: <= 5 characters

    This is the airport code of the originating airport.

    passengerFirstName string

    Possible values: <= 99 characters

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

    passengerLastName string

    Possible values: <= 99 characters

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

    userLogin

    object

    This is the cardholder login information.

    authenticationMethod string

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

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

    data string

    Possible values: <= 2048 characters

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

    time date-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.

    acceptHeader stringrequired

    Possible values: <= 2048 characters

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

    colorDepthBits stringrequired

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

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

    customerIp stringrequired

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

    javaEnabled booleanrequired

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

    javascriptEnabled booleanrequired

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

    language stringrequired

    Possible values: <= 8 characters

    This is the language in the browser.

    screenHeight numberrequired

    Possible values: <= 999999

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

    screenWidth numberrequired

    Possible values: <= 999999

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

    timezoneOffset numberrequired

    Possible values: <= 99999

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

    userAgent stringrequired

    Possible values: <= 256 characters

    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

    cavv string

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

    eci number

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

    status string

    Possible values: [COMPLETED, PENDING, FAILED]

    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.

    threeDResult string

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

    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
    txnTime string

    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.

    directoryServerTransactionId uuid

    Possible values: <= 36 characters

    This is the directory server transaction ID required for Mastercard.

    Note: This exists only for 3D Secure 2.

    threeDSecureVersion string

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

    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.

    acsUrl string

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

    payload string

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

    sdkChallengePayload string

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

    xid string

    Possible values: <= 40 characters

    This is the transaction identifier returned by the card issuer.

    Note: This exists only for 3DS 1.0.2.

    threeDEnrollment string

    Possible values: [Y, N, U]

    Possible values for ThreeDEnrollment are:

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

    Possible values: >= 1 and <= 999

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

    electronicDelivery

    object

    email string

    Possible values: <= 240 characters

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

    isElectronicDelivery boolean

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

    initialPurchaseTime string

    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.

    amount number

    Possible values: <= 99999999999

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

    deviceDetails

    object

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

    deviceId string

    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.

    shippingDetails

    object

    shipMethod string

    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
    street string

    Possible values: <= 50 characters

    This is the recipient's street address.

    street2 string

    Possible values: <= 255 characters

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

    city string

    Possible values: <= 40 characters

    This is the city in which the recipient resides.

    state string

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

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

    country string

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

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

    zip string

    Possible values: <= 10 characters

    This is the recipient's postal/zip code.

    wallet

    object

    Embedded wallet details for the operation.

    customerId stringrequired

    Possible values: <= 50 characters

    The customer wallet id.

    fee integer

    The fee to be applied on this transaction.

    feeSettlementCurrency string

    Possible values: <= 3 characters

    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.

    feeWalletId string

    Id of the merchant wallet where merchant fee is collected.

    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.

    id string

    Possible values: <= 50 characters

    The wallet account id

    verifiedInstrument booleandeprecated

    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.

    deviceInfo

    object

    Device profiling information required for embedded wallet risk evaluation.

    appType stringrequired

    Possible values: [WEB_APP, MOBILE_APP, API]

    Application type.

    threatMetrixSessionId string

    Possible values: <= 100 characters

    The Threat Metrix Session Id.

    threatMetrixData string

    Possible values: <= 25600 characters

    The URL-encoded response as received from Threat Metrix

    risk

    object

    Embedded wallet risk related parameters.

    customerRiskRating number

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

    isScaPerformed boolean
    isCustomerIPTrusted boolean
    isBeneficiaryTrusted boolean

Responses​

Created

Response Headers

  • Content-Type

    string

Schema

    oneOf

    card

    object

    Card details to be used for the transaction

    cardNum stringrequired

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

    This is the card number used for the request.

    cardExpiry

    object

    This is the card's expiry date.

    month numberrequired

    Possible values: <= 12

    This is the card expiry month.

    year numberrequired

    Possible values: <= 9999

    This is the card expiry year.

    cvv string

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

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

    holderName string

    Possible values: <= 50 characters

    This is the name of the card holder.

    cardType string

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

    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

    lastDigits string

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

    nickName string

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

    cardBin string

    Possible values: <= 6 characters

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

    id string

    Possible values: <= 36 characters

    This is the ID returned in the response. This ID can be used for future associated requests, for example, to look up the Payment Handle.

    paymentHandleToken string

    Possible values: <= 36 characters

    This is the payment token generated by Paysafe that will be used by merchants for Payment API requests.

    txnTime date-time

    This is the date and time the transaction was processed.

    status string

    Possible values: [INITIATED, PAYABLE, PROCESSING, FAILED, EXPIRED, COMPLETED]

    This is the status of the payment handle. Possible values are:

    • INITIATED – The transaction was initiated with the downstream provider.

    • PAYABLE – The merchant can use the Payment Handle for a Payment request.

    • PROCESSING – The Payment Handle was authorized by customer, awaiting PSP response.

    • FAILED – The transaction failed due to either an error or being declined.

    • EXPIRED – The Payment Handle expired because the merchant did not proceed with the Payment request.

    • COMPLETED – The Payment request was initiated successfully using the Payment Handle.

    liveMode boolean

    This flag indicates the environment.

    • true - Production
    • false - Non-Production
    usage string

    Possible values: [SINGLE_USE, MULTI_USE]

    This specifies how the Payment Handle will be used for Payments. Possible values are:

    • SINGLE_USE – The Payment Handle can be used for one transaction only and expiresif not used.

    • MULTI_USE – The Payment Handle can be used multiple times.

    action string

    Possible values: [NONE, REDIRECT]

    This specifies the next step of the user journey once they proceed to the Payment. Possible values are:

    • NONE – No action is required, for example, for a standard credit card payment.

    • REDIRECT – The user must be redirected in order to complete a Payment, for example, when an alternate payment method like Paysafecard is used.

    executionMode string

    Possible values: [SYNCHRONOUS, ASYNCHRONOUS]

    This specifies the action of the merchant server in order to complete the Payment. Possible values are:

    • SYNCHRONOUS – The status of the Payment request will be returned synchronously to the merchant, e.g., a credit card request.

    • ASYNCHRONOUS – The Payment request is not completed immediately and the merchant must rely on webhooks to retrieve the status of the Payment request.'

    timeToLiveSeconds number

    This is the period of time, in seconds, the paymentHandleToken is valid before expiration.

    gatewayResponse

    object

    This is the read-only raw response returned by an acquirer. It is returned only if your account is configured accordingly.

    id string

    This is the response id returned by the processor

    processor string

    This is the processor code of the transaction at Paysafe side

    code string

    This is acquirer identification code, such as DJN, CRX, etc.

    responseCode string

    This is the raw response returned by the acquirer.

    avsCode string

    This is the raw AVS code returned by the acquirer.

    avsResponse string

    Possible values: [MATCH, MATCH_ADDRESS_ONLY, MATCH_ZIP_ONLY, NO_MATCH, NOT_PROCESSED, UNKNOWN]

    This is the AVS response returned from the card issuer.

    balanceResponse string

    This is the balance remaining on a gift card, if a gift card was used for the original transaction.

    mid string

    This is the acquirer MID that was sent to the clearing house.

    terminalId string

    This is the merchant's terminal ID.

    batchNumber string

    This is the batch number.

    seqNumber string

    This is the merchant's sequence number.

    effectiveDate string

    This is the date of the bank deposit associated with the transaction.

    financingType string

    This is the type of financing offered.

    plan string

    This is the plan number for this financing transaction.

    gracePeriod string

    This is the grace period, in months, associated with deferred payment transactions.

    term string

    This is the number of payments, in months, for equal payment transactions.

    responseId string

    This is the response ID assigned by Credorax.

    requestId string

    This is the request ID assigned by Paysafe.

    description string

    This is a description of the response.

    authCode string

    This is the authorization code.

    txnDateTime string

    This is the transaction date and time.

    referenceNbr string

    This is the Bank net transaction ID/Merch Tran Ref

    responseReasonCode string

    This is the raw response reason code returned by Credorax.

    cvvVerification string

    Possible values: [MATCH, NO_MATCH, NOT_PROCESSED, UNKNOWN]

    This is the response to the cvv submitted with the transaction request.

    cvv2Result string

    This is the raw cvv2 result code.

    status string

    This is the status of the transaction at the processor side.

    orderId string

    Unique NETELLER reference for the order.

    profile

    object

    This is customer's profile details.

    id string

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

    status string

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

    merchantCustomerId string

    Possible values: <= 10 characters

    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.

    locale stringrequired

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

    This indicates the customer's locale preference.

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

    firstName stringrequired

    Possible values: <= 80 characters

    This is the customer’s first name.

    lastName stringrequired

    Possible values: <= 80 characters

    This is the customer’s last name.

    email stringrequired

    Possible values: <= 255 characters

    This is the customer's email address.

    phone string

    Possible values: <= 40 characters

    This is the customer's phone number.

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

    dateOfBirth

    object

    This is the recipient's date of birth.

    day numberrequired

    Possible values: <= 31

    This is the day of birth.

    month numberrequired

    Possible values: <= 12

    This is the month of birth.

    year numberrequired

    Possible values: >= 1900

    This is the year of birth.

    mobile string

    Possible values: <= 40 characters

    Customer's mobile number.

    gender string

    Possible values: [M, F]

    This field indicates the Customer's gender.

    M - Male

    F - Female

    nationality string

    Possible values: <= 30 characters

    This field indicates the Customer's nationality.

    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

    type stringrequired

    Possible values: [SOCIAL_SECURITY]

    Default value: SOCIAL_SECURITY

    Value will always be "SOCIAL_SECURITY" This is part of 1st JSON object.

    documentNumber stringrequired

    Possible values: <= 9 characters

    The customer’s social security number.

  • ]

  • ]

    • gatewayReconciliationId string

    Possible values: <= 36 characters

    Transaction identifier that can be used to reconcile this transaction with the provider gateway.

    updatedTime date-time

    Indicates the last updated time for the resource.

    statusTime date-time

    Indicates the last updated time for the resource.

    links

    object

    URL links to redirect customer during transaction flow

    rel string

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

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

    • redirect_registration - Merchant needs to redirect consumer to this url to complete registration.

    • redirect_payment - Merchant needs to redirect consumer to this url to complete authentication.

    • 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.

    href string

    The url to be used for further actions.

    method string

    The corresponding HTTP request method to be invoked on url.

    merchantRefNum stringrequired

    Possible values: <= 255 characters

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

    transactionType stringrequired

    Possible values: [PAYMENT, STANDALONE_CREDIT]

    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.

    accountId string

    Possible values: <= 10 characters

    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.

    paymentType stringrequired

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

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

    amount numberrequired

    Possible values: <= 99999999999

    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.

    currencyCode stringrequired

    Possible values: <= 3 characters

    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.

    paymentHandleTokenFrom string

    Possible values: <= 36 characters

    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.

    profile

    object

    This is customer's profile details.

    id string

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

    status string

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

    merchantCustomerId string

    Possible values: <= 10 characters

    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.

    locale stringrequired

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

    This indicates the customer's locale preference.

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

    firstName stringrequired

    Possible values: <= 80 characters

    This is the customer’s first name.

    lastName stringrequired

    Possible values: <= 80 characters

    This is the customer’s last name.

    email stringrequired

    Possible values: <= 255 characters

    This is the customer's email address.

    phone string

    Possible values: <= 40 characters

    This is the customer's phone number.

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

    dateOfBirth

    object

    This is the recipient's date of birth.

    day numberrequired

    Possible values: <= 31

    This is the day of birth.

    month numberrequired

    Possible values: <= 12

    This is the month of birth.

    year numberrequired

    Possible values: >= 1900

    This is the year of birth.

    mobile string

    Possible values: <= 40 characters

    Customer's mobile number.

    gender string

    Possible values: [M, F]

    This field indicates the Customer's gender.

    M - Male

    F - Female

    nationality string

    Possible values: <= 30 characters

    This field indicates the Customer's nationality.

    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

    type stringrequired

    Possible values: [SOCIAL_SECURITY]

    Default value: SOCIAL_SECURITY

    Value will always be "SOCIAL_SECURITY" This is part of 1st JSON object.

    documentNumber stringrequired

    Possible values: <= 9 characters

    The customer’s social security number.

  • ]

  • ]

    • 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.

    id string

    Possible values: <= 36 characters

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

    status string

    This is the status of the address.

    nickName string

    Possible values: <= 50 characters

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

    street stringrequired

    Possible values: <= 50 characters

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

    street1 string

    Possible values: <= 50 characters

    This is the first line of the street address.

    Note: Mandatory for VIPPreferred

    street2 string

    Possible values: <= 50 characters

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

    city stringrequired

    Possible values: <= 40 characters

    This is the city where the address is located.

    state string

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

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

    country stringrequired

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

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

    zip stringrequired

    Possible values: <= 10 characters

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

    phone string

    Possible values: <= 40 characters

    This is the customer's telephone number.

    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.

    linkedAccount stringrequired

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

    amount number

    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.

    percent number

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

    merchantDescriptor

    object

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

    dynamicDescriptor stringrequired

    Possible values: <= 20 characters

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

    phone string

    Possible values: <= 13 characters

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

    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.

    rel stringrequired

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

    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.

    href stringrequired

    This is the URI of the resource.

    method stringrequired

    This is the HTTP method.

    customerIp string

    Possible values: <= 39 characters

    This is the customer's IP address.

    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 caseMCCValid transactionIntent value
    The consumer is acquiring cryptocurrency in a transaction.6012, 6051CRYPTO_ON_RAMP
    The consumer is loading a cryptocurrency wallet or exchange account with fiat. *Applicable only in combination with valid fundingTransaction object.6012, 6051WALLET_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, 6051QUASI_CASH
    For purchases of goods or services that leverage a live conversion of fiat into non - fiat currency.ANYBUY_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).

    transactionIntent string

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

    singleUseCustomerToken string

    Possible values: <= 36 characters

    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.

    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.

    id uuid

    Possible values: <= 36 characters

    This is the unique ID returned in the response.

    deviceFingerprintingId uuid

    Possible values: <= 36 characters

    This is the UUID used with device fingerprinting.

    merchantRefNum string

    Possible values: <= 255 characters

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

    process boolean

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

    merchantUrl string

    Possible values: <= 2048 characters

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

    deviceChannel string

    Possible values: [BROWSER, APP, 3RI]

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

    requestorChallengePreference string

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

    This indicates whether a challenge is requested for this transaction.

    messageCategory string

    Possible values: [PAYMENT, NON_PAYMENT]

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

    transactionIntent string

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

    This identifies the type of transaction being authenticated.

    authenticationPurpose string

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

    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.

    billingCycle

    object

    Details of the billing cycle information for recurring payments.

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

    endDate date

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

    frequency number

    This is the minimum number of days between authorizations.

    orderItemDetails

    object

    preOrderItemAvailabilityDate date

    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.

    preOrderPurchaseIndicator string

    Possible values: [MERCHANDISE_AVAILABLE, FUTURE_AVAILABILITY]

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

    reorderItemsIndicator string

    Possible values: [FIRST_TIME_ORDER, REORDER]

    This indicates whether the cardholder is reordering merchandise.

    shippingIndicator string

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

    This is the shipping method for the transaction.

    purchasedGiftCardDetails

    object

    amount number

    Possible values: <= 99999999999

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

    count number

    Possible values: <= 99

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

    currency string

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

    userAccountDetails

    object

    These are the user account details from the merchant website.

    addCardAttemptsForLastDay number

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

    changedDate date

    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.

    changedRange string

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

    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.

    createdDate date

    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.

    createdRange string

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

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

    passwordChangedDate date

    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.

    passwordChangedRange string

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

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

    suspiciousAccountActivity boolean

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

    totalPurchasesSixMonthCount number

    Possible values: <= 9999

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

    transactionCountForPreviousDay number

    Possible values: <= 999

    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.

    transactionCountForPreviousYear number

    Possible values: <= 999

    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.

    shippingDetailsUsage

    object

    This is the shipping usage information.

    cardHolderNameMatch boolean

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

    initialUsageDate date

    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.

    initialUsageRange string

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

    userLogin

    object

    This is the cardholder login information.

    authenticationMethod string

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

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

    data string

    Possible values: <= 2048 characters

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

    time date-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.

    createdRange string

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

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

    createdDate date

    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.

    id string

    Possible values: <= 36 characters

    This is the previous authentication ID for the cardholder.

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

    data string

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

    method string

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

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

    time date-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.

    isAirTravel boolean

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

    airlineCarrier string

    Possible values: <= 256 characters

    This is the selected airline carrier.

    departureDate date

    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.

    destination string

    Possible values: <= 5 characters

    This is the airport code of the destination airport.

    origin string

    Possible values: <= 5 characters

    This is the airport code of the originating airport.

    passengerFirstName string

    Possible values: <= 99 characters

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

    passengerLastName string

    Possible values: <= 99 characters

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

    priorThreeDSAuthentication

    object

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

    id string

    Possible values: <= 36 characters

    This is the previous authentication ID for the cardholder.

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

    data string

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

    method string

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

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

    time date-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.

    cardHolderNameMatch boolean

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

    initialUsageDate date

    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.

    initialUsageRange string

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

    suspiciousAccountActivity boolean

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

    totalPurchasesSixMonthCount number

    Possible values: <= 9999

    Transaction count for last 6 months.

    transactionCountForPreviousDay number

    Possible values: <= 999

    Transaction count for last 24 hours

    transactionCountForPreviousYear number

    Possible values: <= 999

    Transaction count for last 1 year.

    travelDetails

    object

    These are the Amex-specific travel details.

    isAirTravel boolean

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

    airlineCarrier string

    Possible values: <= 256 characters

    This is the selected airline carrier.

    departureDate date

    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.

    destination string

    Possible values: <= 5 characters

    This is the airport code of the destination airport.

    origin string

    Possible values: <= 5 characters

    This is the airport code of the originating airport.

    passengerFirstName string

    Possible values: <= 99 characters

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

    passengerLastName string

    Possible values: <= 99 characters

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

    userLogin

    object

    This is the cardholder login information.

    authenticationMethod string

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

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

    data string

    Possible values: <= 2048 characters

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

    time date-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.

    acceptHeader stringrequired

    Possible values: <= 2048 characters

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

    colorDepthBits stringrequired

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

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

    customerIp stringrequired

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

    javaEnabled booleanrequired

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

    javascriptEnabled booleanrequired

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

    language stringrequired

    Possible values: <= 8 characters

    This is the language in the browser.

    screenHeight numberrequired

    Possible values: <= 999999

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

    screenWidth numberrequired

    Possible values: <= 999999

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

    timezoneOffset numberrequired

    Possible values: <= 99999

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

    userAgent stringrequired

    Possible values: <= 256 characters

    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

    cavv string

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

    eci number

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

    status string

    Possible values: [COMPLETED, PENDING, FAILED]

    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.

    threeDResult string

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

    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
    txnTime string

    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.

    directoryServerTransactionId uuid

    Possible values: <= 36 characters

    This is the directory server transaction ID required for Mastercard.

    Note: This exists only for 3D Secure 2.

    threeDSecureVersion string

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

    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.

    acsUrl string

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

    payload string

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

    sdkChallengePayload string

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

    xid string

    Possible values: <= 40 characters

    This is the transaction identifier returned by the card issuer.

    Note: This exists only for 3DS 1.0.2.

    threeDEnrollment string

    Possible values: [Y, N, U]

    Possible values for ThreeDEnrollment are:

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

    Possible values: >= 1 and <= 999

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

    electronicDelivery

    object

    email string

    Possible values: <= 240 characters

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

    isElectronicDelivery boolean

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

    initialPurchaseTime string

    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.

    amount number

    Possible values: <= 99999999999

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

    deviceDetails

    object

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

    deviceId string

    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.

    shippingDetails

    object

    shipMethod string

    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
    street string

    Possible values: <= 50 characters

    This is the recipient's street address.

    street2 string

    Possible values: <= 255 characters

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

    city string

    Possible values: <= 40 characters

    This is the city in which the recipient resides.

    state string

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

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

    country string

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

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

    zip string

    Possible values: <= 10 characters

    This is the recipient's postal/zip code.

    wallet

    object

    Embedded wallet details for the operation.

    customerId stringrequired

    Possible values: <= 50 characters

    The customer wallet id.

    fee integer

    The fee to be applied on this transaction.

    feeSettlementCurrency string

    Possible values: <= 3 characters

    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.

    feeWalletId string

    Id of the merchant wallet where merchant fee is collected.

    slipId string

    Possible values: <= 50 characters

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

    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.

    id string

    Possible values: <= 50 characters

    The wallet account id

    verifiedInstrument booleandeprecated

    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.

    risk

    object

    Embedded wallet risk related parameters.

    customerRiskRating number

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

    isScaPerformed boolean
    isCustomerIPTrusted boolean
    isBeneficiaryTrusted boolean
Loading...