Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Save Cards

You can streamline the payment process by allowing returning consumers to save their card details, addresses, and profile information for future use.

NOTE:  Only the card numbers and expiry dates are stored - the CVV is not saved.

Therefore, for transactions where the CVV is mandatory, you must capture the CVV each time.

Create Customer and Save Cards flow

Typical Scenarios

Create a customer

Creating a customer is mandatory when using saved cards, 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 three options:

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

    • Call the Payment Handles API to create a payment handle:
      POST: paymenthub/v1/paymenthandles 
      transactionType: PAYMENT or STANDALONE_CREDIT or ORIGINAL_CREDIT or VERIFICATION
      paymentType: CARD
    • We tokenize the information and return a paymentHandleToken.
      The paymentHandleToken status depends on the 3DS configuration:
      INITIATED  (with 3DS) moving to PAYABLE once 3DS post-challenge is completed.
      PAYABLE  (without 3DS)
    • Configured webhooks are triggered at all stages.
    • When the status is PAYABLE, 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 paymentHandleToken as the value for paymentHandleTokenFrom.
    • The card details are saved and we return a permanent, multi-use paymentHandleToken in the response (MUPH).

  2. Save the card during the payment.

    • Create a payment handle with the following parameters: 
      transactionType: PAYMENT
      paymentType: CARD
    • Additionally, set parameter customerOperation: ADD.
    • We tokenize the information and return a paymentHandleToken.
      The paymentHandleToken status depends on the 3DS configuration:
      INITIATED  (with 3DS) moving to PAYABLE once 3DS post-challenge is completed.
      PAYABLE  (without 3DS)
    • Configured webhooks are triggered at all stages.
    • When the paymentHandleToken status is PAYABLE, complete the transaction by calling the Payments API using the merchantCustomerId.

  3. Save the card directly

    • Call the Payment Handle Customer API to add the card details to the customer profile:
      POST: paymenthub/v1/customers/{id}/paymenthandles

    • Optionally include billingDetails as this can improve the chances of a successful transaction.

To fetch a permanent token, call the Customer Payment Handles API using the customer id.

Update a customer

To update a customer's details or add new parameters, use the Update Customer API.

Update a saved card

To update the details of a saved card (expiry date and billing details), use the Update Customer Payment Handle API.

Complete transactions

 

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:

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

  2. 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.
    • Show the card details to the consumer and capture any additional information such as the CVV.
    • Call the Payment Handle API with the following:
      a card object containing the additional information (CVV, holderName)
      singleUseCustomerToken
      paymentHandleToken
      transactionType (either PAYMENT, STANDALONE_CREDIT, ORIGINAL_CREDIT, or VERIFICATION).
    • The additional information is tokenized and we return a new paymentHandleToken, which is active for 300 seconds.
      The paymentHandleToken status depends on the 3DS configuration:
      INITIATED  (with 3DS) moving to PAYABLE once 3DS post-challenge is completed.
      PAYABLE  (without 3DS).
    • Configured webhooks are triggered at all stages.

  3. Complete the transaction:

On this Page