Documentation
API – Webhooks

Webhooks API Documentation

Introduction

The FinchPay Webhooks API allows you to receive updates on transaction status directly to your application through webhook notifications. By adding a webhook_url to your integration, you can stay informed about changes in transaction status in real-time. This documentation provides details on how to set up and use this API.

Webhook Endpoint

  • Endpoint: POST https://webhook.finchpay.io/transaction_updates

Webhook Request

When a relevant transaction status change occurs, FinchPay sends a POST request to the specified webhook_url. The request body will contain the following information in JSON format:

{
  "id": "c158f7dd-c2a6-49d0-96bf-4f9fd38c0376",
  "status": "COMPLETE", // Possible values: CREATED, RECEIVED, PROCESSING, REFUNDED, SENDING, COMPLETE, ERROR
  "partner_key": "6794e41ed645",
  "amount_from": "100",
  "asset_from": "EUR",
  "asset_from_extra": null, // Possible types: string / null
  "amount_to": "109.58",
  "asset_to": "USDT",
  "asset_network_to": "TRC20",
  "asset_to_extra": null, // Possible types: string / null
  "partner_profit_amount": "2.38",
  "partner_profit_currency": "EUR",
  "event_time": "2023-10-11T10:14:14.491786009Z",
  "external_id": "your_generated_external_id", // Possible types: string / null
  "transaction_hash": "blockchain_tx_hash"
}

Transaction Status

The status field in the webhook request can have one of the following values:

  • CREATED: The transaction has been created.
  • RECEIVED: The transaction has been received.
  • PROCESSING: The transaction is currently being processed.
  • REFUNDED: The transaction has been refunded.
  • SENDING: The transaction is in the process of being sent.
  • COMPLETE: The transaction has been successfully completed.
  • ERROR: An error occurred during the transaction.

Example Webhook Response

Here is an example of a webhook response sent by FinchPay when a transaction status changes to COMPLETE:

{
  "id": "c158f7dd-c2a6-49d0-96bf-4f9fd38c0376",
  "status": "COMPLETE",
  "partner_key": "6794e41ed645",
  "amount_from": "100",
  "amount_to": "109.58",
  "asset_from": "EUR",
  "asset_from_extra": null, // Possible types: string / null
  "asset_to": "USDT",
  "asset_network_to": "TRC20",
  "asset_to_extra": null, // Possible types: string / null
  "partner_profit_amount": "2.38",
  "partner_profit_currency": "EUR",
  "event_time": "2023-10-11T10:14:14.491786009Z",
  "external_id": "your_generated_external_id", // Possible types: string / null
  "transaction_hash": "1f1c70b36ecfaf266bfee6603939e1986529ba9e3056a24b0cf1ddea4171fc70"
}

Handling Webhook Notifications

To make use of the webhook notifications, you should set up an endpoint in your application to receive incoming POST requests from FinchPay. When you receive a notification, you can process the data and take any necessary actions based on the transaction status.

Contact Our Team

If you would like to add a webhook_url to your integration, please don't hesitate to contact our team. We are here to assist you and ensure a smooth setup of webhook notifications.

Conclusion

The FinchPay Webhooks API provides real-time transaction status updates to keep you informed about changes in your transactions. By integrating this API and specifying a webhook_url, you can ensure that you are always up-to-date with the latest information regarding your transactions.

API – Documentation