Saved Cards Integration
Paysafe JS allows consumers to save cards and addresses to their customer profile, enabling faster payments for returning consumers. The SDK handles storage of the saved information on your behalf, using a secure process involving Customer Tokens.
Save Cards flow diagram
Typical Scenarios
Create a customer
Creating a customer is mandatory, as each card must be associated with a customer/ consumer.
-
Call the customers endpoint:
POST: paymenthub/v1/customers -
Include the following basic customer details:
firstName
lastName
email
merchantCustomerId - this is the identifier you use for the customer in the Customer API. -
The customer is created and we return an id, which is Paysafe's identifier for the customer.
Save a card
To save the card details, you have two options:
-
Save the card after the transaction (recommended).
With this option, you save the card following completion of the transaction using the token (paymentHandleToken). The token expires 300 seconds after creation.
- Initialize the SDK - see Setup Function for more information.
- Tokenize the provided card data - the result returned by the callback function contains a token (paymentHandleToken).
- When you have received the token, complete the transaction by calling either the Payments API, Standalone Credit API, Original Credit API, or Verification API.
- Call the Payment Handle Customer API to add the card details to the customer profile:
POST: paymenthub/v1/customers/{id}/paymenthandles
use the id received when you created the customer
pass the token as the value for paymentHandleTokenFrom. - The card details are saved and we return a permanent, multi-use paymentHandleToken in the response (MUPH).
-
Save the card during the payment.
- Initialize the SDK.
- In the setup options, set the following parameters:
transactionType: PAYMENT
paymentType: CARD - Additionally, set parameter customerOperation: ADD.
- Tokenize the provided card data - the result returned by the callback function contains a token (paymentHandleToken).
- When you have received the token, complete the transaction by calling the Payments API using the merchantCustomerId.
To fetch a permanent token, call the Customer Payment Handles API using the customer id.
Complete transactions
- You can use the paymentHandleToken returned in the Customer Payment Handles API directly (without CVV) for transactions in either the Payments API, Standalone Credit API, Original Credit API, or Verification API.
- If you have multiple accounts, pass the accountId parameter to use a particular account.
Special Cases
In cases where additional information is required for saved cards, such as a one-time update of CVV, the process involves a few more steps:
-
Create a single-use Customer Token - this tokenizes the consumer's saved information, comprising profile details, saved cards, addresses, and bank details (ACH, EFT, SEPA, and BACS) including mandates, and returns a one-time usable token for all data parameters.
- Call the following endpoint using Paysafe's Customer ID (returned in the Create Customer response):
POST: paymenthub/v1/customers/{customerId}/singleusecustomertokens - We return 2 important tokens in the response:
singleUseCustomerToken - a unique token identifying the consumer.
paymentHandleToken - contained in a paymentHandles array where each object holds details of the payment instrument, including the paymentHandleToken, which represents tokenized information for the payment instrument (Cards, ACH, EFT, SEPA, BACS).
These are valid for 900 seconds and must be used within that time frame before expiring.
- Call the following endpoint using Paysafe's Customer ID (returned in the Create Customer response):
-
Create a single-use Payment Handle Token:
- From the call to the SingleUseCustomerToken API (above), you have tokenized card information (card number and expiry date) in the form of a paymentHandleToken.
- Initialize the SDK.
- Tokenize the provided card data with additional information (CVV, holderName) along with singleUseCustomerToken, paymentHandleToken, and transactionType (either PAYMENT, STANDALONE_CREDIT, ORIGINAL_CREDIT, or VERIFICATION).
- The result returned by the callback function contains a token (paymentHandleToken).
-
Complete the transaction:
- When you receive the token, complete the transaction by calling either the Payments API, Standalone Credit API, Original Credit API or Verification API.
Saving a card to the Customer profile
After successfully issuing a single-use payment handle for card payment method from Paysafe.js, the merchant has the ability to add it to a customer profile based on the customer intentions.
-
For a new customer the merchant can use the Create a Profile Using a Single-Use Token which will create a new customer profile and will add the card details from the payment token.
-
For an existing customer the Create a Card Using a Single-Use Token will add the card details from the payment token to an existing customer profile.
-
Paysafe recommends to either make a successful payment using the token or verify that the token corresponds to a valid card before adding it to the customer profile.
Setup Paysafe.js with optional fields
Paysafe.js needs to be setup with optional Card Number and Expiry Date, additionally the merchant needs to hide the field containers in their website. Based on the merchant intentions the CVV field can be set to optional, if needed.
If the customer wishes to pay with a new card, the merchant can start visualizing the Card Number and Expiry Date. They will become required if the singleUseCustomerToken and paymentTokenFrom are not passed on tokenize function call.
<html>
...
<body>
<div hidden id="cardNumber"></div>
<div hidden id="expiryDate"></div>
<div id="cvv"></div>
<script>
paysafe.fields.setup("my API key", {
fields: {
cardNumber: {
selector: "#cardNumber",
optional: true
},
expiryDate: {
selector: "#expiryDate",
optional: true
}
cvv: {
selector: "#cvv"
}
}
}, function (instance, error) {...});
</script>
</body>
</html>
Tokenize with saved card
If the customer has already a profile created in Payments API, and there are cards associated with this profile, the merchant can now instruct Paysafe.js to perform a tokenization for a selected saved card by passing a single-use customer token and single-use payment handle to the tokenize function. Single-Use Customer Token is a temporary token representing the profile of the customer. The main purpose of the single-use customer token is to prevent exposing customer id and multi-use payment token at the front-end. Single-use payment handle is а temporary token representing the card details of the customer located in the paymentHandles object from the response of the single-use customer token creation. If the customer contains multiple cards, the merchant needs to pass the correct single-use payment handle based on the customer intentions.
Before performing a tokenization, the merchant needs to complete the steps:
-
Create a Single-Use Customer token on their Back-end (BE) server.
-
Retrieve the singleUseCustomerToken and the selected card paymentHandleToken from the response..
-
Send both tokens to the their Front-end (FE).
-
Pass them to the tokenize function using the singleUseCustomerToken and paymentTokenFrom parameter in the options object.
<html>
...
<body>
...
<script>
paysafe.fields.setup("my Base64 encoded single-use-token API key", {...}, function(instance, error) {
if (error) {
console.log(error);
} else {
var payButton = document.getElementById("payButton");
payButton.addEventListener("click", function (event) {
var singleUseProfile = createSingleUseProfile();
var options = {
...
singleUseCustomerToken: singleUseProfile.paymentToken,
paymentTokenFrom: singleUseProfile.cards[0].paymentToken
}
instance.tokenize(options , function(instance, error, result) {
if (error) {
console.log(error);
} else {
// handle result
}
});
});
}
});
</script>
</body>
</html>
Reset Card Details
The function provides flexibility for the merchant to clear previously inserted card data in Paysafe.js fields. This is to be used when the customer is switching between paying with а saved or а new card.
Optionally the Expiry Date can be prefilled by passing it as an argument in the following format ("MM", "YYYY"). In such scenario the merchant needs to visualize and lock the Expiry Date container, keep in mind that the feature is only for visualizing the Expiry Date and not for editing it.
Optionally, you can set a limit on the number of CVV digits in accordance with the card brand by including the card brand code. For example, instance.resetCardDetails('VI') will allow the cardholder to enter up to 3 digits in the CVV field. The supported values are AM, DC, DI, MC, and VI. If the card brand is not passed, Paysafe.JS accepts 4 digits in the CVV field by default.
<html>
...
<body>
...
<script>
paysafe.fields.setup("my Base64 encoded single-use-token API key", {...}, function(instance, error) {
if (error) {
console.log(error);
} else {
var payButton = document.getElementById("selectSavedCard");
payButton.addEventListener("click", function (event) {
instance.resetCardDetails()
});
}
});
</script>
</body>
</html>
Errors
| Code | Display Message | Detailed Message | Description |
|---|---|---|---|
| 9127 | There was an error (9127), please contact our support. | resetCardDetails is available only if card fields are initialized. | Used when card fields are not initialized. |