Introduction
A Webhook is a functionality to send data to a Webhook URL. It facilitates the transmission of data to the specified Webhook endpoint using HTTP requests.
The Webhook feature facilitates merchants and ISOs to promptly receive notifications about events occurring with their accounts. It should allow the user to configure the Webhook URL.
"Reach out to [email protected] to enable Webhook support on your account."
Webhook – Valid URL
The ISO must provide a valid URL for the webhook. If the merchant provides an incorrect URL, it will be deemed invalid.
Ex: https://vpuat.valorpaytech.com
In ISO, Webhook URL column should accept the valid URL and duplicate URL should also be accepted.
In ISO, Webhook URL column should accept the valid URL and shows pop up as “WEBHOOK URL UPDATED”.
Webhook – Invalid URL
In ISO, Webhook URL column should not accept the invalid URL.
Ex: https://valorpaytech.com/404page
In ISO, Webhook URL column should not accept the invalid URL and shows pop up as “WEBHOOK URL VERIFICATION UPDATED”.
Webhook – Merchant
In ISO Boarding, if a webhook option is enabled in integration, Add Customer full board page and in the settings of webhook option and a webhook option will also display in the merchant login of settings. And it will display as ISO Configured settings.
Webhook – Settings
In Settings, a webhook entity and action are enabled to verify and update the webhook URL and it will get notified to the merchant webhook URL.
The entity is Merchant, User, Devices, Transaction, Recurring, Settlement, Card updater.
The Action are ADD, UPDATE, DELETE, AUTHCAPTURE, AUTHDECLINED, VOIDED, RETURN, APPROVED, FAILED, SUMMARY, DETAIL.
Merchant – Valid URL
In Merchant, Webhook URL column should accept the valid URL and duplicate URL should also be accepted.
In Merchant, Webhook URL column should accept the valid URL and shows pop up as “WEBHOOK URL UPDATED”.
Merchant – Invalid URL
In Merchant, Webhook URL column should not accept the invalid URL.
In Merchant, Webhook URL column should not accept the invalid URL and shows pop up as “WEBHOOK URL VERIFICATION UPDATED”.
Following the webhook events
- Merchant Boarding
- Merchant Delete
- Merchant Status Changed
- Update Merchant Contact Info
- Store Creation
- Store Details Update
- Delete Store Info
- Add device Info
- Update Device Info
- Delete Device Info
- Recurring Creation
- Recurring Update
- Recurring Delete
- Add User Info
- Update User Info
- Delete User Info
- Customer Info add to Vault
- Payment Profile add to Vault
- Update Vault Address Info
- Delete Vault Payment Profile
- Delete Vault Address Info
- Delete Vault Customer Info
- ACH Sale
- ACH Recurring
- ACH Void
- ACH Validation
Event identifier to the Webhooks payload
The client needs to be able to identify the type of data being sent to them without having to parse through
all the key-value pairs. There should be a single source of truth identifier for the data type.
Ex: {‘event’: ‘transaction’, ‘data’: {PAYLOAD}}.
Merchant Boarding
{
"event": "MERCHANT BOARDED",
"data": {
"user_Info": {
"UserId": 185466,
"FirstName": "sdfgvsdfsdfv",
"LastName": "dfbfdgbsdfbdf",
"EmailId": "[email protected]",
"MobileNo": "4254254252",
"ParentId": 8077,
"CustID": 1306,
"Address": "4444444444444",
"city": "Long Island City",
"state": "New York",
"zipcode": "11101"
},
"module_Info": {
"1-User Management": null,
"3-Transactions": null,
"15-Device Management": null,
"17-Engage My Customers": null,
"18-Promotions": null,
"19-Valor Shield RT": null,
"20-Contact Us": null,
"25-My Tickets": null,
"29-Vault": null
},
"merchant_Info": {
"MpId": 160641,
"dbaName": "dfsdfsdfsdfsedf",
"legalName": "button",
"legalAddress": "4444444444444",
"legalCity": "Long Island City",
"legalState": "Alabama",
"legalCountry": "US",
"legalZipCode": "11101",
"legalTimezone": "EST",
"TmsStatus": 0
},
"store_Info": {
"store_info": {
"StoreId": 208389,
"storeName": "dfsdfsdfsdfsedf#2",
"storeAddress": "4444444444444",
"storeCity": "Long Island City",
"storeState": "Alabama",
"storeCountry": "US",
"storeZipCode": "11101",
"storeTimezone": "EST",
"SupervisorName": "sdfgvsdfsdfv dfbfdgbsdfbdf",
"SupervisorContact": "4254254252",
"mcc": "744 - CHAMPAGNE PRODUCER",
"SupervisorEmail": "[email protected]",
"descriptors": null,
Merchant Delete
{
"event": "USER DELETE",
"data": {
"user_id": 186093,
"STATUS": "DELETED"
}
}
Merchant Status Changed
{
"event": "Merchant Status Changed",
"data": [
{
"mp_id": 9565,
"status": "ACTIVE"
}
]
}
Update Merchant Contact Info
{
"event": "MERCHANT CONTACT UPDATED",
"data": {
"first_name": "sarojini",
"last_name": "c",
"email": "[email protected]",
"mobile": "7305632694",
"user_name": "Merchantvt",
"dba_name": "Webhookisooo",
"legal_name": "DharshiniD",
"legal_address": "chennai",
"legal_city": "Pine Bush",
"legal_state": "30",
"legal_zipcode": "12566"
}
}
Store Creation
{
"event": "MERCHANT STORE ADDED",
"data": [
{
"StoreId": 41737,
"dbaName": "testmerchant",
"storeName": "testmerchant",
"storeAddress": "2 Jericho Plazza",
"storeCity": "Jericho",
"storeState": "30",
"storeCountry": "US",
"storeZipCode": "11753",
"SupervisorName": "Kevin Thomas",
"SupervisorContact": "5164696526",
"mcc_code": "4814",
"descriptors": null,
"SupervisorEmail": "[email protected]",
"storeTimezone": "EST",
"storeDBA": "testmerchant"
}
]
}
Store Details Update
{
"event": "MERCHANT STORE UPDATED",
"data": [
{
"StoreId": 9421,
"dbaName": "Rithish",
"storeName": "Jofra Archer",
"storeAddress": "Guindy",
"storeCity": "chennai",
"storeState": "48",
"storeCountry": "US",
"storeZipCode": "11250",
"SupervisorName": "Sahaya rithish",
"SupervisorContact": "9786301808",
"mcc_code": "0763",
"descriptors": "sahaya rithish",
"SupervisorEmail": "[email protected]",
"storeTimezone": "EST",
"storeDBA": "sahaya rithish"
}
]
}
Delete Store Info
{
"event": "MERCHANT STORE DELETED"
"data": {
"storeid": 208317,
"status": "deleted"
}
}
Add device Info
{
"event": "DEVICE ADDED",
"data": {
"store_id": 16675,
"storedetails": {
"epi_Info": {
"epi_details": {
"Mp_Id": 14197,
"epi": "2319928276",
"Device_model": 139,
"Device_name": "Virtual Terminal",
"Label": "VT #2",
"Description": null,
"processor": 6,
"processorInfo": {
"id": 72001,
"midDP": "RCTST00000506388",
"groupIdDP": "40001",
"termNoDP": "00000033",
"websiteDP": "kevin.com",
"EBTcash": 0,
"EBTfood": 0,
"EbtNoDP": "",
"customFeeChecked": 1,
"surchargeIndicator": 0,
"surchargePercentage": "3.500",
"mid_Dp6": "3124123412343124",
"tid_Dp6": "43254256",
"certificateNo": "3456435",
"c_nameDP3": 1,
"vendor": "",
"client_id": "",
"username": "",
"password": "",
"status": ""
},
"Status": "ACTIVE",
"key_group": null
}
}
}
}
}
Update Device Info
{
"event": "DEVICE UPDATED",
"data": {
"store_id": 209541,
"storedetails": {
"epi_Info": {
"epi_details": {
"Mp_Id": 161604,
"epi": "2319972317",
"Device_model": 139,
"Device_name": "Virtual Terminal",
"Label": "VT #1",
"Description": null,
"processor": 1,
"processorInfo": {
"id": 193413,
"mid": "887000003191",
"vNumber": "75021670",
"storeNo": "5999",
"termNo": "1515",
"binnumber": "999991",
"industry": "Retail",
"agentBank": "000000",
"chain": "111111",
"agent": "0001",
"surchargePercentage": "2.000",
"tid3": "611525",
"clientID": "45c4ddcc-feb1-4cb1-99f0-1ba71d6d8f69",
"c_name3": 1
},
"debit_share": "Rithish",
"Status": "ACTIVE",
"key_group": "chrome"
}
}
}
}
}
Delete Device Info
{
"event": "DEVICE DELETED",
"data": {
"store_id": 36724,
"epi_Info": {
"epi_id": "2319926670",
"STATUS": "DELETED"
}
}
}
Recurring Creation
{
"event": "RECURRING ADDED",
"data": {
"actual_amount": "100.00",
"start_date": "09/24/24",
"upcoming_date": "10/24/24",
"created_time": "2024-09-24 11:48:14",
"amount": "105.00",
"number_of_failed_attempt": 0,
"total_number_of_subscription": "6",
"descriptor": null,
"total_number_of_installment": null,
"upcoming_payment": "10/24/24",
"orderdescription": "",
"cardholder_name": "",
"masked_card": "XXXX1111",
"customer_name": "",
"customer_email": "",
"txamount": "0.00",
"phone_number": "() -",
"billing_customername": "Rasheth",
"billing_city": "Minneapolis",
"billing_state": "MN - Minnesota",
"billing_street_name": "Suite",
"billing_street_no": "No 23",
"billing_unit": "",
"billing_zipcode": "55455",
"shipping_customername": "Rasheth",
"shipping_city": "Minneapolis",
"shipping_state": "MN - Minnesota",
"shipping_street_name": "Suite",
"shipping_street_no": "No 23",
"shipping_unit": "",
"shipping_zipcode": "55455",
"charge_until": "6",
"orderId": null,
"recurring_type": 2,
"subscription_id": 21706,
"card_status": 0,
"total_charged_cash": "0",
"last_successful_processed_date": null,
"total_number_of_payments": 0,
"every_day_of_month": 24,
"subscription_status": 1,
"recurring_period": 2,
"payment_type": 1,
"day_in_field": 24,
"company_name": null,
"invoicenumber": null,
"card_type": null,
"card_scheme": null,
"vault_id": null,
"epi": null,
"is_skip": 0,
"is_postpone": 0,
"last_skipped_date": null,
"number_of_skip": 0,
"last_postpone_date": null,
"number_of_postpone": 0,
"last_resume_date": null,
"total_skip": 0,
"total_postpone": 0,
"total_resume": 0,
"remaining_balance": 1,
"additional_input_label1": null,
"additional_input_label2": null,
"additional_input_1": null,
"additional_input_2": null
}
}
Recurring Update
{
"event": "RECURRING UPDATED",
"data": {
"actual_amount": "85.00",
"start_date": "09/24/24",
"upcoming_date": "10/24/24",
"created_time": "2024-09-24 10:29:57",
"amount": "90.78",
"number_of_failed_attempt": 0,
"total_number_of_subscription": "6",
"descriptor": null,
"total_number_of_installment": null,
"upcoming_payment": "10/24/24",
"orderdescription": "",
"cardholder_name": "",
"masked_card": "XXXX1111",
"customer_name": "",
"customer_email": "[email protected]",
"txamount": "90.78",
"phone_number": "(730) 563-2694",
"billing_customername": "dharshini",
"billing_city": "Lorado",
"billing_state": "VA - Virginia",
"billing_street_name": "brooklyn",
"billing_street_no": "52",
"billing_unit": "12",
"billing_zipcode": "25630",
"shipping_customername": "dharshini",
"shipping_city": "Lorado",
"shipping_state": "VA - Virginia",
"shipping_street_name": "brooklyn",
"shipping_street_no": "52",
"shipping_unit": "12",
"shipping_zipcode": "25630",
"charge_until": "6",
"orderId": null,
"recurring_type": 2,
"subscription_id": 21685,
"card_status": 1,
"total_charged_cash": "8500",
"last_successful_processed_date": "2024-09-24",
"total_number_of_payments": 1,
"every_day_of_month": 24,
"subscription_status": 1,
"recurring_period": 2,
"payment_type": 1,
"day_in_field": 24,
"company_name": "",
"invoicenumber": "",
"card_type": "DEBIT",
"card_scheme": "Visa",
"vault_id": 6757,
"epi": "2319925748",
"is_skip": 0,
"is_postpone": 0,
"last_skipped_date": null,
"number_of_skip": 0,
"last_postpone_date": null,
"number_of_postpone": 0,
"last_resume_date": null,
"total_skip": 0,
"total_postpone": 0,
"total_resume": 0,
"remaining_balance": 1,
"additional_input_label1": "",
"additional_input_label2": "",
"additional_input_1": "",
"additional_input_2": ""
}
}
Recurring Delete
{
"event": "RECURRING DEACTIVATED",
"data": [
{
"subscription_id": 21355,
"subscription_status": "RECURRING DEACTIVATED"
}
]
}
Add User Info
{
"event": "USER ADD",
"data": {
"userInfo": {
"basicInfo": {
"UserId": 65467,
"UserType_Id": 5,
"ParentId": 31483,
"FirstName": "Kevin",
"LastName": "Thomas",
"Role_Id": 11,
"MobileNo": "5164696526",
"EmailId": "[email protected]",
"UserType_Desc": "Operator",
"Status": 2,
"Is_Default": 0,
"userName": "kevintestmerchatnotp"
},
"processorDetails": {
"acquirer_id": null
},
"billingType": "",
"selectedfeatures": {
"Allow Refund transaction": null,
"Allow Addcash transaction": null,
"Recurring payment conversion": null,
"Void Transaction": null,
"Refund Transaction": null,
"Open Batch": null
},
"advance_Control": {
"KevinDemoMerchant": {
"EPI: 2319914032": null,
"EPI: 2319914050": null,
"EPI: 2319926344": null,
"EPI: 2319928276": null
}
},
"moduleInfo": {
"3-Transactions": null,
"14-Virtual Terminal": null,
"17-Engage My Customers": null,
"18-Promotions": null,
"20-Contact Us": null,
"25-My Tickets": null,
"29-Vault": null
}
}
}
}
Update User Info
{
"event": "USER UPDATED",
"data": {
"EmailId": "[email protected]",
"MobileNo": "5164696526",
"FirstName": "Kevinopt",
"LastName": "Thomas",
"Address": "",
"zipcode": "",
"State": "",
"city": "",
"userName": "kevinOperator",
"Cust_Name": "Kevin Roc Terminal+"
}
}
Delete User Info
{
"event": "USER DELETE",
"data": {
"user_id": 65467,
"STATUS": "DELETED"
}
}
Customer Info add to Vault
{
"event": "VAULT CUSTOMER CREATED",
"data": {
"customer_details_new": {
"id": 6763,
"merchant_id": 32581,
"customer_name": "Kavitha Saro",
"email": "[email protected]",
"phone": "7305632694",
"company": "ITC Grand chola",
"is_deleted": 0
},
"address_details": [
{
"is_same_address": true,
"address_label": "Home Address",
"billing_customer_name": "Kavitha Saro",
"billing_street_no": "010",
"billing_street_name": "megha",
"billing_unit": "#5",
"billing_zipcode": "12560",
"billing_city": "mount",
"billing_state": "AR - Arkansas",
"shipping_customer_name": "Kavitha Saro",
"shipping_street_no": "010",
"shipping_street_name": "megha",
"shipping_unit": "#5",
"shipping_zipcode": "12560",
"shipping_city": "mount",
"shipping_state": "AR - Arkansas"
}
],
"card_details": [
{
"vault_main_id": 6763,
"masked_pan": "XXXX1111",
"token": "87542BC0C0C01FCFE44C863B7246493CE5CEFA67",
"card_brand": "Visa",
"cardholder_name": "PLATINUM",
"card_type": "D"
}
]
}
}
Payment Profile add to Vault
{
"event": "VAULT CUSTOMER CARD ADDED",
"data": {
"vault_main_id": 3866,
"masked_pan": "XXXX1111",
"token": "BCFBBAB9640783657D9AB8FF0C0EBCCCB30394A5",
"card_brand": "Visa",
"cardholder_name": "ARTAN M",
"card_type": "D"
}
}
Update Vault Address Info
{
"event": "VAULT CUSTOMER ADDRESS UPDATED",
"data": {
"address_id": 0,
"vault_main_id": 6757,
"address_label": "village Address",
"billing_customer_name": "Kavitha Saro",
"billing_street_no": "010",
"billing_street_name": "megha",
"billing_unit": "#5",
"billing_city": "mount",
"billing_state": "AR - Arkansas",
"billing_zip": "12560",
"shipping_customer_name": "gayathri",
"shipping_street_no": "85",
"shipping_street_name": "saint",
"shipping_unit": "118",
"shipping_city": "Spring Dale",
"shipping_state": "",
"shipping_zip": "259865"
}
}
Delete Vault Payment Profile
{
"event": "VAULT CUSTOMER CARD DELETED",
"data": {
"userid": 35589,
"card_id": 7738,
"card_brand": "Discover",
"masked_pan": "XXXX6909"
}
}
Delete Vault Address Info
{
"event": "VAULT CUSTOMER ADDRESS DELETED",
"data": {
"is_same_address": true,
"address_label": "Home Address",
"billing_customer_name": "",
"billing_street_no": "",
"billing_street_name": "",
"billing_unit": "",
"billing_zipcode": "",
"billing_city": "",
"billing_state": "",
"shipping_customer_name": "",
"shipping_street_no": "",
"shipping_street_name": "",
"shipping_unit": "",
"shipping_zipcode": "",
"shipping_city": "",
"shipping_state": ""
}
}
Delete Vault Customer Info
{
"event": "VAULT CUSTOMER DELETED",
"data": {
"vault_id": "6475",
"Status": "DELETED"
}
}
ACH Sale
{
"event": "ACH SALE INTIATED",
"data": {
"uid": "2419297317",
"epi": "2319918526",
"account_number": "XXXX0000",
"routing_number": "XXXX0021",
"payee_name": "dddddddddddddd Authent",
"account_type": "C",
"amount": "104.00",
"state_tax_amount": 4,
"city_tax_amount": 0,
"reduced_tax_amount": 0,
"userid": 36627,
"username": "ACH Merchant",
"base_amount": "100.00"
}
}
ACH Recurring
{
"event": "ACH RECURRING INTIATED",
"data": {
"uid": "2426496152",
"epi": "2319925748",
"account_number": "XXXX0000",
"routing_number": "XXXX0021",
"payee_name": "sales",
"account_type": "C",
"amount": 150.8,
"recurring_type": 1,
"start_from": "2024-09-20",
"number_subscription": 6,
"frequency_type": "4",
"userid": 57154,
"state_tax_amount": 5.8,
"city_tax_amount": 0,
"reduced_tax_amount": 0,
"username": "sarojini c",
"base_amount": 145,
"entry_class": "CCD",
"txn_type": "Debit"
}
}
ACH Void
{
"event": "ACH TRANSACTION VOIDED",
"data": {
"ach_uid": "669fab94634b0",
"epi_id": "2319936916"
}
}
ACH Validation
{
"event": "ACH VERIFICATION INTIATED",
"data": {
"status": true,
"message": "success",
"values": {
"status": true,
"content": {
"VerificationResponse": "Declined",
"AccountResponseCode": "RT00",
"CustomerResponseCode": "",
"bankName": "JPMORGAN CHASE BANK, NA"
}
},
"account_number": "XXXX0056",
"routing_number": "XXXX0021"
}
}
Card Updater
{
"event": "CardUpdater",
"data": {
"subscription_id": "35204",
"card_updater_response": null,
"card_updater_response_code": "0",
"upcoming_payment": "2024-07-30",
"epi": "2319936916",
"masked_card_no_new": "",
"masked_card_no_old": "6222 XXXX XXXX 0026",
"card_holder_name": "",
"card_brand": "CHINA UNION PAY",
"card_type": "CREDIT",
"card_category": "CLASSIC",
"customer_event": "CardUpdater",
"mp_id": "59499"
}
}
Transaction
{
"event": "transactions",
"data": {
"txn_id": 222992644587,
"epi_id": "2319972317",
"device_app_version": " v1.0.2",
"txn_type": "SALE",
"txn_type_code": 101,
"amount": 11429,
"tip_amount": 0,
"cashback_amount": 0,
"custom_fee_amount": 229,
"surcharge_fee_amount": 0,
"merchant_fee_amount": 0,
"tax_amount": 0,
"city_tax_amount": 114,
"state_tax_amount": 457,
"original_amount": 0,
"addtl_amount_2": 0,
"tran_no": 7,
"stan_no": "19429",
"invoice_no": "23",
"batch_no": "6",
"masked_card_no": "7932 XXXX XXXX 3672",
"card_type": "",
"card_scheme": "Unknown",
"mcc": "0744",
"request_date": "2024-09-26",
"request_time": "06:34:43",
"response_date": "2024-09-26",
"response_time": "06:34:43",
"rrn": "427010501416",
"approval_code": " ",
"response_code": "06",
"settled_at": "2024-09-26 10:34:43",
"created_at": "2024-09-26 10:34:43",
"modified_at": "2024-09-26 10:34:44",
"request_recv_at": "2024-09-26 10:34:43",
"response_sent_at": "2024-09-26 10:34:43",
"batches_id": null,
"store_number": "5999",
"agent_bank_number": "000000",
"timezone": "EST",
"refunded_amount": 0,
"reduced_tax_amount": 0,
"food_balance_amount": null,
"food_amount": 0,
"ebt_approval_code": "",
"tip_fee_amount": 0,
"tax_fee_amount": 0
}
}
Batch Summary
{
"event": "batch_summary",
"data": {
"batches_id": 977148,
"epi_id": "2319972317",
"batch_opened_at": "2024-09-26 10:11:04",
"batch_closed_at": "2024-09-26 10:43:59",
"batch_no": 6,
"total_debit_amount": 0,
"total_credit_amount": 488633,
"total_ebt_cash_amount": 0,
"total_ebt_food_amount": 0,
"total_ebt_voucher_amount": 0,
"total_gift_amount": 101900,
"total_other_amount": 0,
"purchase_amount": 478633,
"void_amount": 0,
"refund_amount": 0,
"auth_amount": 10000,
"ebt_cash_amount": 0,
"ebt_food_amount": 0,
"ebt_voucher_amount": 0,
"cash_purchase_amount": 10000,
"cash_refund_amount": 0,
"cashback_amount": 0,
"tip_count": 0,
"tip_amount": 0,
"fee_count": 4,
"fee_amount": 9573,
"surcharge_fee_amount": 0,
"merchant_fee_amount": 0,
"tax_amount": 0,
"city_tax_amount": 4787,
"state_tax_amount": 19145,
"created_at": "2024-09-26 10:43:59",
"modified_at": "2024-09-26 10:43:59",
"cash_withdrawal_amount": 0,
"vpid": 1,
"gift_add_value_amount": 100000,
"gift_sale_amount": 1900,
"gift_tip_amount": 0,
"reduced_tax_amount": 0,
"cash_discount_amount": 0
}
}
Recurring Failed
{
"event": "Recurring Failed",
"data": {
"message": "Recursive Payment of $708.63 is declined for subscription Id #34880, due to following reason Unknown Error",
"epi": "2319936916",
"subscriptionid": "34880",
"transactionamount": "$708.63",
"user_id": "79812"
}
}