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:
Webhook Payload
{
  "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
string
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 merchant configurations
  • PENDING: The transaction is in progress and awaiting confirmation
  • CREATED: The transaction has been initiated but not yet processed
  • EXPIRED: The transaction has expired due to timeout
​
top_ticket
string
Unique identifier of the transaction
​
top_reference
string
Reference identifier provided by the merchant for the transaction
​
top_amount
integer
Total amount of the transaction
​
top_currency
string
Currency of the transaction (e.g., COP)
​
top_payment_method
string
The payment method used (e.g., RECAUDO)
​
top_bank_name
string
Name of the bank involved in the transaction
​
top_response_message
string
Message describing the transaction’s outcome
​
top_user
object
​
top_user_email
string
Customer email address (repeated for convenience)
​
top_user_phone
string
Customer phone number (repeated for convenience)
​
top_card
object
​
top_extra_params1
string
Additional parameters

​
Webhook Security

Request Headers

The webhook request includes the following headers for validation:

​
Signature Generation

Always validate the webhook signature to ensure that the request is legitimate and comes from Tumipay.
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.
Signature Format
{
    "token": "<client_token>",
    "ticket": "<uuid_of_transaction>",
    "reference": "<transaction_reference>"
}

​
Signature Verification Steps

1

Reconstruct the JSON object

Create a JSON string with your client token and the received transaction details
2

Apply SHA256 algorithm

Generate a signature by hashing the JSON object with SHA256
3

Compare signatures

Compare your generated signature with the one in the x-trx-signature header
4

Validate request

Only process the webhook if the signatures match

​
Handling Webhook Events

Your system should respond to webhook requests with a 200 OK HTTP status code to confirm successful receipt.

​
Retry Schedule

If Tumipay does not receive a successful response, it will retry sending the webhook according to this schedule:

First Retry

5 minutes after the initial attempt

Second Retry

15 minutes after the first retry

Third Retry

30 minutes after the second retry

Fourth Retry

1 hour after the third retry

Fifth Retry

2 hours after the fourth retry
After these attempts, if no successful response is received, the webhook will be marked as failed and no further retries will be made.

​
Example Use Case: Declined vs Rejected

Indicates the transaction was canceled internally by merchant-specific rules, such as:
  • Fraud detection triggers
  • Exceeding transactional limits
  • Additional configurations made by the merchant

​
Example Use Case: Idempotent Processing

To prevent processing the same webhook event multiple times, implement idempotency checks in your webhook handler.
1

Store processed transactions

Store a record of processed transactions using their top_ticket or top_reference as a unique key
2

Check for duplicates

When a webhook is received, check if the top_ticket already exists in your database
3

Handle accordingly

If the transaction exists, skip processing to avoid duplicates. Otherwise, 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.

​
Handling Common Response Messages

Common Rejection Messages

When receiving webhooks, be prepared to handle these common response messages for transactions with “REJECTED” status:
  • “Esta cuenta está inactiva/bloqueada” - Account is inactive/blocked
  • “La cuenta o Nit no corresponden” - Account or tax ID do not match
  • “El número de cuenta no existe” - Account number does not exist
  • “El número de cuenta no es válido” - Account number is invalid
  • “Cuenta no autorizada” - Unauthorized account
  • “El Nit no es válido” - Invalid tax ID
  • “El producto de destino no existe” - Destination product does not exist
  • “Excede el tope saldo de la cuenta destino” - Exceeds destination account balance limit
By following these practices, you can ensure a reliable and secure webhook implementation that effectively handles real-time transaction updates.