Manual Webhook Setup

Casso allows integration with Webhook API that calls to your server. Every time there is a new transaction, Casso will call to the API you have set up to send this transaction information.

If you need a payment confirmation, use payOS by Casso

payOS is a specialized solution from Casso for payment confirmation, developed through the integration of VietQR technology, Virtual Account Number, and Open Banking API.

Operating Model

Casso uses Webhooks to notify your application when there is a deposit or withdrawal transaction to your bank account.

Integrating Casso into your application via Webhook involves just three simple steps:

Program a Webhook endpoint to handle Webhook events on your server.
Simulate a new transaction from the bank for testing and ensuring that your webhook endpoint runs correctly.
Register URL of Webhook endpoint on Casso and Go live

Before Starting

You have to:

Create an account on Casso
Link a bank account to Casso

Setting up Webhook in Casso

Access Setting > Integration và click Create Integration (+)

In the list of Integration Options, choose Webhook, then open interface of Integrated Webhook:

In the section Bank receiving Webhook :

Choose the bank account that will be monitored to transmit transaction information.
You can choose All so that Casso System will transmit transaction information of all bank accounts you have linked.

In the step of Entering Webhook information:

Parameter Webhook URL will be the path to the Webhook receiver API on your web server.
Parameter Security Key contains a secret code that every time Casso calls the Webhook URL, Casso will attach this security key to the HTTP Header. You can check the header to get the secret code information to authenticate the validity of the call to the Webhook URL.

Do not use Webhook URL is a path only accessible from the internal network or localhost, 127.0.01, 192.160.1.x ... Webhook URL must be a public path on the Internet.

Click on the Test Call button to have the Casso system send a test transaction to the Webhook URL.

If Casso transmits successfully the Webhook URL, your configuration is valid. Now you can click the Save button to save this configuration.

Strict mode: is an advanced result verification step, when the status code returned is 200, Casso will further check in JSON returned either success : 1 or success : true. If it is 0/false, the system will interpret it as a failure, and Casso will resend the Webhook. If the strict mode is not enabled, when receiving a response of status code 200, Casso will consider it as a successful Webhook transmission.

TIP: During the integration programming process, besides the custom Webhook pointing to your website, you can register another custom Webhook using services such as pipedream.com, webhook.site, ngrok.com to debug information Casso send to Webhook URL.

Requirement of Webhook URL

Casso will make an API call to the Webhook URL every time there is a new transaction. The Webhook URL will need to meet the following requirements:

Accessible ability

Must be a public link that is accessible from the internet
The path to use the security protocol HTTPS
If the website uses Cloudfare or DDOS prevention services, note that you must whitelist Casso's IP.

Successful response

After processing, your webhook should respond with a status code of 200 OK and the response time less than 5 seconds ( Casso will set the timeout for request post transmit webhook to 5s)

Handling failure cases

If the webhook transmiting fails for some reason, Casso will repeatedly call the webhook for the next 12 hours, the first call will be after 1 minute, and this timeout will increase to the next Fibonacci value every time the retry failed.

In total, Casso will retry a Webhook event up to 17 times. After that, it will skip and mark the Webhook event as FAIL.

If continuous Webhook calls fail for 24 hours, Casso will change the Webhook configuration to PAUSED status. When the Webhook configuration is paused and new transactions occur, these Webhook events will not be executed but instead will be held with the status of HOLDING. After customers fix the system's Webhook event processing issue, they can access the Casso interface to Replay these Webhook events.

If a Webhook configuration is paused for 7 days without being processed, Casso will change the Webhook configuration to Disabled status. Transactions that occur when the Webhook configuration is disabled will not be able to be replayed.

Anti-duplicate

To counter the attack methods of Replay Attack, Does your webhook need to be de-duplicated by checking if a new transaction has been processed before? Each Casso transaction is identified by an id. With a new webhook coming, check anid whether this transaction has been processed before; if it is, then this transaction has been replayed for some reason, just ignore it.

Post-check processing

Despite being rare, there will always be a chance that the webhook will fail. To avoid the case of missed transactions, Developers might consider providing Full Transaction Tracing by using the API to download transactions and check if there are any missed transactions. See more in Create Auth Cod Manually or OAuth 2

Data structure sent via Webhook

Casso will transmit data into the Webhook URL you declared with JSON format data, where the data field will store an array of new transactions.

{
    "error": 0,
    "data": [
        {
            "id": 6785,        // Mã định danh duy nhất của giao dịch (Casso quy định)
            "tid": "BANK_REF_ID", // Mã giao dịch từ phía ngân hàng
            "description": "giao dich thu nghiem", // Nội dung giao dịch
            "amount": 79000, // Số tiền giao dịch
            "cusum_balance": 20079000,  // Số tiền còn lại sau giao dịch                 
            "when": "2020-10-14 00:34:57",    // Thời gian ghi có giao dịch ở ngân hàng
            "bank_sub_acc_id": "123456789",   // Mã tài khoản ngân hàng mà giao dịch thuộc về
            "subAccId" :  "123456789"       // Tương tự field bank_sub_acc_id, nhằm tương thích với code cũ
            "bankName" : "VPBank", // Tên ngân hàng
            "bankAbbreviation" : "VPB", // Viết tắt tên ngân hàng 
            "virtualAccount": "", // Tài khoản ảo
            "virtualAccountName": "", // Tên tài khoản ảo
            "corresponsiveName": "", // Tên tài khoản đối ứng
            "corresponsiveAccount": "", // Tài khoản đối ứng
            "corresponsiveBankId": "", // Mã ngân hàng đối ứng
            "corresponsiveBankName": "" // Tên ngân hàng đối ứng
        },
    
    ]
}