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", // See all possible values below
  "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",
  "payment_method": "card",
  "side": "buy"
}

Transaction Status

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

  • CREATED: The transaction has been created.
  • PROCESSING: The transaction has been received and is currently being processed.
  • REFUNDED: The transaction has been refunded.
  • SENDING: The transaction is in the process of being sent.
  • HOLD: The transaction is temporary on hold.
  • COMPLETE: The transaction has been successfully completed.
  • ERROR: An error occurred during the transaction.
  • EXPIRED: The transaction has been expired.
  • REJECTED_BY_ANTI_FRAUD: The transaction has been rejected by our anti fraud system.

Payment method

  • card: Credit/debit cards
  • pix: Pix
  • picpay: Picpay
  • boleto: Boleto
  • oxxo: OXXO
  • spei: SPEI
  • dana: DANA
  • ovo: OVO
  • mandiri_va: Mandiri VA
  • bri_va: BRI VA

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",
  "payment_method": "card",
  "side": "buy"
}

Webhook Signature

To ensure security and verify the authenticity of requests, FinchPay adds an x-signature header to each webhook request. This header contains an HMAC-SHA256 signature created using your secret key.

Example of Signature Verification in JavaScript

const crypto = require('crypto');
 
function verifySignature(secret, payload, signature) {
  const hash = crypto.createHmac('sha256', secret)
                     .update(payload)
                     .digest('hex');
  return hash === signature;
}
 
const signature = 'received_signature_from_x-signature_header';
const payload = request.rawBody;
 
if (verifySignature(secret, payload, signature)) {
  console.log('Signature is valid');
} else {
  console.log('Signature is invalid');
}

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