SDK - Add Card

Tokenize customer cards using the PayOrc Flutter SDK for secure storage and future payments.

SDK - Add Card

Generate an API Key for SDKs channel: Navigate to Developers → API Keys → Add new API key → Select SDK/Plugins in the Channel Dropdown.

1. Overview

This document provides guidance on how to tokenize a customer's card using the PayOrc Flutter SDK and securely use the generated token for future transactions.

2. Flow Summary

Customer enters card details within the mobile application
A successful request generates a secure card token
Merchant stores the token securely on their backend
SDK uses the stored token to process future payments

3. SDK Initialization

Initialize the SDK at application startup using your merchant credentials.

PayorcSdk.init(
  merchantKey: merchantKey,
  merchantSecret: merchantSecret,
  environment: PayorcEnvironment.sandbox,
  language: PayorcLanguage.english,
);

Always switch to PayorcEnvironment.production in live environments.

4. Card Tokenization (Add Card)

Use the addCard method to securely tokenize customer card details.

PayOrc.addNewCard(
  context,
  paymentRequest: _p.addCardPaymentRequest,
  initialCard: card,
  onAddCard: _handleAddCardSheetResult,
);

The _p.addCardPaymentRequest object includes all required transaction parameters. Billing and shipping details collected during card tokenization are reused for future transactions using the m_payment_token, eliminating the need to resend them.

PaymentRequest.addCard Parameters

Field	Type	Description
orderDetails	Array	List of order details associated with the transaction.
`mOrderId` (optional)	String	Unique order identifier generated by the merchant.
`currency`	String	Transaction currency in ISO format (e.g., USD, AED).
`description` (optional)	String	Description of the order (e.g., Event Ticket Purchase).
customerDetails	Object	Contains customer-related information.
`mCustomerId`	String	Unique identifier for the customer.
`name`	String	Full name of the customer.
`email`	String	Email address of the customer.
`mobile`	String	Customer mobile number.
`code`	String	Country dialing code (e.g., 971 for UAE).
billingDetails	Object	Billing address details of the customer.
`addressLine1`	String	Primary billing address line.
`addressLine2` (optional)	String	Secondary billing address line.
`city` (optional)	String	City of the billing address.
`province` (optional)	String	State or province of the billing address.
`country`	String	Country code in ISO format (e.g., AE).
`pin` (optional)	String	Postal/ZIP code of the billing address.
shippingDetails (optional)	Object	Shipping address and delivery-related information.
`shippingName` (optional)	String	Name of the recipient for shipping.
`shippingEmail` (optional)	String	Email address of the recipient.
`shippingCode` (optional)	String	Country dialing code for shipping contact.
`shippingMobile` (optional)	String	Mobile number of the recipient.
`addressLine1` (optional)	String	Primary shipping address line.
`addressLine2` (optional)	String	Secondary shipping address line.
`city` (optional)	String	City of the shipping address.
`province` (optional)	String	State or province of the shipping address.
`country` (optional)	String	Country code in ISO format.
`pin` (optional)	String	Postal/ZIP code of the shipping address.
`locationPin` (optional)	String	Google Maps location URL for delivery reference.

CardData Structure

initialCard = CardData(
  this.cardNumber,
  required this.cardholderName,
  required this.expiryMonth,
  required this.expiryYear,
  required this.cvv,
);

5. Response Format

Use the payment_method_data.m_payment_token to securely tokenize customer card details. This token can be stored on your backend and used for future transactions without needing to handle sensitive card information again.

{
    "status": "success",
    "code": "CARD_VERIFIED",
    "message": "Your card has been successfully verified.",
    "payment_method_data": {
        "m_payment_token": "WVNnWlBoVEZRsOWhIZndPUT09",
        "scheme": "VISA",
        "card_country": "POLAND",
        "card_type": "DEBIT",
        "mask_card_number": "4111****1111"
    }
}

void _handleAddCardSheetResult(BuildContext sheetContext, CardData card) {
  ///  TODO: save card in List
}

Response Parameters

Field	Type	Description
`status`	String	Indicates the overall status of the request (e.g., success, failed).
`code`	String	Response code representing the result of the operation (e.g., CARD_VERIFIED).
`message`	String	Human-readable message describing the result of the operation.
`payment_method_data`	Object	Contains tokenized card and related metadata.
`m_payment_token`	String	Unique token generated for the card. This should be stored securely and used for future transactions.
`scheme`	String	Card network/brand (e.g., VISA, MASTERCARD, AMEX).
`card_country`	String	Country where the card was issued.
`card_type`	String	Type of card (e.g., CREDIT, DEBIT).
`mask_card_number`	String	Masked card number showing only first 4 and last 4 digits.

6. Error Handling

Error Code	Description
INVALID_CARD	Card number validation failed
CARD_EXPIRED	Card has expired
INVALID_CVV	CVV validation failed
NETWORK_ERROR	Network connectivity issue
SDK_NOT_INITIALIZED	SDK has not been initialized

7. Best Practices

Never store raw card numbers — Always use the token returned by the SDK.
Store tokens securely — Use encrypted storage (Keychain on iOS, EncryptedSharedPreferences on Android).
Validate inputs — Check card number, expiry, and CVV before submission.
Handle errors gracefully — Show appropriate messages for different error types.

Payment with Token — Process payments using saved tokens
UI Customization — Customize the payment UI appearance

SDK - Add Card

On this page