API Webhooks

A webhook is a callback that UnDosTres API uses to send notifications regarding your merchant events/actions. For secutiry, payload will be always encrypted using AES-128-ECB algorithm and the secret key will be shared only between involved parts.

Setting up your Webhook URLs:

To set up your Webhook URLs please see Update your account data

Parameters to take into account:

• ✅ main_url : Mandatory webhook url where high priority notifications are sent.
• ✅ second_url: Secondary webhook url where medium priority notifications are sent (this one is optional).
• ✅ extra_url: Additional webhook url where less priority notifications could be sent (this one is optional).
• ✅ working_time_only: If enabled, notifications will be scheduled to be sent only in working time (Monday to Friday between 8:00am - 5:00pm only).

Webhook core payload

JSON

{
	  "event_type": "ACCOUNT", /* API Event Type */
	  "event_type_description": "EMAIL_UPDATED", /* Event Sub-Type description */
	  "webhook_notification_code": 1001, /* Webhook notification event code */
	  "created_at": "2024-05-15 12:34:56", /* The timestamp when the event was created */
	  "first_sent_at": "2024-05-15 12:40:00", /* The timestamp of first attempt to send the event */
	  "attempts": 1, /* Attempts made by the webhook */
	  "account_id": 321, /* Account ID related with the event sent */
	  "customer_id": 345, /* Customer ID related with the event, if exist. */
	  "transaction_id": "trx_ehe77r6t8et5", /* If exist, external transaction ID related with the event. */
    "request_id": 12343, /* If exist, our internal request ID related with the event. */
	  "details": {
		    "id": 321, /* Object Instance ID of the API resource created/updated */
		    "code": "", /* Object Code ID of the API resource created/updated */
        "name": "", /* Object Name of the API resource created/updated */
        "amount": "", /* Amount related with the API resource created/updated */
		    "status": "success", /* The status of the action */
		    "failed_reason": "", /* If status=failed, a failure code */
		    "failed_message": "" /* If status=failed, a description of the failure */
	  },
    "metadata": null /*Json object with data related to the specific event type */
}

Webhook List

For information about specific payloads for a given API event type and webhook notification code, just click on the corresponding Webhook Code in the table below.

Event Type	Event Sub Type	Code	scheduled to be sent whenever...	Up
ACCOUNT	ACCOUNT_CREATED	1000	an account is created.
ACCOUNT	ACCOUNT_UPDATED	1100	an account is updated.	✅
ACCOUNT	ACCOUNT_CANCELLED	1101	an account is cancelled.
ACCOUNT	ACCOUNT_FAILED	1005	an account failed on being created, updated or cancelled.	✅
ACCOUNT	EMAIL_UPDATED	1001	the account email is changed/replaced.
ACCOUNT	MOBILE_UPDATED	1002	the account mobile is changed/replaced.
ACCOUNT	SECRET_KEY_CREATED	1010	initial Secret API Key is created (by the first time only).	✅
ACCOUNT	SECRET_KEY_UPDATED	1011	a new Secret API Key is created and old one is scheduled to expire (second time and so on).	✅
ACCOUNT	SECRET_KEY_WARNING	1012	a Secret API Key is near to expire (1, 3 and 7 days before expire).	✅
ACCOUNT	CREDENTIAL_UPDATED	1013	new account credentials are created.
ACCOUNT	CREDENTIAL_WARNING	1014	account credentials are expired (1, 3 and 5 days after expired).	✅
ACCOUNT	UNAUTHORIZED_ACTION	1015	an unauthorized action is requested (account behalf).	✅
ACCOUNT	SUB_ACCOUNT_CREATED	1200	a sub-account is created.	✅
ACCOUNT	SUB_ACCOUNT_UPDATED	1300	a sub-account is updated.
ACCOUNT	SUB_ACCOUNT_CANCELLED	1301	a sub-account is cancelled.
ACCOUNT	SUB_ACCOUNT_FAILED	1205	a sub-account failed on being created, updated or cancelled.
ACCOUNT	SA_EMAIL_UPDATED	1201	Sub-Account email is changed/replaced.
ACCOUNT	SA_MOBILE_UPDATED	1202	Sub-Account mobile is changed/replaced.
ACCOUNT	SA_SECRET_KEY_CREATED	1210	Sub-Account initial Secret API Key is created (first time only).
ACCOUNT	SA_SECRET_KEY_UPDATED	1211	a new Secret API Key is created and old one is scheduled to expire (second time and so on).
ACCOUNT	SA_SECRET_KEY_WARNING	1212	Sub-Account Secret API Key is near to expire (1, 3 and 7 days before expire)
ACCOUNT	SA_CREDENTIAL_UPDATED	1213	new sub-account credentials are created.
ACCOUNT	SA_CREDENTIAL_WARNING	1214	sub-account credentials are expired (1, 3 and 5 days after expired)
ACCOUNT	SA_UNAUTHORIZED_ACTION	1215	an unauthorized action is requested (sub-account behalf).
ACCOUNT	SPEI_REFERENCE_CREATED	1030	account SPEI reference is created.	✅
ACCOUNT	SPEI_WEBHOOK_ACCEPTED	1031	a success SPEI webhook is received (accepted).	✅
ACCOUNT	SPEI_WEBHOOK_CANCELLED	1032	a previous success SPEI webhook is requested to be cancelled.
ACCOUNT	SPEI_WEBHOOK_REJECTED	1033	a failed SPEI webhook is received (rejected).	✅
ACCOUNT	SPEI_WEBHOOK_REFUNDED	1034	a SPEI transaction refund webhook is received (REFUND)
ACCOUNT	SPEI_ACCOUNT_CASH_OUT_CREATED	1060	account spei cashout successfully created	✅
ACCOUNT	SPEI_ACCOUNT_CASH_OUT_FAILED	1065	an account SPEI cash out failed on being created.	✅
ACCOUNT	SPEI_ACCOUNT_CASH_OUT_SUCCESS	1061	an account SPEI cash out is successfully executed.	✅
ACCOUNT	SPEI_ACCOUNT_CASH_OUT_CANCELLED	1062	Spei cashout cancelled by bank or system	✅
ACCOUNT	SPEI_ACCOUNT_CASH_OUT_REJECTED	1063	Spei cashout rejected by bank or system	✅
ACCOUNT	SPEI_ACCOUNT_CASH_OUT_DECLINED	1064	Spei cashout declined by bank or system	✅
ACCOUNT	CASH_REFERENCE_CREATED	1040	account CASH reference is created	✅
ACCOUNT	CASH_WEBHOOK_ACCEPTED	1041	a success CASH webhook is received (accepted).	✅
ACCOUNT	CASH_WEBHOOK_CANCELLED	1042	a previous success CASH webhook is requested to be cancelled.	✅
ACCOUNT	CASH_WEBHOOK_REJECTED	1043	a failed CASH webhook is received (rejected).	✅
ACCOUNT	CODI_WEBHOOK_ACCEPTED	1051	a success CODI webhook is received (accepted).
ACCOUNT	CODI_WEBHOOK_REJECTED	1053	a failed CODI webhook is received (rejected).
CUSTOMER	CUSTOMER_CREATED	2000	a customer is created.	✅
CUSTOMER	CUSTOMER_UPDATED	2100	a customer is updated.	✅
CUSTOMER	CUSTOMER_ENABLED	2101	a customer is enabled.	✅
CUSTOMER	CUSTOMER_DISABLED	2102	a customer is disabled.	✅
CUSTOMER	CUSTOMER_FAILED	2002	a customer failed on being created, updated or enabled/disabled.	✅
PAYMENT_METHOD_CARD	PAYMENT_METHOD_CREATED	3000	a card payment method is created.
PAYMENT_METHOD_CARD	PAYMENT_METHOD_UPDATED	3100	a card payment method is updated.
PAYMENT_METHOD_CARD	PAYMENT_METHOD_DELETED	3101	a card payment method is deleted.
PAYMENT_METHOD_CARD	PAYMENT_METHOD_USED	3300	a card payment method is used (a charge was requested).
PAYMENT_METHOD_CARD	PAYMENT_METHOD_FAILED	3002	a card payment method failed on being created, updated or deleted
PAYMENT_METHOD_DMCL	PAYMENT_METHOD_CREATED	4000	a domiciled payment method is created.
PAYMENT_METHOD_DMCL	PAYMENT_METHOD_UPDATED	4100	a domiciled payment method is updated.
PAYMENT_METHOD_DMCL	PAYMENT_METHOD_DELETED	4101	a domiciled payment method is deleted.
PAYMENT_METHOD_DMCL	PAYMENT_METHOD_USED	4300	a domiciled payment method is used (a charge was requested).
PAYMENT_METHOD_DMCL	PAYMENT_METHOD_FAILED	4002	a domiciled payment method failed on being created, updated or deleted.
PAYMENT_METHOD_DMCL	BANK_INSTITUTION_ADDED	4305	a new BANK INSTITUTION is added.
PAYMENT_METHOD_DMCL	BANK_INSTITUTION_UPDATED	4105	any existing BANK INSTITUTION is updated.
PAYMENT_REQUEST_CARD	CARD_REQUEST_CREATED	5000	a card payment request is created.
PAYMENT_REQUEST_CARD	CARD_REQUEST_UPDATED	5100	a card payment request is updated.
PAYMENT_REQUEST_CARD	CARD_REQUEST_CANCELLED	5101	a card payment request is cancelled.
PAYMENT_REQUEST_CARD	CARD_REQUEST_FAILED	5002	a card payment request failed on being created, updated, cancelled or we have confirmation from providers that payment attempt was rejected.
PAYMENT_REQUEST_CARD	CARD_REQUEST_SUCCESS	5001	we got confirmation from providers that payment attempt was success.
PAYMENT_REQUEST_CARD	CARD_REQUEST_CHARGEBACK	5005	we got confirmation from providers that chargeback has been made by your customer.
PAYMENT_REQUEST_DMCL	DMCL_REQUEST_CREATED	6000	a domiciled payment request is created.
PAYMENT_REQUEST_DMCL	DMCL_REQUEST_UPDATED	6100	a domiciled payment request is updated.
PAYMENT_REQUEST_DMCL	DMCL_REQUEST_CANCELLED	6101	a domiciled payment request is cancelled.
PAYMENT_REQUEST_DMCL	DMCL_REQUEST_FAILED	6002	a domiciled payment request failed on being created, updated, cancelled or we have confirmation from providers that payment attempt was rejected.
PAYMENT_REQUEST_DMCL	DMCL_REQUEST_SUCCESS	6001	we got confirmation from providers that payment attempt was success.
PAYMENT_REQUEST_DMCL	DMCL_REQUEST_CHARGEBACK	6005	we got confirmation from providers that chargeback has been made by your customer.
PAYMENT_REQUEST_CASHIN	CASHIN_REFERENCE_CREATED	7000	a cash-in reference is created.	✅
PAYMENT_REQUEST_CASHIN	CASHIN_REFERENCE_COMPLETED	7001	we got confirmation from providers that payment attempt was success.	✅
PAYMENT_REQUEST_CASHIN	CASHIN_REFERENCE_CANCELED	7002	a cash-in reference is cancelled.	✅
PAYMENT_REQUEST_CASHIN	CASHIN_REQUEST_FAILED	7003	a cash-in reference is failed on being created.	✅
PAYMENT_REQUEST_CASHIN	CASHIN_REFERENCE_EXPIRED	7004	a cash-in reference is expired without payment	✅
PAYMENT_REQUEST_CASHOUT	CASHOUT_REFERENCE_CREATED	8000	a cash-out reference is created.	✅
PAYMENT_REQUEST_CASHOUT	CASHOUT_REFERENCE_COMPLETED	8001	we got confirmation from providers that reference was fulfilled successfully.	✅
PAYMENT_REQUEST_CASHOUT	CASHOUT_REFERENCE_CANCELED	8002	a cash-out reference is cancelled.	✅
PAYMENT_REQUEST_CASHOUT	CASHOUT_REQUEST_FAILED	8003	a cash-out reference is failed on being created.	✅
PAYMENT_REQUEST_CASHOUT	CASHOUT_REFERENCE_EXPIRED	8004	a cash-out reference is expired.	✅
CHECKOUT_ORDERS	CHECKOUT_ORDER_CREATED	9000	a checkout order is created.	✅
CHECKOUT_ORDERS	CHECKOUT_ORDER_COMPLETED	9001	Confirmation that payment attempt was success.	✅
CHECKOUT_ORDERS	CHECKOUT_ORDER_FAILED	9103	a checkout order failed on being created.	✅
CHECKOUT_ORDERS	CHECKOUT_ORDER_PAYMENT_FAILED	9004	a checkout created order failed the payment attempt.	✅

Webhook to use by code format

• high priority notifications, last 3 digits of the webhook notification code are in the range [000 - 099]. Examples: 1001, 2050, 3030, X010. This group is expected to be sent to the main webhook url (i.e. the one provided in main_url parameter).
• medium priority notifications, last 3 digits of the webhook notification code are in the range [100 - 299]. Examples: 1100, 2150, 3200, X210. This group is expected to be sent to the secondary webhook url (i.e. the one provided in second_url parameter).
• less priority notifications, last 3 digits of the webhook notification code are in the range [300 - 599]. Examples: 1501, 2350, 3333, X310. This group is expected to be sent to the additional webhook url (i.e. the one provided in extra_url parameter).

Retry policy

If your system does not returns us 2XX status code, we automatically tries to send the webhook notification again. This retry process will be scheduled to happen depending of the retry logic configured for each of your webhook url. We currently manage following retry logic options:

1. Continue retry; if the first attempt fails, our system will try again and will continue this pattern until it either receives a successful response or reaches the maximum allowed retries.
2. Retry after 5 minute; if the first attempt fails, our system waits for 1 minute before trying again and will continue this pattern until it either receives a successful response or reaches the maximum allowed retries.
3. Retry after 15 minute; if the first attempt fails, our system waits for 10 minutes before trying again and will continue this pattern until it either receives a successful response or reaches the maximum allowed retries.

This logic may be affected if your webhook is configured to receive notifications in working time only (Monday to Friday between 8:00am-5:00pm only).