Transactions

What is a transaction?

A transaction represents a movement of money between your customer and your business. It is the heart of the payment system, where every payment operation is authorized, processed, and recorded.

Note

The following parameters are mandatory or optional depending on the API integration, and parameter requirements vary with widget or checkout integration.

Create a transaction

To create a transaction through your integration via API, you must make a POST request to the /transactions endpoint with the details of the operation you want to process.

Endpoint

POST /v1/transactions

Required Authentication

You must use your private key as a Bearer token in the authentication header:

Authorization: Bearer {your_private_key}

Required parameters

Parameter	Type	Description
acceptance_token	string	Acceptance token obtained from Acceptance Tokens
amount_in_cents	integer	Transaction amount in cents. For example, 10000 = $100 COP
currency	string	Transaction currency. Only COP (Colombian pesos) is currently available.
customer_email	string	Customer email for receipt delivery
payment_method	object	Object with payment method details based on its type
reference	string	Unique reference of the transaction in your system (max 255 characters). Must be unique per transaction
signature	string	Integrity signature to validate the transaction

Optional parameters

Parameter	Type	Description
customer_data	object	Additional customer data (name, phone, address, etc.)
redirect_url	string	URL to redirect the customer after payment
ip	string	IP address of the device from which the transaction is being made

Important

For detailed information on how to generate the integrity signature, check the guide at Widget & Checkout Web - Generate an integrity signature.

Request example - Credit Card

{
  "amount_in_cents": 50000,
  "currency": "COP",
  "customer_email": "juan@example.com",
  "payment_method": {
    "type": "CARD",
    "token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301",
    "installments": 1
  },
  "signature": "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5",
  "payment_method_type": "CARD",
  "reference": "ORDER-2024-001",
  "acceptance_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "ip": "192.168.1.100"
}

Response - Transaction created

A successfully created transaction returns a 201 status code with the following data:

{
  "data": {
    "id": "1292-1602113476-10985",
    "reference": "ORDER-2024-001",
    "created_at": "2024-01-15T14:30:45.000Z",
    "amount_in_cents": 50000,
    "currency": "COP",
    "customer_email": "juan@example.com",
    "payment_method_type": "CARD",
    "status": "PENDING",
    "status_message": "The transaction is being processed",
    "merchant": {
      "id": "pub_prod_xxx",
      "name": "My Business",
      "legal_name": "My Business SAS"
    },
    "payment_method": {
      "type": "CARD",
      "brand": "VISA",
      "last_four": "4242"
    }
  }
}

Transaction statuses

A transaction can have the following statuses:

Status	Description
PENDING	The transaction was created but is still being processed
APPROVED	The transaction was approved and the payment was completed successfully
DECLINED	The transaction was declined (insufficient funds, invalid data, etc.)
VOIDED	The transaction was voided (only applies to credit/debit card transactions)
ERROR	An error occurred during processing

Important

A newly created transaction always has a PENDING status. You must implement polling or use webhooks to verify the final status of the transaction.

Check transaction status

To check the current status of a transaction, use the endpoint:

GET /v1/transactions/{transaction_id}

Status verification

You can verify the status of a transaction at any time using your public key.

Request example

curl -X GET "https://production.wompi.co/v1/transactions/1292-1602113476-10985" \
  -H "Authorization: Bearer pub_prod_xxx"

Response example

{
  "data": {
    "id": "1292-1602113476-10985",
    "reference": "ORDER-2024-001",
    "status": "APPROVED",
    "amount_in_cents": 50000,
    "currency": "COP",
    "payment_method_type": "CARD",
    "status_message": "Transaction approved"
  }
}

Common error codes

Code	Message	Solution
422	Duplicate reference	Use a unique reference for each transaction
422	Invalid amount	Verify that amount_in_cents is a positive integer
400	Invalid acceptance token	Generate a new acceptance token
401	Invalid authentication key	Verify your private key
400	Incomplete payment method	Review the required parameters of payment_method

Important validation

Before sending a transaction to Wompi, make sure to validate all required data on your client and server side. This will prevent validation errors.

Traceability and Security

Importance of capturing the IP address

Storing the IP address of the device from which each transaction originates is fundamental to:

• Fraud identification and prevention: Allows detection of suspicious patterns such as multiple transactions from geographically impossible locations in a short time and facilitates the implementation of anomaly detection rules based on location.
• Traceability: Keep a complete record of the origin of each transaction for auditing.

Security recommendation

Always capture the IP on your backend server. If you use a proxy or load balancer, make sure the X-Forwarded-For header is configured correctly.

Best practices

1. Use unique references

Each transaction must have a unique reference. We recommend using a format that includes your order number and a timestamp:

ORDER-2024-001-1705330245

2. Implement polling

Since no payment method is synchronous, implement polling to check the status:

const checkStatus = async (transactionId) => {
  let attempts = 0;
  const maxAttempts = 60; // 5 minutes with 5-second intervals
  
  const poll = setInterval(async () => {
    const response = await fetch(`/v1/transactions/${transactionId}`, {
      headers: { 'Authorization': `Bearer ${PUBLIC_KEY}` }
    });
    
    const { data } = await response.json();
    
    if (['APPROVED', 'DECLINED', 'VOIDED', 'ERROR'].includes(data.status)) {
      clearInterval(poll);
      console.log('Final status:', data.status);
      return data;
    }
    
    attempts++;
    if (attempts >= maxAttempts) {
      clearInterval(poll);
      console.log('Query timeout');
    }
  }, 5000);
};

3. Store transaction information

Keep a record of transactions in your database with:

• Transaction ID
• Reference
• Status
• Amount
• Payment method
• Device IP address
• Date/time
• And any additional information you consider valuable for your business.

4. Handle errors gracefully

Always validate data before sending the transaction and handle errors appropriately:

try {
  const response = await fetch('/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${PUBLIC_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(transactionData)
  });
  
  if (response.status === 201) {
    const { data } = await response.json();
    // Transaction created successfully
  } else if (response.status === 422) {
    const error = await response.json();
    // Validation failed - invalid data
    console.error('Validation error:', error);
  }
} catch (error) {
  console.error('Network error:', error);
}

Supported payment methods

Wompi supports multiple payment methods. For more detailed information about the specific data for each method, check the complete guide at Payment Methods.

Void a transaction

To void a card transaction (only available for certain statuses), use:

POST /v1/transactions/{transaction_id}/void

Requires your private key.

curl -X POST "https://production.wompi.co/v1/transactions/1292-1602113476-10985/void" \
  -H "Authorization: Bearer priv_prod_xxx"

See also

• Payment Methods
• Acceptance Tokens
• Payment Sources
• API Reference