API Reference

Order + Transaction (UPI)

1. UPI Deeplink

Create order and get UPI deeplink as response.

Note

order_fullfillment_threshold_in_mins is in minutes (60 mins in the below example)

Request:

              
                curl --location --request POST 'https://api.juspay.in/orders' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic XXXXX==' \
--data-urlencode 'order_id=orderIdIs125676' \
--data-urlencode 'amount=2' \
--data-urlencode 'customer_id=cth_nfhDAjJf8HmnZ1AK8' \
--data-urlencode 'return_url=' \
--data-urlencode 'description=Sample description' \
--data-urlencode 'options.get_client_auth_token=true' \
--data-urlencode 'metadata.JUSPAY:gateway_reference_id=testmode' \
--data-urlencode 'order_fullfillment_threshold_in_mins=60' \
--data-urlencode 'options_get_upi_deep_links=1'

Response:

              
                {
    "status": "NEW",
    "status_id": 10,
    "id": "ordeh_5d4f1f5d2135453aadd08703297c0c2b",
    "order_id": "orderIdIs67267",
    "payment_links": {
        "iframe": "https://sandbox.juspay.in/orders/ordeh_5d4f1f5d2135453aadd08703297c0c2b/payment-page",
        "web": "https://sandbox.juspay.in/orders/ordeh_5d4f1f5d2135453aadd08703297c0c2b/payment-page",
        "mobile": "https://sandbox.juspay.in/orders/ordeh_5d4f1f5d2135453aadd08703297c0c2b/payment-page"
    },
    "deep_link": "upi://pay?tr=mandate_juspay-orderIdIs67267-1&mc=5816&pa=STAGEONLINE@ybl&pn=Stage&am=2.00&cu=INR",
    "udf9": "",
    "udf8": "",
    "udf7": "",
    "udf6": "",
    "udf5": "",
    "udf4": "",
    "udf3": "",
    "udf2": "",
    "udf10": "",
    "udf1": "",
    "return_url": "",
    "refunded": false,
    "product_id": "",
    "merchant_id": "mandate_juspay",
    "date_created": "2023-12-15T10:54:52Z",
    "customer_phone": "9197079735",
    "customer_id": "cth_nfhDAjJf8HmnZ1AK8",
    "customer_email": "ghge@gmail.com",
    "currency": "INR",
    "amount_refunded": 0,
    "source_object": "",
    "source_object_id": "",
    "amount": 2,
    "juspay": {
        "client_auth_token_expiry": "2023-12-15T11:09:52Z",
        "client_auth_token": "tkn_af91a58f472c419b97ab10fe0f259020"
    },
    "order_expiry": "2023-12-15T11:09:52Z"
}

2. UPI QR

Create order and get UPI QR in base 64 encoded string as response.

Request:

              
                curl --location --request POST 'https://api.juspay.in/orders' \
--header 'Authorization: Basic N0JBRDA4OUExRjYwNEYwREEyNDlCNjY3QTVCMUQzM0Q6' \
--form 'order_id="HD-1707740261"' \
--form 'amount="1"' \
--form 'currency="INR"' \
--form 'customer_id="cth_w2gbGjGi8BUkLgCo"' \
--form 'customer_email="krishna.gprasad@juspay.in"' \
--form 'customer_phone="7093125824"' \
--form 'description="NA"' \
--form 'product_id="5"' \
--form 'return_url="http://www.google.com/"' \
--form 'options.get_client_auth_token="true"' \
--form 'metadata.JUSPAY:gateway_reference_id="testmode"' \
–-form 'udf10="RiderQR"' \
–-form 'order_fullfillment_threshold_in_mins="60"' \
--form 'options.get_upi_qr="true"'

Response:

              
                {
    "status": "NEW",
    "status_id": 10,
    "id": "ordeh_fab5fc85809d45798153a02e4ee8000c",
    "order_id": "HD-1707740261",
    "payment_links": {
        "iframe": "http://localhost:8080/merchant/ipay/ordeh_fab5fc85809d45798153a02e4ee8000c",
        "web": "http://localhost:8080/merchant/pay/ordeh_fab5fc85809d45798153a02e4ee8000c",
        "mobile": "http://localhost:8080/merchant/pay/ordeh_fab5fc85809d45798153a02e4ee8000c?mobile=true"
    },
    "base64_encoded_qr": "qr-image-in-bas64-encoded-for,at",
    "deep_link": "upi://pay?tr=mandate_juspay-orderIdIs67267-1&mc=5816&pa=STAGEONLINE@ybl&pn=Stage&am=2.00&cu=INR",
    "udf9": "",
    "udf8": "",
    "udf7": "",
    "udf6": "",
    "udf5": "",
    "udf4": "",
    "udf3": "",
    "udf2": "",
    "udf10": "RiderQR",
    "udf1": "",
    "return_url": "http://www.google.com/",
    "refunded": false,
    "product_id": "5",
    "merchant_id": "azharamin",
    "date_created": "2024-02-12T07:44:57.150265Z",
    "customer_phone": "7093125824",
    "customer_id": "cth_w2gbGjGi8BUkLgCo",
    "customer_email": "krishna.gprasad@juspay.in",
    "currency": "INR",
    "amount_refunded": 0,
    "source_object": "",
    "source_object_id": "",
    "amount": 1,
    "juspay": {
        "client_auth_token_expiry": "2024-02-12T07:59:57Z",
        "client_auth_token": "tkn_b25bae8cd5cc4f4c9ec28b5a5ffb2db5"
    }
}

FAQs:

1. Is there any expiry time for that QR? If yes, for how much time QR is valid for?

The validity of the QR is primarily decided by the payment gateway. Additionally Juspay fulfillment window will be taken into account.

  • If the transaction becomes successful after fulfillment window, the debited amount will be auto-refunded and status will be marked as AUTO_REFUNDED.

  • There is an option to pass fulfillment window in the order + transaction request so this can be controlled at order ID level.

  • If the fulfillment threshold is not passed in the request then default one configured on Juspay dashboard will be used since they come under the same merchant ID.

  • Within the fulfillment window if the API is called with same order ID again, then Juspay would be sending back the same base 64 QR, fulfillment threshold will not be altered again, it will stay as set in the initial request.

  • If the API is called with the same order ID again post the fulfillment window, then Juspay would be providing just the order status.  

2. If a QR transaction attempt has been made, but abandoned before completion, what will be the transaction status? Pending or Failed?

3. If a QR transaction attempt has been made, but payment couldn't succeed due to incorrect UPI PIN / insufficient balance, can we again scan the same QR and make the payment?

  • Depends, within the fulfilment window the user can attempt multiple times to complete the payment. Anyway multiple PIN submission on UPI apps is controlled at PG level, PG might or might not honor second submission.

4. In what scenarios do we get Failed status?

Last updated 1 month ago