CreatePaymentHandle

This createPaymentHandle function accepts a callback that receives a single-use token representing the user's sensitive card data. The Paysafe Payments API can use this token to take payments. Single-use tokens are valid for only five minutes and are not consumed by verification.

instance.createPaymentHandle(options, function(instance, error, result) {
  ...
});

The function signature contains the following parameters:

Parameter Required Type Description
options true object

Optional settings, that contain information about the 3D Secure (3DS) flow and additional customer data.

callback true function

Callback function invoked with the result of the tokenization.

Options
amount true number Integer representing the amount in minor units to charge the customer's card following 3DS check. Use the correct minor units amount for the merchant account currency. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese Yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139. The amount has to be supplied as a positive number and shouldn't be longer than 9 digits.Min = 1Max = 999999999When using 3DS 2 (i.e. useThreeDSecureVersion2= true), amount with value: "0" can be passed.
currency true string The currency code for the merchant's account, for example, USD or GBP.
accountId true number The id of the selected merchant account to use to process the payment.
paymentType true string This is the type of payment. eg: card, skrill etc.
profile false object This is the customer profile.
billingDetails false object Card billing address - additional details for the BillingAddress object can be found in the Paysafe Payments API documentation.
merchantRefNum false string
merchantDescriptor false object This consists of two params
holderName true string Card holder name
merchantDescriptor
dynamicDescriptor false string Description from merchant
phone false string Phone number of the merchant
billingDetails
country true string Country of billing address
zip true string Zip code of the address
state false string State/province/region of the address
city false string City in which the address is located
street false string First line of the street address
street2 false string Second line of the street address
profile
email false string

This is the email address of the customer.

length <= 255 chars

phone false string

This is the customer's primary phone.

length <= 40 chars

firstName false string

This is the customer's first name.

length <= 40 chars

lastName false string

This is the customer's last name.

length <= 40 chars

dateOfBirth false object Consists of day, month and year
shippingDetails
recipientName false string This is the recipient's name.
country true string Country of billing address
zip true string Zip code of the address
state false string State/province/region of the address
city false string City in which the address is located
street false string First line of the street address
street2 false string Second line of the street address
3DS
authenticationPurpose false string

Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. Possible values are:

  • PAYMENT_TRANSACTION
  • INSTALMENT_TRANSACTION

If omitted, defaults to PAYMENT_TRANSACTION.

maxAuthorizationsForInstalmentPayment conditional number

Indicates the maximum number of authorizations permitted for installment payments.

Min = 1

Max = 999

Required when authenticationPurpose = INSTALMENT_TRANSACTION.

billingCycle conditional object Billing cycle information for recurring payments.Required when authenticationPurpose = INSTALMENT_TRANSACTION.
electronicDelivery false object This is the electronic delivery information.
initialPurchaseTime conditional 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.
orderItemDetails false object These are the details of a previously made purchase or preorder.
purchasedGiftCardDetails false object These are the details of a previously made gift card purchase.
userAccountDetails false object These are the user account details from the merchant website.
billingCycle
endDate true string 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 true number

This is the minimum number of days between authorizations.

Min = 1

Max = 999

electronicDelivery
isElectronicDelivery true boolean This indicates whether there is an electronic delivery for the product. The electronicDelivery object is optional; however, if the object is used, this element is required.
email false string

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

length <= 240 chars

email false string

This is the email address of the customer.

length <= 255 chars

phone false string

This is the customer's primary phone.

length <= 40 chars

cellphone false string

This is the customer's cell phone.

length <= 40 chars

orderItemDetails
preOrderItemAvailabilityDate false string 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 false string

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

  • MERCHANDISE_AVAILABLE
  • FUTURE_AVAILABILITY
reorderItemsIndicator false string

This indicates whether the cardholder is reordering merchandise. Possible values are:

  • FIRST_TIME_ORDER
  • REORDER
shippingIndicator false string
  • This is the shipping method for the transaction. Possible values are:SHIP_TO_BILLING_ADDRESS
  • SHIP_TO_VERIFIED_ADDRESS
  • SHIP_TO_DIFFERENT_ADDRESS
  • SHIP_TO_STORE
  • DIGITAL_GOODS
  • TRAVEL_AND_EVENT_TICKETS
  • OTHER
purchasedGiftCardDetails
amount false number

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

Max = 99999999999

count false number

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

Max = 99

currency false string Three character code for the currency of the gift card – for example, USD for US dollars.
userAccountDetails
createdDate false string 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 false string

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 are:

  • DURING_TRANSACTION
  • NO_ACCOUNT
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
  • MORE_THAN_SIXTY_DAYS
changedDate false string 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 false string

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 are:

  • MORE_THAN_SIXTY_DAYS
  • DURING_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
passwordChangedDate false string 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 false string

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 are:

  • MORE_THAN_SIXTY_DAYS
  • NO_CHANGE
  • DURING_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
totalPurchasesSixMonthCount false number

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

Max = 9999

addCardAttemptsForLastDay false number

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

Max = 999

transactionCountForPreviousDay false number

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.

Max = 999

transactionCountForPreviousYear false number

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.

Max = 999

suspiciousAccountActivity false boolean This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.
shippingDetailsUsage false object This is the shipping usage information.
paymentAccountDetails false object These are the details of the current payment account of the cardholder.
userLogin false object This is the cardholder login information.
priorThreeDSAuthentication false object This is the previous authentication information used with current merchant, cardholder, and card.
travelDetails false object These are the Amex-specific travel details.
shippingDetailsUsage
cardHolderNameMatch false boolean This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.
initialUsageDate false string 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 false string

This is the length of time between the first use of this shipping address and the current transaction. Possible values are:

  • MORE_THAN_SIXTY_DAYS
  • CURRENT_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
paymentAccountDetails
createdDate false string 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.
createdRange false string
  • This indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Possible values are:
  • MORE_THAN_SIXTY_DAYS
  • NO_ACCOUNT
  • DURING_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
userLogin
data false string

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

length <= 2048 chars

authenticationMethod false string

This is the mechanism used by the cardholder to authenticate to the 3DS Requestor. Possible values are:

  • THIRD_PARTY_AUTHENTICATION
  • NO_LOGIN
  • INTERNAL_CREDENTIALS
  • FEDERATED_ID
  • ISSUER_CREDENTIALS
  • FIDO_AUTHENTICATOR
time false string 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.
priorThreeDSAuthentication
data false string

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

length <= 2048 chars

method false string

This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor. Possible values are:

  • FRICTIONLESS_AUTHENTICATION
  • ACS_CHALLENGE
  • AVS_VERIFIED
  • OTHER_ISSUER_METHOD
id false string

This is a previous authentication ID for the cardholder.

length <= 36 chars

time false string 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
isAirTravel false string

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

If omitted, defaults to false.

airlineCarrier conditional string

This is the selected airline carrier. Note: This element is required only if isAirTravel=true.

length <= 256 chars

departureDate conditional string

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. Note: This element is required only if isAirTravel=true.

destination conditional string

This is the airport code of the destination airport. Note: This element is required only if isAirTravel=true.

length <= 5 chars

origin conditional string

This is the airport code of the originating airport. Note: This element is required only if isAirTravel=true.

length <= 5 chars

passengerFirstName conditional string

This is the first name of the cardholder from the billing details. Note: This element is required only if isAirTravel=true.

length <= 99 chars

passengerLastName conditional string

This is the last name of the cardholder from the billing details. Note: This element is required only if isAirTravel=true.

length <= 99 chars

CreatePaymentHandle Example

<html>
    ...
    <body>
        ...
        <script>
            var options_new = {
        "amount": 123,
        "paymentType": "CARD",
        "holderName": "John Smith",
        "billingDetails": {
            "nickName": "John Dee",
            "street": "20735 Stevens Creek Blvd",
            "street2": "Montessori",
            "city": "Cupertino",
            "zip": "95014",
            "country": "US",
            "state": "CA"
          },
          "shippingDetails": {
            "recipientName": "John",
            "street": "20735 Stevens Creek Blvd",
            "street2": "Montessori",
            "city": "Cupertino",
            "zip": "95014",
            "country": "US",
            "state": "CA"
          },
        "merchantRefNum": "1608104239085",
        "merchantDescriptor": {
            "dynamicDescriptor": "Test Description",
            "phone": "123456"
        },
        "profile": {
            "firstName": "Vishnu",
            "lastName": "Vardhan",
            "email": "vishnu@paysafe.com",
            "phone": "1231231231",
            "dateOfBirth": {
              "day": 1,
              "month": 7,
              "year": 1990
            }
        },
        "threeDs": {
            "deviceChannel": "BROWSER"
        }
    };
            paysafe.fields.setup("my Base64 encoded single-use-token API key", options, function(instance, error) {
                if (error) {
                    console.log(error);
                } else {
                    var payButton = document.getElementById("payButton");
                    payButton.addEventListener("click", function (event) {
                        instance.createPaymentHandle(options_new,function(instance, error, result) {
                            if (error) {
                                console.log(error);
                            } else {
                                // handle result
                            }
                        });
                    });
                }
            });
        </script>
    </body>
</html>

The createPaymentHandle callback function has the following signature:

function callback(instance, errorResponse, result) {
    if (errorResponse) {
        // handle error
    } else {
        // use token
    }
}
The paramters are described below:

Profile dateOfBirth should be valid.
ParameterRequiredTypeDescription
instancetrueobject Paysafe.js instance
errorResponsefalse object Object containing information for the error.
resultfalse object Result containing the payment token.
errorResponse
codetrue string Short error code identifying the error type.
displayMessagetrue string An error message that can be displayed to users.
detailedMessage true string A detailed error message that can be logged.
correlationId true string Unique ID that can be provided to the Paysafe Support team as a reference for investigation.
result
token falsestringPayment token representing the sensitive card details following successful tokenization.
List of callback errors
9003There was an error (9003), please contact our support.

Invalid fields: ${fields}.

Invalid fields: ${fields}.
9054There was an error (9054), please contact our support.Invalid amount parameter. Used when an amount is not supplied, is not a number, is not positive, or is longer than 9 digits.
9043There was an error (9043), please contact our support.HolderName should be valid. Used when the supplied holderName parameter is not a string or Not passed
9044There was an error (9044), please contact our support.billingDetails country should be valid country code. Used when the supplied billingDetails.country parameter is not a string.
9204There was an error (9204), please contact our support.billingDetails nickName should be valid nickName. Used when the supplied billingDetails.nickname parameter isnot a valid string if provided. Max length is 50
9045There was an error (9045), please contact our support.billingDetails zip should be valid zip code. Used when the supplied billingDetails.zip parameter is not a string. Max length is 10
9046There was an error (9046), please contact our support.billingDetails state should be valid state. Used when the supplied billingDetails.state parameter is not a string.
9047There was an error (9047), please contact our support.billingDetails city should be valid city. Used when the supplied billingDetails.city parameter is not a string.
9048There was an error (9048), please contact our support.billingDetails street should be valid street. Used when the supplied billingDetails.street parameter is not a string. Max length is 50.
9049There was an error (9049), please contact our support.billingDetails street2 should be valid street. Used when the supplied billingAddress.street2 parameter is not a string if provided. Max length is 50
9115There was an error (9115), please contact our support.ShippingDetails should be an object. Used when the supplied ShippingDetailsparameter is not an object.
9116There was an error (9116), please contact our support.ShippingDetails recipientName should be a valid recipient name. Used when the supplied ShippingDetails.recipientName parameter is not a string.
9117There was an error (9117), please contact our support.ShippingDetails street should be a valid street. Used when the supplied ShippingDetails.street parameter is not a string.
9118There was an error (9118), please contact our support.ShippingDetails street2 should be a valid street. Used when the supplied ShippingDetails.street2 parameter is not a string.
9119There was an error (9119), please contact our support.ShippingDetails city should be a valid city. Used when the supplied ShippingDetails.city parameter is not a string.
9120There was an error (9120), please contact our support.ShippingDetails state should be a valid state. Used when the supplied ShippingDetails.state parameter is not a string.
9121There was an error (9121), please contact our support.ShippingDetails country should be a valid country. Used when the supplied ShippingDetails.country parameter is not a string.
9122There was an error (9122), please contact our support.ShippingDetails zip should be a valid zip code. Used when the supplied ShippingDetails.zip parameter is not a string.
9211There was an error (9211), please contact our support.Invalid merchantRefNum value. Invalid merchantRefNum value.
9205There was an error (9205), please contact our support.Invalid parameter in merchantDescriptor.dynamicDescriptor Invalid parameter in merchantDescriptor.dynamicDescriptor
9206There was an error (9206), please contact our support.Invalid parameter in merchantDescriptor.phone Invalid parameter in merchantDescriptor.phone
9004There was an error (9004), please contact our support.Callback should be function.
9002There was an error (9002), please contact our support.Error communicating with server. The response from the server cannot be handled.
9209There was an error (9209), please contact our support.Invalid options argument. Invalid options argument.
9207There was an error (9207), please contact our support.There are no accounts for the provided currency. There are no accounts for the provided currency.
9208There was an error (9208), please contact our support.Error Thrown from the API Error Thrown from the API
9050There was an error (9050), please contact our support.ThreeDS should be object. The threeDS parameter is not an object.
9210There was an error (9210), please contact our support.Invalid Device Channel parameter.
9208There was an error (9208), please contact our support.Error Thrown from the API Error Thrown from the API
9050There was an error (9050), please contact our support.ThreeDS should be object. The threeDS parameter is not an object.
9208There was an error (9208), please contact our support.Error Thrown from the API Error Thrown from the API
9050There was an error (9050), please contact our support.ThreeDS should be object. The threeDS parameter is not an object.
9212There was an error (9212), please contact our support.Invalid Payment Method.Invalid Payment Method.
9213There was an error (9213), please contact our support.Invalid AccountId. If multiple accounts are registered with same currency, accountId is mandatory. Invalid AccountId. If multiple accounts are registered with same currency, accountId is mandatory.
9214There was an error (9214), please contact our support.Profile options is not an object. Profile options is not an object.
9215There was an error (9215), please contact our support.Profile firstName should be valid. Profile firstName should be valid.
9216There was an error (9216), please contact our support.Profile LastName should be valid. Profile LastName should be valid.
9217There was an error (9217), please contact our support.Profile Email should be valid. Profile Email should be valid.
9218There was an error (9218), please contact our support. Profile dateOfBirth should be valid. Profile dateOfBirth should be valid.
9219There was an error (9219), please contact our support. Profile dateOfBirth should be less than current date. Profile dateOfBirth should be less than current date.
9099There was an error (9099), please contact our support. Status of the payment handle is ${status} Status of the payment handle is ${status}

Converting a single-use payment handle into a multi-use

You can convert the single-use payment handle to a re-usable permanent payment handle by sending it as a paymentHandleTokenFrom - Customer API . You will get the multi use payment handle as a response of the call. Paysafe recommends that you verify the single-use token corresponding to a valid card before creating the profile.

Did you find this page useful?