> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 1. Build Integration

> Steps to integrate your Custom Flutter application with Razorpay Payment Gateway.

Available in
🇮🇳 India
🇲🇾 Malaysia
🇸🇬 Singapore

Follow these steps to integrate your Flutter application with the Razorpay Payment Gateway:

**1.1** [Install Razorpay Flutter Plugin](#1-1-install-razorpay-flutter-plugin).

**1.2** [Add Dependencies](#1-2-add-dependencies).

**1.3** [Import Package](#1-3-import-package).

**1.4** [Create Razorpay instance](#1-4-create-razorpay-instance).

**1.5** [Attach Event Listeners](#1-5-attach-event-listeners).

**1.6** [Create an Order in Server](#1-6-create-an-order-in-server).

**1.7** [Add Checkout Options](#1-7-add-checkout-options).

**1.8** [Open Checkout](#1-8-open-checkout).

**1.9** [Store Fields in Your Server](#1-9-store-fields-in-your-server).

**1.10** [Verify Payment Signature](#1-10-verify-payment-signature).

**1.11** [Verify Payment Status](#1-8-verify-payment-status).

> [!NOTE]
>
> **Handy Tips**
>
> After you complete the integration:
>
> * Set up webhooks
> * Make test payments
> * Replace Test API keys with Live API keys
> * Integrate with other APIs\\
>
>   Refer to the [post-integration steps](https://razorpay.com/docs/my/payments/payment-gateway/flutter-integration/custom/test-integration.md).

> [!WARNING]
>
> **Watch Out!**
>
> If you use M1 MacBook, you need to make [these changes](#m1-macbook-changes) in your `podfile`.

## 1.1 Install Razorpay Flutter Plugin

[Download the plugin](https://pub.dev/packages/razorpay_flutter_customui) from Pub.dev.

## 1.2 Add Dependencies

Add the below code to `dependencies` in your app's `pubspec.yaml`:

```yml Add Dependencies theme={null}
razorpay_flutter_customui: 1.0.0
```

#### Add Proguard Rules (Android Only)

If you are using Proguard for your builds, you need to add the following lines to the Proguard files:

```java Add Proguard Rules theme={null}
-keepattributes *Annotation*
-dontwarn com.razorpay.**
-keep class com.razorpay.** {*;}
-optimizations !method/inlining/
-keepclasseswithmembers class * {
  public void onPayment*(...);
}
```

Know more about [Proguard rules](https://github.com/razorpay/razorpay-flutter/issues/42#issuecomment-550161626).

#### Get Packages

Run `flutter packages get` in the root directory of your app.

> [!NOTE]
>
> **Handy Tips**
>
> * For **Android**, ensure that the minimum API level for your app is 19 or higher.
> * For **iOS**, ensure that the minimum deployment target for your app is iOS 10.0 or higher. Also, do not forget to enable bitcode for your project.

## 1.3 Import Package

Use the below code to import the `razorpay_flutter_customui.dart` file to your project:

```yml Import Package theme={null}
import 'package:razorpay_flutter_customui/razorpay_flutter_customui.dart';
```

## 1.4 Create Razorpay instance

For Android, use the below code to create a Razorpay instance:

```java Instantiate theme={null}
_razorpay = Razorpay();
```

For iOS, you need to initialise and instantiate the SDK using the following method:

```swift Initialise and Instantiate theme={null}
@override
void initState() {
  _razorpay = Razorpay();
  _razorpay.initializeSDK(key);
}
```

## 1.5 Attach Event Listeners

The plugin uses event-based communication and emits events when payments fail or succeed.

* The event names are exposed via the constants `EVENT_PAYMENT_SUCCESS` and `EVENT_PAYMENT_ERROR` from the `Razorpay` class.
* Use the `on(String event, Function handler)` method on the Razorpay instance to attach event listeners.

```yml Attach Event Listeners theme={null}
_razorpay.on(Razorpay.EVENT_PAYMENT_SUCCESS, _handlePaymentSuccess);
_razorpay.on(Razorpay.EVENT_PAYMENT_ERROR, _handlePaymentError);
```

The handlers would be defined in the class as:

```yml Handlers theme={null}
void _handlePaymentSuccess(PaymentSuccessResponse response) {
  // Do something when payment succeeds
}

void _handlePaymentError(PaymentFailureResponse response) {
  // Do something when payment fails
}
```

## 1.6 Create an Order in Server

**Order is an important step in the payment process.**

* An order should be created for every payment.
* You can create an order using the [Orders API](#api-sample-code). It is a server-side API call. Know how to [authenticate](https://razorpay.com/docs/my/payments/dashboard/account-settings/api-keys.md#generate-api-keys) Orders API.
* The `order_id` received in the response should be passed to the checkout. This ties the order with the payment and secures the request from being tampered.

> [!WARNING]
>
> **Watch Out!**
>
> Payments made without an `order_id` cannot be captured and will be automatically refunded. You must create an order before initiating payments to ensure proper payment processing.

#### API Sample Code

Use this endpoint to create an order using the Orders API.

`POST /orders`

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v1/orders
-U [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-H 'content-type:application/json'
-d '{
   "amount": 100,
   "currency": "MYR",
   "receipt": "qwsaq1",
   "partial_payment": true,
   "first_payment_min_amount": 230,
   "notes": {
     "key1": "value3",
     "key2": "value2"
   }
 }'
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

 JSONObject orderRequest = new JSONObject();
 orderRequest.put("amount", 100); // amount in the smallest currency unit
 orderRequest.put("currency", "MYR");
 orderRequest.put("receipt", "order_rcptid_11");

 Order order = razorpay.Orders.create(orderRequest);
} catch (RazorpayException e) {
 // Handle Exception
 System.out.println(e.getMessage());
}
```

```python Python theme={null}
import razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

DATA = {
   "amount": 100,
   "currency": "MYR",
   "receipt": "receipt#1",
   "notes": {
       "key1": "value3",
       "key2": "value2"
   }
}
client.order.create(data=DATA)
```

```php PHP theme={null}
$api = new Api($key_id, $secret);

$api->order->create(array('receipt' => '123', 'amount' => 100, 'currency' => 'MYR', 'notes'=> array('key1'=> 'value3','key2'=> 'value2')));
```

```csharp .NET theme={null}
RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

Dictionary<string, object> options = new Dictionary<string,object>();
options.Add("amount", 100); // amount in the smallest currency unit
options.add("receipt", "order_rcptid_11");
options.add("currency", "MYR");
Order order = client.Order.Create(options);
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

options = amount: 100, currency: 'MYR', receipt: '<order_rcptid_11>'
order = Razorpay::Order.create
```

```javascript Node.js theme={null}
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.orders.create({
 amount: 100,
 currency: "MYR",
 receipt: "receipt#1",
 notes: {
   key1: "value3",
   key2: "value2"
 }
})
```

```go Go theme={null}
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data := map[string]interface{}{
 "amount": 100,
 "currency": "MYR",
 "receipt": "some_receipt_id"
}
body, err := client.Order.Create(data)
```

```json Success Response theme={null}
{
 "id": "order_IluGWxBm9U8zJ8",
 "entity": "order",
 "amount": 100,
 "amount_paid": 0,
 "amount_due": 100,
 "currency": "MYR",
 "receipt": "rcptid_11",
 "offer_id": null,
 "status": "created",
 "attempts": 0,
 "notes": [],
 "created_at": 1642662092
}
```

```json Failure Response theme={null}
{
 "error": {
   "code": "BAD_REQUEST_ERROR",
   "description": "Order amount less than minimum amount allowed",
   "source": "business",
   "step": "payment_initiation",
   "reason": "input_validation_failed",
   "metadata": {},
   "field": "amount"
 }
}
```

> [accordion] Request Parameters
>
> `amount` *mandatory*
> : `integer` Payment amount in the smallest currency subunit. For example, if the amount is ₹500, enter `50000`.
>
> `currency` *mandatory*
> : `string` The currency in which the payment should be made by the customer. Length must be of 3 characters.
>
> `receipt` *optional*
> : `string` Your receipt id for this order should be passed here. Maximum length is 40 characters.
>
> `notes` *optional*
> : `json object` Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.
>
> `partial_payment` *optional*
> : `boolean` Indicates whether the customer can make a partial payment. Possible values:
>
> * `true`: The customer can make partial payments.
> * `false` (default): The customer cannot make partial payments.
>
> `first_payment_min_amount` *optional*
> : `integer` Minimum amount that must be paid by the customer as the first partial payment. For example, if an amount of ₹7000 is to be received from the customer in two installments of #1 - ₹5000, #2 - ₹2000 then you can set this value as `500000`. This parameter should be passed only if `partial_payment` is `true`.
>
> Know more about Orders API.

> [accordion] Response Parameters
>
> Descriptions for the response parameters are present in the [Orders Entity](https://razorpay.com/docs/my/api/orders/entity.md) parameters table.

> [accordion] Error Response Parameters
>
> The error response parameters are available in the [API Reference Guide](https://razorpay.com/docs/my/api/orders/create.md).

## 1.7 Add Checkout Options

Pass the Checkout options. Ensure that you pass the `order_id` that you received in the response of the previous step.

```yml Checkout Options theme={null}
var options = {
                "key": key,
                "amount": 29935,
                "currency": "MYR",
                "contact": "<phone>",
                "email": "<email>",
                "order_id": "order_EMBFqjDHEEn80l", // Generate order_id using Orders API
                "description": "Fine T-Shirt",
                "method": "card",
                "card[name]": "Test User",
                "card[number]": "card number",
                "card[expiry_month]": 11,
                "card[expiry_year]": 30,
                "card[cvv]": <CVV>
            };
        _razorpay.submit(options);
```

You must pass these parameters in Checkout to initiate the payment.

`key` *mandatory*
: `string` API Key ID generated from the Razorpay Dashboard.

`amount` *mandatory*
: `integer` The amount to be paid by the customer in currency subunits. For example, if the amount is ₹100, enter `10000`.

`currency` *mandatory*
: `string` The currency in which the payment should be made by the customer.

`description` *optional*
: `string` Description of the product shown in the Checkout form. It must start with an alphanumeric character.

`image` *optional*
: `string` Link to an image (usually your business logo) shown in the Checkout form. Can also be a **base64** string, if loading the image from a network is not desirable.

`order_id` *mandatory*
: `string` Order ID generated via the Orders API.

`notes` *optional*
: `object` Set of key-value pairs that can be used to store additional information about the payment. It can hold a maximum of 15 key-value pairs, each 256 characters long (maximum).

`method` *mandatory*
: `string` The payment method used by the customer on Checkout. \
Possible values:

* `card` (default)
* `fpx` (default)
* `wallet` (default)

`card` *mandatory if method=card*
: `object` The details of the card that should be entered while making the payment.

`number`
: `integer` Unformatted card number.

`name`
: `string` The name of the cardholder.

`expiry_month`
: `integer` Expiry month for card in MM format.

`expiry_year`
: `integer` Expiry year for card in YY format.

`cvv`
: `integer` CVV printed on the back of the card.

`bank` *mandatory if method=fpx*
: `string` Bank code. List of available banks enabled for your account can be fetched via [**methods**](https://razorpay.com/docs/my/payments/payment-gateway/web-integration/custom/payment-methods.md#fetch-payment-methods).

`wallet` *mandatory if method=wallet*
: `string` Wallet code for the wallet used for the payment. Possible values:

* `touchngo` (default)
* `grabpay` (default)

`callback_url` *optional*
: `string` Customers will be redirected to this URL on successful payment. Ensure that the domain of the Callback URL is whitelisted. This parameter is mandatory for FPX payments.

`redirect` *optional*
: `boolean` Determines whether to post a response to the event handler post payment completion or redirect to Callback URL. `callback_url` and `redirect` parameters are mandatory for FPX payments. Possible values:

* `true`: Customer is redirected to the specified callback URL in case of payment failure. For FPX payments, the `redirect` parameter should always be sent as `true`.
* `false` (default): Customer is not redirected to the specified callback URL.

## 1.8 Open Checkout

Use the below code to open the Razorpay checkout:

```yml Open Razorpay Checkout theme={null}
_razorpay.submit(options);
```

## 1.9 Store Fields in Your Server

A successful payment returns the following fields to the Checkout form.

> [accordion] Success Callback
>
> * You need to store these fields in your server.
> * You can confirm the authenticity of these details by verifying the signature in the next step.
>
> ```json Success Callback theme={null}
> {
>   "razorpay_payment_id": "pay_29QQoUBi66xm2f",
>   "razorpay_order_id": "order_9A33XWu170gUtm",
>   "razorpay_signature": "9ef4dffbfd84f1318f6739a3ce19f9d85851857ae648f114332d8401e0949a3d"
> }
> ```
>
> `razorpay_payment_id`
> : `string` Unique identifier for the payment returned by Checkout **only** for successful payments.
>
> `razorpay_order_id`
> : `string` Unique identifier for the order returned by Checkout.
>
> `razorpay_signature`
> : `string` Signature returned by the Checkout. This is used to verify the payment.

## 1.10 Verify Payment Signature

This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.

> [accordion] To verify the `razorpay_signature` returned to you by the Checkout form:
>
> 1. Create a signature in your server using the following attributes:
>    * `order_id`: Retrieve the `order_id` from your server. Do not use the `razorpay_order_id` returned by Checkout.
>    * `razorpay_payment_id`: Returned by Checkout.
>    * `key_secret`: Available in your server. The `key_secret` that was generated from the [Dashboard](https://razorpay.com/docs/my/payments/dashboard/account-settings/api-keys.md#generate-api-keys).
> 2. Use the SHA256 algorithm, the `razorpay_payment_id` and the `order_id` to construct a HMAC hex digest as shown below:
>
> ```html HMAC Hex Digest theme={null}
> generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret);
>
>   if (generated_signature == razorpay_signature) {
>     payment is successful
>   }
> ```
>
> 3. If the signature you generate on your server matches the `razorpay_signature` returned to you by the Checkout form, the payment received is from an authentic source.

> [accordion] Generate Signature on Your Server
>
> Given below is the sample code for payment signature verification:
>
> ```java Java theme={null}
> RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");
>
> String secret = "testWebhookSecret1234567";
>
> JSONObject options = new JSONObject();
> options.put("razorpay_order_id", "order_IEIaMR65cu6nz3");
> options.put("razorpay_payment_id", "pay_IH4NVgf4Dreq1l");
> options.put("razorpay_signature", "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f");
>
> boolean status =  Utils.verifyPaymentSignature(options, secret);
> ```
>
> ```php PHP theme={null}
> $api = new Api($key_id, $secret);
>
> $api->utility->verifyPaymentSignature(array('razorpay_order_id' => $razorpayOrderId, 'razorpay_payment_id' => $razorpayPaymentId, 'razorpay_signature' => $razorpaySignature));
> ```
>
> ```ruby Ruby theme={null}
> require "razorpay"
> Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')
>
> payment_response = {
>        razorpay_order_id: 'order_IEIaMR65cu6nz3',
>        razorpay_payment_id: 'pay_IH4NVgf4Dreq1l',
>        razorpay_signature: '0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f'
>      }
> Razorpay::Utility.verify_payment_signature(payment_response)
> ```
>
> ```python Python theme={null}
> import razorpay
> client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))
>
> client.utility.verify_payment_signature({
>   'razorpay_order_id': razorpay_order_id,
>   'razorpay_payment_id': razorpay_payment_id,
>   'razorpay_signature': razorpay_signature
>   })
> ```
>
> ```c .NET theme={null}
> RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");
>
> Dictionary<string, string> options = new Dictionary<string, string>();
> options.Add("razorpay_order_id", "order_IEIaMR65cu6nz3");
> options.Add("razorpay_payment_id", "pay_IH4NVgf4Dreq1l");
> options.Add("razorpay_signature", "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f");
>
> Utils.verifyPaymentSignature(options);
> ```
>
> ```javascript Node.js theme={null}
> var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })
>
> var { validatePaymentVerification, validateWebhookSignature } = require('./dist/utils/razorpay-utils');
> validatePaymentVerification({"order_id": razorpayOrderId, "payment_id": razorpayPaymentId }, signature, secret);
> ```
>
> ```go Go theme={null}
> import ( razorpay "github.com/razorpay/razorpay-go" )
> client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")
>
> params := map[string]interface{}{
>  "razorpay_order_id": "order_IEIaMR65cu6nz3",
>  "razorpay_payment_id": "pay_IH4NVgf4Dreq1l",
> }
>
> signature := "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f";
> secret := "testWebhookSecret1234567";
> utils.VerifyPaymentSignature(params, signature, secret)
> ```

> [accordion] Post Signature Verification
>
> After you have completed the integration, you can [set up webhooks](https://razorpay.com/docs/my/webhooks/setup-edit-payments.md), make test payments, replace the test key with the live key and integrate with other [APIs](https://razorpay.com/docs/my/api).

#### M1 MacBook Changes

If you use M1 MacBook, you need to make the following changes in your podfile.

> [!NOTE]
>
> **Handy Tips**
>
> Add the following code inside `post_install do |installer|`.

```javascript podfile theme={null}
installer.pods_project.build_configurations.each do |config|
  config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
end
```

## 1.8 Verify Payment Status

> [!NOTE]
>
> **Handy Tips**
>
> On the Razorpay Dashboard, ensure that the payment status is `captured`. Refer to the payment capture settings page to know how to [capture payments automatically](https://razorpay.com/docs/my/payments/payments/capture-settings.md).

> [accordion] You can track the payment status in three ways:
>
> > [tab] Verify Status from Dashboard
> >
> > To verify the payment status from the Razorpay Dashboard:
> >
> > 1. Log in to the Razorpay Dashboard and navigate to **Transactions** → **Payments**.
> > 2. Check if a **Payment Id** has been generated and note the status. In case of a successful payment, the status is marked as **Captured**.
> >
> > ![Payment details on Dashboard](https://razorpay.com/docs/build/browser/assets/images/my-testpayment.jpg)
>
> > [tab] Subscribe to Webhook Events
> >
> > You can use Razorpay webhooks to configure and receive notifications when a specific event occurs. When one of these events is triggered, we send an HTTP POST payload in JSON to the webhook's configured URL. Know how to [set up webhooks.](https://razorpay.com/docs/my/webhooks/setup-edit-payments.md)
> >
> > #### Example
> >
> > If you have subscribed to the `order.paid` webhook event, you will receive a notification every time a customer pays you for an order.
>
> > [tab] Poll APIs
> >
> > [Poll Payment APIs](https://razorpay.com/docs/my/api/payments/fetch-all-payments.md) to check the payment status.

## Next Steps

[Step 2: Test Integration](https://razorpay.com/docs/my/payments/payment-gateway/flutter-integration/custom/test-integration.md)
