Skip to main content

​
Webhooks

The Webhook feature allows your system to receive real-time updates about the status of transactions. When a transaction status changes, Tumipay sends a POST request to the URL provided in the ipn_url field during the transaction creation.

​
Webhook Payload

The webhook payload is a JSON object containing the following information: 
{
  "top_status": "APPROVED",
  "top_ticket": "49e3c70f-49d2-11ef-a534-02530a7dec0f",
  "top_reference": "ef3bc5cc-1a08-41c8-9e3b-449b95ac5eb6",
  "top_amount": 20000,
  "top_currency": "COP",
  "top_payment_method": "RECAUDO",
  "top_bank_name": "BANCO FALABELLA",
  "top_response_message": "Transacción exitosa",
  "top_user": {
    "legal_doc_type": "CC",
    "legal_doc": "879406421",
    "phone_code": "57",
    "phone_number": "3002134607",
    "email": "[email protected]",
    "full_name": "Jane Johnson"
  },
  "top_card": {
    "bank": "BANCO FALABELLA",
    "bin": "531122",
    "country": "Colombia",
    "lastFourDigits": "1974",
    "type": "credit",
    "brand": "Mastercard"
  },
  "top_user_email": "[email protected]",
  "top_user_phone": "3002134607",
  "top_extra_params1": ""
}
Payload Properties:
  • top_status: The status of the transaction. Possible values:
    • APPROVED: The transaction was successfully completed.
    • REJECTED: The transaction failed during the normal flow (e.g., declined by the bank).
    • DECLINED: The transaction was canceled due to internal rules, such as fraud detection, transactional limits, or additional configurations by the merchant.
    • PENDING: The transaction is in progress and awaiting confirmation.
  • top_ticket: Unique identifier of the transaction.
  • top_reference: Reference identifier provided by the merchant for the transaction.
  • top_amount: Total amount of the transaction.
  • top_currency: Currency of the transaction (e.g., COP).
  • top_payment_method: The payment method used (e.g., RECAUDO).
  • top_bank_name: Name of the bank involved in the transaction.
  • top_response_message: Message describing the transaction’s outcome.
  • top_user: An object containing detailed information about the user/customer:
    • legal_doc_type: Type of the customer legal document (e.g., CC).
    • legal_doc: Customer legal document number.
    • phone_code: Customer country phone code.
    • phone_number: Customer phone number.
    • email: Customer email address.
    • full_name: Customer full name.
  • top_user_email: Customer email address (repeated for convenience).
  • top_user_phone: Customer phone number (repeated for convenience).
  • top_card: An object containing information about the card used in the transaction (if applicable):
    • bank: Name of the issuing bank.
    • bin: Bank Identification Number (first 6 digits of the card).
    • country: Country of issuance.
    • lastFourDigits: Last four digits of the card number.
    • type: Card type (e.g., credit, debit).
    • brand: Card brand (e.g., Visa, Mastercard).
  • top_extra_params1: Additional parameters.
Webhook Headers The webhook request includes the following headers for validation:
  • x-trx-signature: A signature generated based on certain values in the payload.
  • User-Agent: The user agent for the webhook is Tumipay/1.1.
Signature Generation The signature is generated using the SHA256 algorithm by hashing a JSON object that includes the customer token, the transaction ticket, and the transaction reference. Here’s the format: 
sha256('{
    "token": "<client_token>",
    "ticket": "<uuid_of_transaction>",
    "reference": "<transaction_reference>"
}');
Make sure your system validates the signature for security purposes.
Php
function valid_webhook(array $body, string $signature, string $clientToken): bool {
    $message = json_encode([
        'token' => $clientToken,
        'ticket' => $body['top_ticket'],
        'reference' => $body['top_reference'],
    ]);
    $expected = hash('sha256', $message);
    return hash_equals($expected, $signature);
}

​
Handling Webhook Events

Your system should respond to webhook requests with a 200 OK HTTP status code to confirm successful receipt. If Tumipay does not receive this response, it will automatically retry the webhook delivery up to three times. Example Use Case: Declined vs Rejected
  • DECLINED: Indicates the transaction was canceled internally by merchant-specific rules, such as:
    • Fraud detection triggers.
    • Exceeding transactional limits.
    • Additional configurations made by the merchant.
  • REJECTED: Indicates the transaction was declined during the normal transaction process, such as:
    • Insufficient funds.
    • Bank-specific rejections.

​
Example Use Case: Idempotent Processing

To prevent processing the same webhook event multiple times:
  • Store a record of processed transactions using their top_ticket or top_reference as a unique key.
  • When a webhook is received, check if the top_ticket already exists in your database:
    • If it exists, skip processing.
    • If it does not exist, proceed with handling the event and store the record.
By following these practices, you can ensure a reliable and secure webhook implementation that effectively handles real-time transaction updates.