Payments API: Wompi Integration and Webhook Handling

The Payments API connects Zippi orders to the Wompi payment gateway. It provides endpoints for recording manual payments, initiating Wompi hosted-checkout sessions, listing payment transactions, and receiving asynchronous webhook notifications from Wompi. All order-scoped endpoints are mounted under /api/v1/orders and require the orders.financial permission. The webhook endpoint is unauthenticated (public) but is protected by HMAC checksum verification on every request.

Order-scoped payment endpoints (/payment-method, /payments, /wompi/checkout, /payment-transactions) are mounted at /api/v1/orders/{order_id}/.... Only the public webhook is registered at /api/v1/payments/wompi/webhook.

Environment Variables

Variable	Default	Description
`WOMPI_ENV`	`sandbox`	Gateway environment. Set to `production` for live transactions.
`WOMPI_BASE_URL`	`https://sandbox.wompi.co/v1`	Wompi API base URL. Switches to `https://production.wompi.co/v1` in production.
`WOMPI_PUBLIC_KEY`	—	Wompi public key used on the frontend checkout widget.
`WOMPI_PRIVATE_KEY`	—	Wompi private key used for server-side API calls.
`WOMPI_INTEGRITY_SECRET`	—	Secret used to sign checkout integrity tokens.
`WOMPI_EVENTS_SECRET`	—	Secret used to verify incoming webhook event checksums.
`WOMPI_REDIRECT_URL`	`http://localhost:5173/orders`	URL Wompi redirects the customer to after checkout completes.
`WOMPI_WEBHOOK_PUBLIC_URL`	`http://localhost:5000/api/v1/payments/wompi/webhook`	Public URL registered with Wompi as the event callback endpoint.

Permissions

Permission	Description
`orders.financial`	View amounts, collections, and payments on an order; initiate or record payments

Webhook signature verification uses a constant-time string comparison to prevent timing-based attacks. Never replace this with a standard equality check (==). The checksum is passed in the X-Event-Checksum header and must match the HMAC-SHA256 of the raw request body computed with WOMPI_EVENTS_SECRET. Requests with a missing or invalid checksum are silently rejected.

PATCH /api/v1/orders//payment-method

Updates the payment method associated with an order (e.g. switching from cash to wompi before collection). Permission required: orders.financial

Path Parameters

order_id

integer

required

Numeric order ID.

Body

payment_method

string

required

New payment method. Accepted values: cash, wompi, transfer, other.

curl -X PATCH https://api.zippi.co/api/v1/orders/1023/payment-method \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"payment_method": "wompi"}'

Response

success

boolean

Always true on success.

data

object

Updated order payment record with the new payment_method and updated_at timestamp.

POST /api/v1/orders//payments

Records a manual payment entry against an order (cash collection, bank transfer confirmation, etc.). The optional Idempotency-Key header prevents duplicate entries when the request is retried. Returns 201 Created. Permission required: orders.financial

Path Parameters

order_id

integer

required

Numeric order ID.

Headers

Idempotency-Key

string

A unique key (UUID recommended) that makes the operation safe to retry. If a payment with the same key was already recorded, the original response is returned without creating a duplicate.

Body

amount

integer

required

Payment amount in centavos (e.g. 1500000 = $15,000 COP).

method

string

required

Payment method: cash, wompi, transfer, other.

reference

string

External reference number (bank transfer ID, receipt number, etc.).

note

string

Internal note attached to this payment record.

curl -X POST https://api.zippi.co/api/v1/orders/1023/payments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "amount": 1500000,
    "method": "cash",
    "reference": "REC-2024-0042"
  }'

Response

success

boolean

Always true on success.

data

object

Created payment record including payment_id, order_id, amount, method, reference, and created_at.

GET /api/v1/orders//payments

Lists all payment records associated with an order. Permission required: orders.financial

Path Parameters

order_id

integer

required

Numeric order ID.

curl -X GET https://api.zippi.co/api/v1/orders/1023/payments \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Whether the request succeeded.

data

array

Array of payment objects, each with payment_id, amount (centavos), method, reference, and created_at.

POST /api/v1/orders//wompi/checkout

Creates a Wompi hosted-checkout session for an order. Returns the checkout URL and reference that the customer uses to complete payment. Returns 201 Created. Permission required: orders.financial

Path Parameters

order_id

integer

required

Numeric order ID.

Headers

Idempotency-Key

string

Unique key to prevent creating duplicate checkout sessions on retry.

Body

amount_in_cents

integer

required

Amount to charge in centavos. Must match the outstanding balance of the order.

customer_email

string

Customer email address pre-filled in the Wompi checkout widget.

redirect_url

string

Override the default WOMPI_REDIRECT_URL for this specific checkout. Useful for deep links.

curl -X POST https://api.zippi.co/api/v1/orders/1023/wompi/checkout \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c9d8e7f6-a5b4-3210-fedc-ba0987654321" \
  -d '{
    "amount_in_cents": 1500000,
    "customer_email": "cliente@example.com"
  }'

Response

success

boolean

Always true on success.

data

object

Checkout session details.

data.checkout_url

string

The Wompi hosted checkout URL to redirect the customer to.

data.reference

string

Unique Wompi transaction reference for this checkout session.

data.expires_at

string

ISO 8601 timestamp when the session expires.

GET /api/v1/orders//payment-transactions

Returns the list of Wompi transaction records associated with an order. Each record reflects a Wompi gateway event and includes the gateway status, amounts, and timestamps. Permission required: orders.financial

Path Parameters

order_id

integer

required

Numeric order ID.

curl -X GET https://api.zippi.co/api/v1/orders/1023/payment-transactions \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Whether the request succeeded.

data

array

Array of Wompi transaction objects, each including transaction_id, wompi_id, status, amount_in_cents, payment_method_type, and created_at.

POST /api/v1/payments/wompi/webhook

Receives asynchronous event notifications from the Wompi gateway. This endpoint is public (no Authorization header required) and is registered directly with Wompi’s dashboard as the event callback URL. No authentication header required. Security is enforced via HMAC-SHA256 checksum verification using WOMPI_EVENTS_SECRET.

Webhook Security

Every Wompi webhook request includes an X-Event-Checksum header. The service verifies it as follows:

checksum = HMAC-SHA256(key=WOMPI_EVENTS_SECRET, message=<raw_request_body>)

The computed checksum is compared against the header value using constant-time comparison. Requests that fail this check are rejected immediately.

Handled Event Types

Wompi Event	Action Taken
`TRANSACTION.UPDATED`	Updates the Wompi transaction record and, if the transaction status is `APPROVED`, marks the corresponding order payment as settled.

Webhook Payload Structure

event

string

required

Event type identifier, e.g. "TRANSACTION.UPDATED".

data

object

required

Event data envelope.

data.transaction

object

required

Wompi transaction object.

data.transaction.id

string

Wompi-assigned transaction UUID.

data.transaction.reference

string

Your internal order reference used when creating the checkout session.

data.transaction.amount_in_cents

integer

Transaction amount in centavos.

data.transaction.status

string

Gateway status: PENDING, APPROVED, DECLINED, VOIDED, ERROR.

data.transaction.payment_method_type

string

Payment instrument used: CARD, NEQUI, PSE, BANCOLOMBIA_TRANSFER, etc.

sent_at

string

ISO 8601 timestamp when Wompi dispatched the event.

timestamp

integer

Unix epoch of the event.

signature

object

Wompi signature envelope (used for integrity verification alongside X-Event-Checksum).

# Simulating a Wompi webhook in sandbox — compute the checksum locally
SECRET="your_wompi_events_secret"
BODY='{"event":"TRANSACTION.UPDATED","data":{"transaction":{"id":"txn_abc123","reference":"order-1023","amount_in_cents":1500000,"status":"APPROVED","payment_method_type":"NEQUI"}},"sent_at":"2024-01-15T10:30:00.000Z","timestamp":1705314600}'
CHECKSUM=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://api.zippi.co/api/v1/payments/wompi/webhook \
  -H "Content-Type: application/json" \
  -H "X-Event-Checksum: $CHECKSUM" \
  -d "$BODY"

Response

success

boolean

Always true when the event is accepted and processed.

data

object

Processing result, including any state transitions triggered by the event.

Authentication

Marketplace & Customer

Business Portal

Operations

Payments API: Wompi Integration and Webhook Handling

Environment Variables

Permissions

PATCH /api/v1/orders//payment-method

Path Parameters

Body

Response

POST /api/v1/orders//payments

Path Parameters

Headers

Body

Response

GET /api/v1/orders//payments

Path Parameters

Response

POST /api/v1/orders//wompi/checkout

Path Parameters

Headers

Body

Response

GET /api/v1/orders//payment-transactions

Path Parameters

Response

POST /api/v1/payments/wompi/webhook

Webhook Security

Handled Event Types

Webhook Payload Structure

Response

Build docs developers (and LLMs) love

Authentication

Marketplace & Customer

Business Portal

Operations

Documentation Index

​Environment Variables

​Permissions

​PATCH /api/v1/orders//payment-method

​Path Parameters

​Body

​Response

​POST /api/v1/orders//payments

​Path Parameters

​Headers

​Body

​Response

​GET /api/v1/orders//payments

​Path Parameters

​Response

​POST /api/v1/orders//wompi/checkout

​Path Parameters

​Headers

​Body

​Response

​GET /api/v1/orders//payment-transactions

​Path Parameters

​Response

​POST /api/v1/payments/wompi/webhook

​Webhook Security

​Handled Event Types

​Webhook Payload Structure

​Response

Build docs developers (and LLMs) love

Environment Variables

Permissions

PATCH /api/v1/orders//payment-method

Path Parameters

Body

Response

POST /api/v1/orders//payments

Path Parameters

Headers

Body

Response

GET /api/v1/orders//payments

Path Parameters

Response

POST /api/v1/orders//wompi/checkout

Path Parameters

Headers

Body

Response

GET /api/v1/orders//payment-transactions

Path Parameters

Response

POST /api/v1/payments/wompi/webhook

Webhook Security

Handled Event Types

Webhook Payload Structure

Response