--- page_title: Loyalty Rewards product: Payment Method Integrations platform: HyperCheckout page_source: https://juspay.io/br/docs/payment-method-integrations/hypercheckout/reward-integration/loyalty-rewards llms_txt: https://juspay.io/br/docs/llms.txt product_llms_txt: https://juspay.io/br/docs/payment-method-integrations/llms.txt --- # Loyalty Rewards Integration ## Adding the PG on Juspay Dashboard * Login to the Juspay Dashboard and open PG Control Centre. Select the `LOYLTYREWARDZ` gateway and enter the gateway credentials to configure the PG. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Screenshot%202024-09-16%20at%207.29.29%20PM.png) * Select `LOYLTYREWARDZ` Reward from Payment Method Configurations ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Screenshot%202024-04-03%20at%207.59.28%20AM-1W4WO.png) > **Note** > For Loyalty Rewardz, `order_id = txn_id` config needs to be disabled as each order would have more than one transaction ## User Flows ### Saved Card Flow When a user selects the option to "Securely save the card for future payments" and successfully completes a transaction on the merchant app, then the card would be available as a pre-saved payment instrument in all future transactions. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(2)-LtVWv.png) *Saved Card Flow | Fetch Balance* ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(3)-i1Mpz.png) *Saved Card Flow | Split Transaction* ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(4)-ULp4M.png) *Saved Card Flow | Full Redemption* ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(5)-LS1WR.png) *No Rewards* ### New Card Flow When a user initiates a transaction on the merchant app with a new (previously unsaved) card. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(6)-lf1Ox.png) *New Card Flow | Eligibility* ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(7)-0phoP.png) *New Card Flow | Fetch Balance* ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(8)-bjzHz.png) *New Card Flow | Split Transaction* ## **Order Status API** The transaction details will be available in the root structure of the orderStatus (`/orders/:order_id`) block. For Loyalty Rewardz integration, merchant needs to handle new order statuses (`AUTO_REFUNDED` and `PARTIAL_CHARGED`) and a new array block `txn_list` in the order status response for the 2 transactions (CARD + LOYLTYREWARDZ). > **Note** > * **AUTO_REFUNDED** > > It indicates that primary card transaction is successful but the `LOYLTYREWARDZ` transaction got failed and JUSPAY has called Auto Refund for primary card transaction. > * **PARTIAL_CHARGED** > > It indicates that primary card transaction is successful but the `LOYLTYREWARDZ` transaction is in PENDING state. ### **Order Status - Sample Request** #### Request CURL Code Snippet: ```request curl curl --location 'https://api.juspay.in/ecr/orders/ \ --header 'Authorization: Basic Auth' --header 'Version: 2024-01-01' ``` ### **Order Status Response: Reward Transaction** #### Sample Response Code Snippet: ```sample response { "customer_email": "amritin@gmail.com", "customer_phone": "7892369201", "customer_id": "cth_7BSdG1PTnKZLBJ9c", "status_id": 21, "status": "CHARGED", "id": "ordeh_4ce8c4ae74fe4d75868422d2001ac1dd", "merchant_id": "udit_juspay", "amount": 10, "currency": "INR", "order_id": "ord_1712290550", "date_created": "2024-04-05T04:15:50Z", "return_url": "https://juspay.in", "product_id": "", "payment_links": { "iframe": "http://localhost:8080/merchant/ipay/ordeh_4ce8c4ae74fe4d75868422d2001ac1dd", "web": "http://localhost:8080/merchant/pay/ordeh_4ce8c4ae74fe4d75868422d2001ac1dd", "mobile": "http://localhost:8080/merchant/pay/ordeh_4ce8c4ae74fe4d75868422d2001ac1dd?mobile=true" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "txn_id": "udit_juspay-ord_1712290550-1", "payment_method_type": "REWARD", "auth_type": "", "payment_method": "LOYLTYREWARDZ", "refunded": false, "amount_refunded": 20, "effective_amount": 10, "refunds": [ { "id": null, "amount": 10, "unique_request_id": "udit_juspay_ord_1712290550_1", "ref": "4598b588-8107-4bac-9ee9-d7530779c8fc", "created": "2024-04-05T05:14:49Z", "status": "SUCCESS", "error_message": "", "sent_to_gateway": true, "initiated_by": "API", "refund_source": "LOYLTYREWARDZ", "refund_type": "STANDARD", "metadata": { "epay_ref_no": "4598b588-8107-4bac-9ee9-d7530779c8fc", "points_expired_amt": 0, "points_refunded_amt": 10 }, "pg_processed_at": "2024-04-05T05:15:01Z", "error_code": null } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozkKMk9CbTSuJv9foG", "txn_detail": { "txn_id": "udit_juspay-ord_1712290550-1", "order_id": "ord_1712290550", "status": "CHARGED", "error_code": null, "net_amount": 10, "surcharge_amount": 0, "tax_amount": 0, "txn_amount": 10, "offer_deduction_amount": null, "gateway_id": 273, "currency": "INR", "express_checkout": false, "redirect": true, "txn_uuid": "mozkKMk9CbTSuJv9foG", "gateway": "LOYLTYREWARDZ", "error_message": "", "created": "2024-04-05T04:15:54Z", "txn_flow_type": "REDIRECT_DEBIT" }, "payment_gateway_response": { "resp_code": "200", "rrn": null, "created": "2024-04-05T04:16:08Z", "epg_txn_id": "854d236f-c9e7-4291-9e01-d1960e79d65f", "resp_message": "", "auth_id_code": null, "txn_id": "udit_juspay-ord_1712290550-1", "gateway_response": { "Code": 200, "Data": { "epay_txn_status": "CONFIRMED", "Refund": [], "epay_id": "854d236f-c9e7-4291-9e01-d1960e79d65f", "epay_txn_id": "37c1c42e-a2ac-48a8-9582-7089c82eed8a", "order_no": "udit_juspay-ord_1712290550-1", "paid_by_points": 10, "invoice_amt": 10 }, "FailureReasons": [], "Message": "", "Success": true }, "network_error_message": null, "network_error_code": null }, "gateway_id": 273, "metadata": { "LOYLTYREWARDZ:gateway_reference_id": "test_ref_2", "payment_links": { "iframe": "http://localhost:8080/merchant/ipay/ordeh_4ce8c4ae74fe4d75868422d2001ac1dd", "web": "http://localhost:8080/merchant/pay/ordeh_4ce8c4ae74fe4d75868422d2001ac1dd", "mobile": "http://localhost:8080/merchant/pay/ordeh_4ce8c4ae74fe4d75868422d2001ac1dd?mobile=true" } }, "gateway_reference_id": "test_ref_2", "offers": [], "maximum_eligible_refund_amount": 0, "additional_info": {}, "resp_category": null } ``` ### **Order Status Response: Card + Reward Transaction** #### Sample Response Code Snippet: ```sample response { "customer_email": "amritin@gmail.com", "customer_phone": "7892369201", "customer_id": "cth_7BSdG1PTnKZLBJ9c", "status_id": 21, "status": "CHARGED", "id": "ordeh_3928cebc762a41baba4c03d1b87e095d", "merchant_id": "udit_juspay", "amount": 10300, "currency": "INR", "order_id": "ord_1712586805", "date_created": "2024-04-08T14:33:25Z", "return_url": "https://juspay.in", "product_id": "", "payment_links": { "iframe": "http://localhost:8080/merchant/ipay/ordeh_3928cebc762a41baba4c03d1b87e095d", "web": "http://localhost:8080/merchant/pay/ordeh_3928cebc762a41baba4c03d1b87e095d", "mobile": "http://localhost:8080/merchant/pay/ordeh_3928cebc762a41baba4c03d1b87e095d?mobile=true" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "refunded": false, "amount_refunded": 0, "effective_amount": 20600, "txn_list": [ { "txn_id": "udit_juspay-ord_1712586805-1-1", "payment_method_type": "CARD", "auth_type": "THREE_DS", "card": { "expiry_year": "2029", "card_reference": "", "saved_to_locker": false, "expiry_month": "02", "name_on_card": "Test", "card_issuer": "HDFC BANK", "last_four_digits": "4343", "using_saved_card": false, "card_fingerprint": "", "card_isin": "435708", "card_type": "DEBIT", "card_brand": "VISA", "using_token": false, "tokens": [], "token_type": "CARD", "card_issuer_country": "INDIA", "juspay_bank_code": "", "extended_card_type": "DEBIT", "payment_account_reference": "" }, "payment_method": "VISA", "refunded": false, "amount_refunded": 0, "effective_amount": 56, "refunds": [ { "id": "udit_juspay_ord_1712586805", "amount": 56, "unique_request_id": "udit_juspay_ord_1712586805", "ref": null, "created": "2024-04-09T12:08:20Z", "status": "PENDING", "error_message": "", "sent_to_gateway": true, "initiated_by": "API", "refund_source": "RAZORPAY", "refund_type": "STANDARD", "error_code": null } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozotSK5bjgHjs1qgSm", "txn_detail": { "txn_id": "udit_juspay-ord_1712586805-1-1", "order_id": "ord_1712586805", "status": "CHARGED", "error_code": null, "net_amount": 10300, "surcharge_amount": 0, "tax_amount": 0, "txn_amount": 56, "offer_deduction_amount": null, "gateway_id": 23, "currency": "INR", "express_checkout": false, "redirect": true, "txn_uuid": "mozotSK5bjgHjs1qgSm", "gateway": "RAZORPAY", "error_message": "", "created": "2024-04-08T14:35:22Z", "txn_flow_type": "CARD_TRANSACTION" }, "payment_gateway_response": { "resp_code": "SUCCESS", "rrn": "776297", "created": "2024-04-08T14:35:55Z", "epg_txn_id": "pay_NwAAnDCmz1smDB", "resp_message": "SUCCESS", "auth_id_code": "776297", "txn_id": "udit_juspay-ord_1712586805-1-1", "gateway_response": { "acquirer_data": "776297", "amount": "5600", "amount_refunded": "0", "auth_code": "776297", "captured": "true", "card_id": "card_NwAAnJwe6B8Wx9", "contact": "+917892369201", "created_at": "1712586946", "currency": "INR", "description": "", "email": "amritin@gmail.com", "entity": "payment", "fee": "118", "id": "pay_NwAAnDCmz1smDB", "international": "false", "method": "card", "notes": "mozotSK5bjgHjs1qgSmudit_juspay-ord_1712586805-1-1", "order_id": "order_NwAAmMjuOX59jn", "status": "captured", "tax": "0" }, "debit_amount": "56.0", "network_error_message": null, "network_error_code": null }, "gateway_id": 23, "gateway_reference_id": "rzp_card", "metadata": { "LOYLTYREWARDZ:gateway_reference_id": "test_ref_2", "payment_links": { "iframe": "http://localhost:8080/merchant/ipay/ordeh_3928cebc762a41baba4c03d1b87e095d", "web": "http://localhost:8080/merchant/pay/ordeh_3928cebc762a41baba4c03d1b87e095d", "mobile": "http://localhost:8080/merchant/pay/ordeh_3928cebc762a41baba4c03d1b87e095d?mobile=true" }, "RAZORPAY:gateway_reference_id": "rzp_card" }, "offers": [], "status": "CHARGED", "resp_category": null }, { "txn_id": "udit_juspay-ord_1712586805-1-2", "payment_method_type": "REWARD", "auth_type": "", "payment_method": "LOYLTYREWARDZ", "refunded": false, "amount_refunded": 0, "effective_amount": 10244, "refunds": [ { "id": null, "amount": 10244, "unique_request_id": "udit_juspay_ord_1712586805-1", "ref": null, "created": "2024-04-09T12:08:20Z", "status": "PENDING", "error_message": "", "sent_to_gateway": true, "initiated_by": "API", "refund_source": "LOYLTYREWARDZ", "refund_type": "STANDARD", "error_code": "ECONNABORTED" } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozkrFWfD7Fqw1xK3Yr", "txn_detail": { "txn_id": "udit_juspay-ord_1712586805-1-2", "order_id": "ord_1712586805", "status": "CHARGED", "error_code": null, "net_amount": 10300, "surcharge_amount": 0, "tax_amount": 0, "txn_amount": 10244, "offer_deduction_amount": null, "gateway_id": 273, "currency": "INR", "express_checkout": false, "redirect": false, "txn_uuid": "mozkrFWfD7Fqw1xK3Yr", "gateway": "LOYLTYREWARDZ", "error_message": "", "created": "2024-04-08T14:35:21Z", "txn_flow_type": "DIRECT_DEBIT" }, "payment_gateway_response": { "resp_code": "", "rrn": null, "created": "2024-04-08T14:36:12Z", "epg_txn_id": "c4f8f3b6-d076-449a-bbc4-968c5ff13ea3", "resp_message": "", "auth_id_code": null, "txn_id": "udit_juspay-ord_1712586805-1-2", "gateway_response": { "Code": 200, "Data": { "epay_id": "c4f8f3b6-d076-449a-bbc4-968c5ff13ea3", "epay_txn_id": "dc9ca99f-039e-4e54-9820-63bbae9fbecd", "paid_by_points": 10244 }, "FailureReasons": [], "Message": "", "Success": true }, "network_error_message": null, "network_error_code": null }, "gateway_id": 273, "gateway_reference_id": "test_ref_2", "metadata": { "LOYLTYREWARDZ:gateway_reference_id": "test_ref_2", "payment_links": { "iframe": "http://localhost:8080/merchant/ipay/ordeh_3928cebc762a41baba4c03d1b87e095d", "web": "http://localhost:8080/merchant/pay/ordeh_3928cebc762a41baba4c03d1b87e095d", "mobile": "http://localhost:8080/merchant/pay/ordeh_3928cebc762a41baba4c03d1b87e095d?mobile=true" }, "RAZORPAY:gateway_reference_id": "rzp_card" }, "offers": [], "status": "CHARGED", "resp_category": null } ] } ``` ## **Refund Handling** Refund requests (full/partial) can be initiated by the merchant at Transaction level or at Order level. Since the `LOYLTYREWARDZ` transactions can be split between an existing Gateway and `LOYLTYREWARDZ`, the merchant can choose between one of the two provisions: * Order based refunds * Merchant will pass `order_id` and `amount` (refund amount) to Juspay. * An order may have 2 transactions (Card and LOYLTYREWARDZ), Juspay will try to prioritise card transaction for refund and if the refund amount is greater than card transaction amount then JUSPAY will initiate refund call to LOYLTYREWARDZ. * In case refund amount is lower than card transaction amount than merchant will receive refund response similar to transaction id based refund response * Refund response will include new key `split_refund_details` * Transaction based refunds * Merchant would initiate refunds against all transaction Ids, with `txn_id` and `amount` for each transaction * Refund response will remain the same as what merchants currently sees for transaction based refunds. No additional handling required. #### **Order Based Refund - Sample Request and Response** #### Sample Request Code Snippet: ```sample request curl --location 'https://api.juspay.in/orders/{order_id}/refunds' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic \ --data-urlencode 'unique_request_id=URI_1696429607' \ --data-urlencode 'amount=950' ``` #### Sample Response Code Snippet: ```sample response { "order_id": "ord_1712586805", "status": "SUCCESS", "amount": 10300, "sent_to_gateway": true, "unique_request_id": "udit_juspay_ord_1712586805", "gateway": "RAZORPAY", "created": "2024-04-09T12:08:20Z", "initiated_by": "API", "split_refund_details": [ { "status": "SUCCESS", "amount": 56, "sent_to_gateway": true, "unique_request_id": "udit_juspay_ord_1712586805", "gateway": "RAZORPAY", "refund_source": "RAZORPAY", "txn_id": "udit_juspay-ord_1712586805-1-1", "reference_id": "udit_juspay_ord_1712586805", "refund_type": "STANDARD" }, { "status": "SUCCESS", "amount": 10244, "sent_to_gateway": true, "unique_request_id": "udit_juspay_ord_1712586805-1", "gateway": "LOYLTYREWARDZ", "refund_source": "LOYLTYREWARDZ", "txn_id": "udit_juspay-ord_1712586805-1-2", "refund_type": "STANDARD" } ], "refund_source": "RAZORPAY", "refund_arn": null, "error_message": null, "epg_txn_id": "7a282d9c-f4a1-4f12-be2c-82147e54d2e0", "txn_id": "udit_juspay-ord_1712586805-1-1", "authorization_id": null, "reference_id": "udit_juspay_ord_1712586805", "response_code": null, "refund_type": "STANDARD" } ``` #### **Transaction Based Refund - Sample Request and Response** #### Sample Request Code Snippet: ```sample request curl --location 'https://api.juspay.in/orders/txns//refunds' \ --header 'Accept: application/json' \ --header 'version: 2022-03-16' \ --header 'x-merchantid:' \ --header 'Authorization: Basic Auth' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'unique_request_id=req-1695671557' \ --data-urlencode 'amount=998' ``` #### Sample Response Code Snippet: ```sample response { "order_id": "ord_1712313308", "status": "SUCCESS", "amount": 10500, "sent_to_gateway": true, "unique_request_id": "refund_1712314361_1", "gateway": "LOYLTYREWARDZ", "created": "2024-04-05T10:52:41Z", "initiated_by": "API", "refund_source": "LOYLTYREWARDZ", "refund_arn": "", "error_message": null, "epg_txn_id": "7a282d9c-f4a1-4f12-be2c-82147e54d2e0", "txn_id": "udit_juspay-ord_1712313308-1-2", "authorization_id": null, "reference_id": null, "response_code": null, "refund_type": "STANDARD" } ``` --- ## See Also - [TWID V2](https://juspay.io/br/docs/payment-method-integrations/hypercheckout/reward-integration/twid-v2) - [CRED Credit Card reward](https://juspay.io/br/docs/payment-method-integrations/hypercheckout/reward-integration/cred-credit-card-reward)