Add Money to Brand Wallet

POST/api/pay/v1/add_money

Adds money to a customer's brand wallet. Supports two modes:

GIFT_CARD — Provide gift card number and PIN in payment_option.gift_card_details. Funds credited immediately.
CASH — Provide amount and UPI payment details in payment_option.upi_details. Creates a parent ADD_MONEY order and child CHARGE order for UPI payment.

View as Markdown Open in ChatGPT Open in Claude Open in Perplexity

Requires Bearer token. Get token →

Request Body

Name	Type	Description
`merchant_order_reference`	`string`required	Unique reference for this add-money request
`mode`	`string`required	Mode of adding money: GIFT_CARD — Provide gift card number and PIN. Funds credited immediately. CASH — Provide amount. Creates a UPI payment order. Allowed values: `GIFT_CARDCASH`
`amount`	`object`	Monetary amount with currency.
`value`	`integer`required	Amount in the smallest currency unit (e.g., paisa for INR).
`currency`	`string`required	Three-letter ISO 4217 currency code.
`payment_option`	`object`required	For GIFT_CARD mode: provide `gift_card_details` with `gift_card_number` and `pin`. For CASH mode: provide `upi_details` with UPI Collect or Intent details.
`gift_card_details`	`object`
`upi_details`	`object`	UPI payment details. For COLLECT flow: `txn_mode` = "COLLECT" and `payer.vpa` is required. For INTENT flow (includes QR): `txn_mode` = "INTENT" and no payer needed.
`customer`	`object`required	Customer information.
`email_id`	`string`	Customer's email address.
`first_name`	`string`	Customer's first name.
`last_name`	`string`	Customer's last name.
`customer_id`	`string`	Unique identifier of the customer.
`mobile_number`	`string`	Customer's mobile number.
`country_code`	`string`	Country code of the registered mobile number. Defaults to 91.
`billing_address`	`object`	Physical address.
`shipping_address`	`object`	Physical address.
`is_edit_customer_details_allowed`	`boolean`	Whether the customer is allowed to edit their details.
`merchant_metadata`	`object`	Arbitrary key/value pairs attached to the order

Status Codes

`201`	Money added successfully.
`400`	The request was malformed or missing required fields.
`401`	Authentication failed — missing, expired, or invalid Bearer token.
`422`	Unprocessable entity.
`500`	An unexpected error occurred on the server.

Example:

Request

curl -X POST "https://api.pluralpay.in/api/pay/v1/add_money" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant_order_reference": "ADD-GC-001",
  "mode": "GIFT_CARD",
  "payment_option": {
    "gift_card_details": {
      "gift_card_number": "GC1234567890",
      "pin": "123456"
    }
  },
  "customer": {
    "customer_id": "cust-bw-001"
  }
}'

Run this request

Bearer token

Request body (JSON)

Status:

201 Created

{
  "data": {
    "order_id": "v1-5757575757-aa-hU1rUd",
    "merchant_order_reference": "112345",
    "type": "CHARGE",
    "status": "CREATED",
    "challenge_url": "https://api.pluralpay.in/web/auth/landing/?token=S50xnInJvpcftOzmuGWUqnLpIe694YPGJiKL%2FdBh5Yl%2Bwb8giJrl6HoTvcKljRVZa3H",
    "merchant_id": "123456",
    "order_amount": {
      "value": 50000,
      "currency": "INR"
    },
    "pre_auth": true,
    "part_payment": false,
    "allowed_payment_methods": [
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET",
      "BRAND_WALLET"
    ],
    "notes": "order1",
    "callback_url": "https://sample-callback-url",
    "failure_callback_url": "https://sample-failure-callback-url",
    "purchase_details": {
      "customer": {
        "email_id": "john@example.com",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "123456",
        "mobile_number": "9876543210",
        "country_code": "91",
        "billing_address": {
          "address1": "10 Downing Street Westminster London",
          "address2": "Oxford Street Westminster London",
          "address3": "Baker Street Westminster London",
          "pincode": "51524036",
          "city": "Westminster",
          "state": "Westminster",
          "country": "London",
          "full_name": "Kevin Bob",
          "adddress_type": "Home",
          "address_category": "billing"
        },
        "shipping_address": {
          "address1": "10 Downing Street Westminster London",
          "address2": "Oxford Street Westminster London",
          "address3": "Baker Street Westminster London",
          "pincode": "51524036",
          "city": "Westminster",
          "state": "Westminster",
          "country": "London",
          "full_name": "Kevin Bob",
          "adddress_type": "Home",
          "address_category": "billing"
        },
        "is_edit_customer_details_allowed": false
      },
      "merchant_metadata": {
        "clientId": "DD",
        "transactionReferenceNo": "pine-1223",
        "merchantId": "1234",
        "tid": "9000990",
        "acquirerName": "HDFC_FSS",
        "isOfferDisplayRequired": "true",
        "OfferData": "UHJvZHVjdF9Db2RlPSIgIiZQcm9kdWN0X05hbWU9IiImUGF5bWVudF9Nb2RlPUJhbmsgRU1JJkNhcmRfVHlwZT1EZWJpdCBDYXJkJkJhbmtfTmFtZT1IREZDIERlYml0JkVNSV9UZW51cmU9NiZJbnRlcmVzdF9SYXRlPTkuMCZJbnRlcmVzdF9BbW91bnQ9MTM4MTQwJk1vbnRobHlfSW5zdGFsbG1lbnQ9ODk0NjkwJkF1dGhvcml6YXRpb25fQW1vdW50PTEwMCZMb2FuX2Jvb2tpbmdfQW1vdW50PTUyMzAwMDAmSW50ZXJlc3RfQ2FzaGJhY2tfQW1vdW50PTAmSW50ZXJlc3RfQ2FzaGJhY2tfVHlwZT1EZWZlcnJlZCZBZGRpdGlvbmFsX0Nhc2hiYWNrPSIiJkFkZGl0aW9uYWxfQ2FzaGJhY2tfVHlwZT0iIiZEZXNjcmlwdGlvbj1CYW5rIEVNSSZQcm9kdWN0X1ZhbHVlPTUyMzAwMDA",
        "tenant_id": "PGATPOS",
        "is_offer_validation_required": "true"
      },
      "split_info": {
        "split_type": "AMOUNT",
        "split_details": [
          {
            "split_merchant_id": "1324",
            "split_settlement_id": "v1-241118074845-aa-wduUQF-ss-b",
            "merchant_settlement_reference": "kshjhfk",
            "amount": {
              "value": 50000,
              "currency": "INR"
            },
            "on_hold": true,
            "status": "HOLD",
            "updated_at": "2024-11-18T07:48:45.324Z"
          }
        ]
      },
      "cart_details": {
        "cart_items": [
          {
            "item_id": "9876",
            "item_name": "T Shirt",
            "item_description": "Shopping on Diwali Sale",
            "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
            "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
            "item_original_unit_price": 199,
            "item_discounted_unit_price": 149,
            "item_quantity": 2,
            "item_currency": "INR"
          }
        ]
      }
    },
    "payments": [
      {
        "id": "v1-5206071124-aa-mpLhF3-cc-l",
        "merchant_payment_reference": "pay-ref-001",
        "status": "PENDING",
        "payment_amount": {
          "value": 50000,
          "currency": "INR"
        },
        "base_amount": {
          "value": 50000,
          "currency": "INR"
        },
        "conversion_rate": 0.0123,
        "payment_method": "CARD",
        "payment_option": {
          "card_data": {
            "card_type": "CREDIT",
            "network_name": "VISA",
            "issuer_name": "HDFC",
            "product_name": "Visa Platinum",
            "card_category": "CONSUMER",
            "country_code": "IND",
            "token_txn_type": "ALT_TOKEN",
            "last4_digit": "1091",
            "save": false,
            "is_native_otp_eligible": true
          },
          "upi_details": {
            "txn_mode": "COLLECT",
            "payer": {
              "vpa": "kevinbob@okaxis"
            }
          },
          "netbanking_details": {
            "pay_code": "NB1531",
            "txn_mode": "REDIRECT"
          },
          "wallet_details": {
            "wallet_name": "PAYTM"
          },
          "bnpl_details": {
            "mobile": "9876543210",
            "bnpl_pay_code": "LAZYPAY"
          },
          "points_card_details": {
            "card_last4": "1234",
            "points_redeemed": "500"
          },
          "cardless_details": {
            "pan_number": "ABCDE****F",
            "registered_mobile_number": "9876543210"
          }
        },
        "acquirer_data": {
          "approval_code": "030376",
          "acquirer_reference": "202455840588334",
          "rrn": "419335023601",
          "is_aggregator": true
        },
        "offer_data": {
          "offer_details": {
            "tenure": {
              "issuer_offer_parameters": [],
              "details": [
                {
                  "product_offer_parameters": [],
                  "subvention": {
                    "breakup": {
                      "brand": {}
                    }
                  }
                }
              ]
            }
          }
        },
        "error_detail": {
          "code": "PAYMENT_DECLINED",
          "message": "Transaction declined due to insufficient balance"
        },
        "capture_data": [
          {
            "merchant_capture_reference": "f31d8c60-0dc8-4788-a577-5ced930cc175",
            "capture_amount": {
              "value": 50000,
              "currency": "INR"
            },
            "created_at": "2024-07-19T11:13:21.523516426Z"
          }
        ],
        "created_at": "2024-09-11T08:07:55.647Z",
        "updated_at": "2024-09-11T08:07:57.115Z"
      }
    ],
    "created_at": "2024-07-09T07:57:08.022Z",
    "updated_at": "2024-07-09T07:57:08.022Z",
    "integration_mode": "SEAMLESS",
    "image_url": "https://api.pluralpay.in/qr/image/v1-order-id",
    "payment_retries_remaining": 10,
    "is_mcc_transaction": false,
    "is_domestic_txn_for_risk_enabled": false,
    "order_token": "mzohdLMNCzZ2SN3k1Ppglkz4mmk9edyahe34BM%2Fu9gA%3D",
    "cross_border_details": {
      "flow_type": "NON_LRS",
      "purpose_code": "S0101",
      "commodity_type": "SERVICES",
      "requires_pan": true,
      "payer_data": {
        "first_name": "Rajesh",
        "last_name": "Patel",
        "email": "rajesh@techcorp.com",
        "phone": "9876543210",
        "country_code": "91",
        "pan": "KGEPS1880J",
        "dob": "1999-04-14",
        "name_on_pan": "TechCorp Private Limited",
        "address_line_1": "10 Downing Street Westminster London",
        "address_line_2": "Oxford Street Westminster London",
        "country": "IN",
        "is_tcs_declared": true
      }
    }
  }
}