PSCardFormController

Initialize

Securely collect card information on the client with PSCardFormController, a pre-defined cards component provided by the SDK that collects the card number, expiration date and CVC.

Pass the following parameters during its initialization from the application:

The cardholder name view defined through Android XML or Jetpack Compose.
The card number view defined through Android XML or Jetpack Compose.
The card expiry view defined through Android XML or Jetpack Compose.
The CVV view defined through Android XML or Jetpack Compose.

The initialize method's signatures are as follows, depending on the fields view types (XML Layout or Jetpack Compose):

/** 

Initializes the PSCardFormController with the specified configuration and views.

@param cardFormConfig The configuration for the card form payment.

@param cardNumberView Optional parameter representing the view for the card number input.

@param cardHolderNameView Optional parameter representing the view for the cardholder name input.

@param cardExpiryDateView Optional parameter representing the view for the card expiry date input.

@param cardCvvView Optional parameter representing the view for the CVV input.

@param callback Callback to receive the initialized PSCardFormController.

*/

fun initialize(

    cardFormConfig: PSCardFormConfig,

    cardNumberView: PSCardNumberView? = null,

    cardHolderNameView: PSCardholderNameView? = null,

    cardExpiryDateView: PSExpiryDateView? = null,

    cardCvvView: PSCvvView? = null,

    completion: PSCallback<PSCardFormController>

)

Parameter	Required	Type	Description
cardFormConfig	true	PSCardFormConfig	The configuration for the card payment.
cardNumberView	false	PSCardNumberInputView or PSCardNumberInputSwiftUIView	Card number field view
cardHolderNameView	false	PSCardholderNameInputView or PSCardholderNameInputSwiftUIView	Card holder field view
cardExpiryDateView	false	PSCardExpiryInputView or PSCardExpiryInputSwiftUIView	Card expiry date view
cardCvvView	false	PSCardCVVInputView or PSCardCVVInputSwiftUIView	Card CVV field view
completion	true	PSCallback<PSCardFormController>	This callback to receive the initialized PSCardFormController. It returns the instance via onSuccess function, and an exception via onFailure
PsCardFormConfig
currencyCode	true	String	The currencyCode accepts 3 letter abbreviations of the ISO standard currencies.
accountId	true	String	The id of the selected merchant account to use to process the payment. 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.

Card form fields

Paysafe SDK supports building the checkout experience using both XML Layout and Jetpack Compose.

All fields automatically pick up the global theme for styling, but you can also update an individual field's appearance (see Form Field Styling for more information).

Card Holder Name field

This is a text field specialized for securely storing and validating cardholder names.

<com.paysafe.android.hostedfields.cardnumber.PSCardHolderNameView

  android:id="@+id/cardHolderNameView"

  android:layout_width="@dimen/no_size"

  android:layout_height="wrap_content"/>

PSCardholderNameField(

    modifier = Modifier.fillMaxWidth(),

    labelInsideField = "Placeholder",

    isValidLiveData = MutableLiveData(false),

    psTheme = defaultTheme

)

Card Number field

This is a text field specialized for securely storing and validating card number values. It automatically validates and updates itself based on the card brand and allows different options for the card number separator.

<com.paysafe.android.hostedfields.cardnumber.PSCardNumberView

    app:psSeparator="dash"

    android:id="@+id/creditCardNumberField"

    android:layout_width="@dimen/no_size"

    android:layout_height="wrap_content" />

PSCardNumberField(

    cardNumberModifier = PSCardNumberModifier(

        modifier = Modifier.fillMaxWidth(),

        cardBrandModifier = Modifier.padding(end = 16.dp)

    ),

    labelInsideField = "Placeholder",

    psTheme = defaultTheme,

    separator = CardNumberSeparator.DASH

)

Possible values for separators:

WHITESPACE: Whitespace separator
NONE: No separator
DASH: Dash separator
SLASH: Slash separator

Card Expiry Date field

This field handles card expiry formatting, styling, auto-cursor movement for the year part, and offers a date picker widget for ease of selection.

Based on the desired input type, the hosted fields module offers 2 components for getting the expiry card date:

PSExpiryDateTextView

For normal text input. It automatically applies the MM/YY format.

<com.paysafe.android.hostedfields.cardnumber.PSExpiryDateTextView

    android:id="@+id/creditCardExpiryDateField"

    android:layout_width="@dimen/no_size"

    android:layout_height="wrap_content" />

PSExpiryDateTextField(

    labelInsideField = "Expiry date",

    placeholderText = "MM   YY",

    psTheme = provideDefaultPSTheme(),

    modifier = Modifier.fillMaxWidth()

)

PSExpiryDatePickerView

Opens a dialog date picker.

<com.paysafe.android.hostedfields.cardnumber.PSExpiryDatePickerView

    android:id="@+id/creditCardExpiryDateField"

    android:layout_width="@dimen/no_size"

    android:layout_height="wrap_content" />

PSExpiryDatePickerField(

    labelInsideField = "Expiry date",

    placeholderText = "MM   YY",

    psTheme = provideDefaultPSTheme(),

    modifier = Modifier.fillMaxWidth()

)

Card CVV field

This field handles card CVV formatting, styling, and hiding the CVV, and offers essential events for handling customer interactions. Because some cards have 4-digit CVVs while others have 3 digits, the number of accepted characters in the form updates automatically based on the card number entered.

<com.paysafe.android.hostedfields.cardnumber.PSCvvView

    app:psIsMasked="true"

    android:id="@+id/creditCardExpiryDateField"

    android:layout_width="@dimen/no_size"

    android:layout_height="wrap_content" />

PSCvvField(

    modifier = Modifier.fillMaxWidth(),

    labelInsideField = "",

    psTheme = defaultTheme,

    isMasked = false,

)

Parameters:

isMasked: Boolean indicating if the text should be masked (password like). Default is false.

PSCallback

Internally, PSCallback is an interface including onSucess & OnFailure functions to handle initialization state and exceptions:

interface PSCallback<T> {

    /**

     * Executed if asynchronous operation was successful.

     *

     * @param value Response value returned in the request.

     */

    fun onSuccess(value: T)

 

    /**

     * Executed if asynchronous operation failed.

     *

     * @property exception Exception thrown by asynchronous operation.

     */

    fun onFailure(exception: Exception)

}

Usage example

PSCardFormController.initialize(

    cardFormConfig = PSCardFormConfig(

        currencyCode = "USD",

        accountId = Consts.CARDS_ACCOUNT_ID

    ),

    cardNumberView = binding.creditCardNumberField,

    cardHolderNameView = binding.creditCardHolderNameField,

    cardExpiryDateView = binding.creditCardExpiryDateField,

    cardCvvView = binding.creditCardCvvField,

    callback = object : PSCallback<PSCardFormController> {

        override fun onSuccess(value: PSCardFormController) {

            // handle success, retain the card form instance

            cardController = value

        }

 

        override fun onFailure(exception: Exception) {

            // handle exception

        }

    }

)

Exceptions

Error code	Display message	Detailed message	Comments
9061	There was an error (9061), please contact our support.	Invalid account id for ${paymentMethod}	AccountId is present, but is not configured for the wanted payment context.
9101	There was an error (9101), please contact our support.	Invalid accountId parameter	The SDK checks if the accountId string has only numbers.
9055	There was an error (9055), please contact our support.	Invalid currency parameter	The SDK checks if currency param that has 3 letters only. This exception is thrown when the server responds with code 5001.
9085	There was an error (9085), please contact our support.	There are no available payment methods for this API key.
9031	There was an error (9031), please contact our support.	Invalid card number separator	['-', ' ', '']; these are the allowed card num separators
9084	There was an error (9084), please contact our support.	Failed to load available payment methods	Triggered when internal server error response for getting the payment methods api call.
9127	There was an error (9127), please contact our support.	resetCardDetails is available only when card fields are initialized
9073	There was an error (9073), please contact our support.	Account not configured correctly.	The error is a result of an improperly created merchant account configuration: Merchant has no account or payment methods configured. The account that is provided on initialize is not configured for the merchant.
9131	There was an error (9131), please contact our support.	Status of the payment handle is ${status}	Thrown whenever the status is checked and is FAILED.

Was this page helpful?

On this Page

Initialize
Card form fields
PSCallback
Usage example
Exceptions

Search Overlay

PSCardFormController

XML Layout

Jetpack Compose

XML Layout

Jetpack Compose

XML Layout

Jetpack Compose

XML Layout

Jetpack Compose

XML Layout

Jetpack Compose

Was this page helpful?

Thank you for your response!