-
Getting started
keyboard_arrow_down
Connect to the CCV Platform
Integrate our products into your software. Let's make payment happen together!
Look at all the possibilities
Integrate our products into your software. Let's make payment happen together!
Look at all the possibilitiesA webhook is a callback mechanism to inform you of changes occurring to your transaction in our system. We accomplish this by making an HTTP call to an endpoint in your system when these changes occur. The webhook only contains our transaction reference. The merchant system should make a status call to retrieve the transaction status.
We call your webhook when the transaction changes status or requires immediate attention. These status changes can be triggered by, for instance, successful or failed completion of the payment, a time out, fraud detection, and so on.
When you receive the webhook, we strongly recommend that you query the transaction and inspect the status before making any decisions.
We can not guarantee that we, the PSP, called the webhook. It is possible an attacker accessed the URL. For that reason we insist that you request the status of the payment once you have received the webhook.
If you require identification of the caller, you can use notifications as an alternative.
Due to security restrictions, we only support secure URLs (https://). If you are technically not able to provide this, contact us.
For a more secure internet, you can look at services like Let's Encrypt that provide you free certificates issued by a free and trusted Certificate Authority!
POSTapplication/json| Name | Description |
|---|---|
| id | The unique reference of the transaction |
Example
{
"id" : "AC130090D6C19A09CD4B8B3EECCE199AD895B6E0"
}
The webhook request does not contain any additional information. We expect the merchant system to query the transaction to retrieve the transaction status. It ensures that we will not disclose (possible) sensitive data to an attacker.
If you need more information in the webhook, you can define a webhook URL per transaction and add additional data in the URL.
We’re using HTTP/2, where sending the Content-Length header is optional. Ensure your system can handle requests without relying on this header.
We expect an HTTP 2xx Success code and ignore any content in the response body. If you do not return a 2xx code, we will retry the webhook request.
We will keep trying the webhook 10 times until we get an HTTP response code 2xx, which would indicate success at your end. Any other HTTP status code is a failure resulting in a retry.
Retrying will be done in increasing intervals until it reaches the final time out, after which we will no longer try to call the webhook for this status change. Should the transaction change state again, we will retry until the final time out is reached.
It is strongly recommended to answer the webhook with a 2xx HTTP status code as fast as possible. We recommend that you do not perform any heavy processing in your webhook handler synchronously. Our system only sends a limited amount of parallel webhooks to your system. If you block your webhook handler by doing some processing, you might miss other webhooks. Instead, we suggest to use a queue system to process the webhook asynchronously and to answer the webhook immediately after receiving it.
The Merchant Backoffice can configure a global Webhook URL. We support one URL per merchant. We will send all status changes to this URL.
We support the overriding of the global configuration by specifying a different webhook URL in the payment, refund, or token request. If the request specifies this URL, we will call this URL instead.
It is useful when you include additional parameters per webhook, for example, the merchant order reference.
For example, it would result in a webhook URL like https://shop/webhook?order=123456&foo=bar
CCV does not follow redirects. If you responds with a HTTP code that is less than 200 or greater than 299, CCV will retry the webhook.
CCV does not send webhooks to localhost. A webhook must be a public endpoint that CCV can access.
CCV does not send webhooks to insecure endpoints. See Security for more information