SDK - Payment with Token

Process payments using saved card tokens with the PayOrc Flutter SDK — no card re-entry required.

SDK - Payment with Token

1. Overview

The Payment with Token flow allows merchants to charge a customer using a previously saved card token (m_payment_token) without requiring the customer to re-enter card details.

This enables:

Faster checkout experience
Secure transactions (no card data handling)
Seamless repeat payments

2. Prerequisites

Before initiating a token-based payment:

Card must be tokenized using the Add Card flow
A valid m_payment_token must be stored securely on the merchant backend

3. Payment Flow

Customer selects a saved card
Merchant retrieves stored m_payment_token
SDK is invoked with transaction details
Payment is processed using the token

4. PaymentRequest.submitOrder

PayOrc.submitOrder(
  context,
  card: card,
  paymentRequest: _p.request,
  addCardPaymentRequest: _p.addCardPaymentRequest,
  onNewCardAdded: _onCardAdded,
  onSuccessPayment: (_) {
    /// Show order details to user
  },
  onPaymentFailed: (
    BuildContext submitModalContext,
    String message, {
    String? code,
  }) {
    /// Handle failure (e.g., analytics)
  },
  onRetryPayment: () {
    /// Handle retry (e.g., analytics)
  },
);

paymentRequest = PaymentRequest.submitOrder({
  required this.paymentToken,
  required this.orderDetails,
  required this.customerDetails,
  required this.billingDetails,
  required this.shippingDetails,
  required this.urls,
  this.parameters = const [],
  this.customData = const [],
  this.viewType = PaymentViewType.bottomsheet,
});

Parameters

Field	Type	Description
`payment_token`	String	Unique token generated for the card. Must be stored securely and used for future transactions.
customer_details	Object	Customer name, email, phone
`m_customer_id`	String	Unique Identifier of the customer. Should match with add card token. Maxlength: 50
`name`	String	Customer first name and last name. Maxlength: 50
`email`	String	Customer email. Maxlength: 50
`mobile`	String	Customer mobile number. Length: According to country code
`code`	String	ISO Phone Codes, Check reference table. Minlength: 1, Maxlength: 9
order_details	Object	Order ID, amount, currency
`m_order_id` (optional)	String	Unique Identifier of the order
`amount`	Number	Order amount
`convenience_fee` (optional)	Number	Convenience Fee
`quantity` (optional)	Number	Order quantity
`currency`	String	Currency code. ISO-3 currency code 3 Characters
`description` (optional)	String	This field contains description. Maxlength: 200
billings_details	Object	Billing address information
`address_line1`	String	Customer billing address. Maxlength: 50
`address_line2` (optional)	String	Customer billing address. Maxlength: 50
`city` (optional)	String	Customer city. Maxlength: 50
`province` (optional)	String	Customer province/state. Maxlength: 50
`country`	String	Customer ISO Country Codes, Check reference table. 2 Characters
`pin` (optional)	String	Customer area zip-code. Minlength: 3, Maxlength: 13
shipping_details	Object	Shipping address information
`shipping_name` (optional)	String	Customer Name
`shipping_mobile` (optional)	String	Customer Mobile Number
`shipping_code` (optional)	String	Customer ISO Country Codes, Check reference table. 2 Characters
`shipping_email` (optional)	String	Customer email.
`address_line1` (optional)	String	Customer shipping address. Maxlength: 50
`address_line2` (optional)	String	Customer shipping address. Maxlength: 50
`city` (optional)	String	Customer city. Maxlength: 50
`province` (optional)	String	Customer province/state. Maxlength: 50
`country` (optional)	String	Customer ISO Country Codes, Check reference table. 2 Characters
`pin` (optional)	String	Customer area zip-code. Minlength: 3, Maxlength: 13
`location_pin` (optional)	Url	Customer location pin should be a url
`shipping_currency` (optional)	String	Customer Currency code. ISO-3 currency code 3 Characters
`shipping_amount` (optional)	Number	Shipping amount
parameters	Object	Any additional set of data merchant wants to add in the request.
`alpha`	String	Merchant defined data
`beta`	String	Merchant defined data
`gamma`	String	Merchant defined data
`delta`	String	Merchant defined data
`epsilon`	String	Merchant defined data
custom_data	Object	Reserved for PayOrc special features like MID Group and Split payments. After enabling merchant can pass the custom data in the request.
`alpha`	String	Custom data
`beta`	String	Custom data
`gamma`	String	Custom data
`delta`	String	Custom data
`epsilon`	String	Custom data

5. Response Format

{
  "action": "AUTH",
  "status": "SUCCESS",
  "order_status": "AUTHORISED",
  "m_order_id": "",
  "p_order_id": "1000010139",
  "p_request_id": "1000015740",
  "psp_ref_id": "030079987119",
  "transaction_id": "1000011980",
  "is_live": false,
  "terminal_label": "",
  "remark": "",
  "reason": "",
  "currency": "AED",
  "amount": "199.00",
  "channel": "SDK/PLUGINS",
  "channel_id": "",
  "shipping_fee": "0.00",
  "convenience_fee": "0.00",
  "customer_details": {
    "name": "John Doe",
    "email": "[email protected]",
    "code": "971",
    "mobile": "555555555",
    "m_customer_id": "customer_12345"
  },
  "billing_address": {
    "address_line_1": "Event Venue",
    "address_line_2": "",
    "city": "",
    "state": "",
    "country": "AE",
    "pincode": ""
  },
  "shipping_address": {
    "address_line_1": "",
    "address_line_2": "",
    "city": "",
    "state": "",
    "country": "",
    "pincode": ""
  },
  "ip_country": "",
  "psp": "TELR",
  "payment_method": "DEBIT CARD",
  "m_payment_token": "WVNnWlBoVEZRsOWhIZndPUT09",
  "transaction_time": "30-03-2026 16:39:01",
  "payment_method_data": {
    "scheme": "VISA",
    "card_country": "POLAND",
    "card_type": "DEBIT",
    "mask_card_number": "4111****1111",
    "expiry_month": "12",
    "expiry_year": "2045"
  },
  "apm_name": "",
  "apm_identifier": "",
  "sub_merchant_identifier": "0000001181",
  "parameters": [
    { "alpha": "" },
    { "beta": "" },
    { "gamma": "" },
    { "delta": "" },
    { "epsilon": "" }
  ],
  "custom_data": [
    { "alpha": "" },
    { "beta": "" },
    { "gamma": "" },
    { "delta": "" },
    { "epsilon": "" }
  ]
}

Response Parameters

Field	Type	Description
`action`	String	Transaction action type AUTH or SALE
`status`	String	Overall transaction execution status. Will be "SUCCESS" only when order_status is "FAILED" will status be "FAILED".
`order_status`	String	Detailed order status from the system. Possible values: AUTHORISED, FAILED, CAPTURED.
`m_order_id`	String	Order ID provided by the merchant.
`p_order_id`	String	Order ID generated by the PayOrc platform.
`p_request_id`	String	Unique PayOrc ID for the transaction event.
`psp_ref_id`	String	Reference ID received from the PSP.
`transaction_id`	String	Unique PayOrc transaction identifier for follow-up actions.
`is_live`	Boolean	Indicates whether the transaction was processed in live mode.
`terminal_label`	String	Terminal label or identifier used for processing the transaction.
`currency`	String	Transaction currency (ISO 4217).
`amount`	String	Transaction amount.
`shipping_fee`	String	Shipping charges applied to the transaction.
`convenience_fee`	String	Convenience or service fee applied to the transaction.
`channel`	String	Payment initiation channel.
`channel_id`	String	Unique identifier of the channel (e.g., payment link ID).
`customer_details`	Object	Customer information provided during order creation.
`name`	String	Customer full name.
`email`	String	Customer email address.
`code`	String	Country calling code of the customer.
`mobile`	String	Customer mobile number.
`m_customer_id`	String	Merchant-side customer identifier.
`billing_address`	Object	Billing address of the customer.
`shipping_address`	Object	Shipping address of the customer.
`ip_country`	String	Country detected from the customers IP address.
`remark`	String	Additional remarks related to the transaction.
`reason`	String	Failure or informational reason code.
`psp`	String	Payment service provider name.
`payment_method`	String	Payment method used by the customer.
`m_payment_token`	String	Payment token generated for the transaction.
`transaction_time`	String	Date and time when the transaction was processed.
`payment_method_data`	Object	Card or payment instrument details.
`apm_name`	String	Name of the alternative payment method.
`apm_identifier`	String	Identifier for the alternative payment method.
`sub_merchant_identifier`	String	Sub-merchant identifier mapped with the PSP.
`parameters`	Object	System-defined key-value parameters.
`custom_data`	Object	Merchant-defined custom key-value data.

6. Handling 3D Secure

The SDK automatically handles 3D Secure challenges. When 3DS is required:

SDK displays the 3DS challenge screen
Customer completes authentication
SDK returns the payment result

No additional code is needed — the SDK manages the entire 3DS flow.

7. Best Practices

Handle all statuses — Always implement onSuccessPayment, onPaymentFailed, and onRetryPayment callbacks.
Unique order IDs — Use unique order IDs to prevent duplicate charges.
Secure token storage — Store m_payment_token encrypted on your backend.
Network resilience — Handle timeout scenarios with retry logic.

Add Card (Tokenization) — Tokenize customer cards securely
UI Customization — Customize the payment UI appearance

SDK - Payment with Token

On this page