FastAPI Wompi API Consumer

This project is a quick proof of concept (POC) FastAPI application for interacting with the Wompi payment API, designed to support MuleSoft development teams.

Overview

This is a rapid POC implementation to help MuleSoft development teams understand and integrate with Wompi's payment APIs. The service provides a simplified interface to Wompi's payment processing capabilities.

Features

• Credit card token creation
• Credit card transaction processing
• Bank listing (PSE and Payouts APIs)
• Merchant bank listing
• Health check endpoint for monitoring

Requirements

• Python 3.8+
• MuleSoft Anypoint Studio 7.x or higher (for integration)
• See requirements.txt for Python dependencies

Setup

Python Service Configuration

1. Clone the repository and navigate to the project folder
2. Install dependencies:

   pip install -r requirements.txt

3. Configure Wompi credentials: Create a .env file in the project root:

   WOMPI_PUBLIC_KEY=your-public-key
   WOMPI_PRIVATE_KEY=your-private-key
   WOMPI_USER_PRINCIPAL_ID=your-user-principal-id
   WOMPI_X_API_KEY=your-x-api-key

4. Start the FastAPI server:

   uvicorn main:app --reload

   API available at http://localhost:8000

Recommended Workflow

1. Token Generation

   graph LR
   A[Client] --> B[Mule API]
   B --> C[FastAPI Service]
   C --> D[Wompi API]
   D --> C
   C --> B
   B --> A
   

   Loading

2. Payment Processing

   graph LR
   A[Client] --> B[Mule API]
   B --> C[Validation]
   C --> D[FastAPI Service]
   D --> E[Wompi API]
   E --> D
   D --> B
   B --> A
   

   Loading

Test Environment

• Use Wompi's sandbox environment for testing
• Test card: 4242 4242 4242 4242
• For successful tests, use "APPROVED" as the card holder name
• See more test data in Wompi documentation

API Endpoints

1. Create Card Token

• POST /wompi/card-token
• Creates a tokenized card for secure payment processing

2. Create Transaction

• POST /transactions/credit-card
• Processes a credit card payment using a token

3. List Banks (PSE)

• GET /wompi/banks
• Lists available banks for PSE payments

4. List Merchant Banks

• GET /wompi/merchants/{merchant_id}/banks
• Lists banks associated with a specific merchant

5. List Payouts Banks

• GET /wompi/payouts/banks
• Lists available banks using Wompi's Payouts API

6. Health Check

• GET /health
• Returns service health status

Usage Examples (cURL)

FastAPI to Wompi (Internal Calls)

1. Token Generation (Wompi API)

# Internal call made by FastAPI to Wompi
curl -X POST https://sandbox.wompi.co/v1/tokens/cards \
  -H "Authorization: Bearer YOUR_PUBLIC_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242 4242 4242 4242",
    "cvc": "123",
    "exp_month": "12",
    "exp_year": "30",
    "card_holder": "APPROVED"
  }'

2. Transaction Processing (Wompi API)

# Internal call made by FastAPI to Wompi
curl -X POST https://sandbox.wompi.co/v1/transactions \
  -H "Authorization: Bearer YOUR_PUBLIC_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_in_cents": 10000,
    "currency": "COP",
    "customer_email": "test@example.com",
    "payment_method": {
      "type": "CARD",
      "token": "tok_test_xxxx_xxxxx",
      "installments": 1
    },
    "reference": "test-ref-001"
  }'

3. PSE Banks Query (Wompi API)

# Internal call made by FastAPI to Wompi to list PSE banks
curl -X GET https://sandbox.wompi.co/v1/pse/financial_institutions \
  -H "Authorization: Bearer YOUR_PUBLIC_KEY_HERE" \
  -H "Content-Type: application/json"

4. Banks Query (Wompi Payouts API)

# Internal call made by FastAPI to Wompi Payouts API
curl -X GET https://api.sandbox.payouts.wompi.co/v1/banks \
  -H "user-principal-id: YOUR_USER_PRINCIPAL_ID" \
  -H "x-api-key: YOUR_X_API_KEY" \
  -H "idempotency-key: unique-idempotency-key" \
  -H "Content-Type: application/json"

# Expected response:
{
  "data": [
    {
      "id": "1", 
      "name": "BANCO DE BOGOTA",
      "financial_institution_code": "001",
      "status": "ACTIVE",
      "type": "BANK",
      "country": "CO",
      "verification_digits": true,
      "created_at": "2025-08-26T...",
      "updated_at": "2025-08-26T..."
    }
  ]
}

5. Merchant Banks Query (Wompi API)

# Internal call made by FastAPI to Wompi to list merchant banks
curl -X GET https://sandbox.wompi.co/v1/merchants/{merchant_id}/payment_sources/banks \
  -H "Authorization: Bearer YOUR_PUBLIC_KEY_HERE" \
  -H "Content-Type: application/json"

# Expected response:
{
  "data": [
    {
      "id": "banco_xxx",
      "name": "Bank Name",
      "type": "BANK",
      "bank_code": "123",
      "status": "ACTIVE",
      "country_code": "CO",
      "bank_account_type": "SAVINGS|CHECKING",
      "created_at": "2025-08-26T...",
      "updated_at": "2025-08-26T..."
    }
  ]
}

Calls to Your FastAPI

1. Generate Card Token

# Step 1: Generate card token
curl -X POST http://localhost:8000/wompi/card-token \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242 4242 4242 4242",
    "cvc": "123",
    "exp_month": "12",
    "exp_year": "30",
    "card_holder": "APPROVED"
  }'

# Expected response:
{
  "data": {
    "id": "tok_test_xxxx_xxxxx",
    "created_at": "2025-08-26T...",
    "brand": "VISA",
    "name": "APPROVED",
    "last_four": "4242",
    "bin": "424242",
    "exp_year": "30",
    "exp_month": "12",
    "card_holder": "APPROVED"
  }
}

2. Process Transaction

# Step 2: Create transaction with token
curl -X POST http://localhost:8000/transactions/credit-card \
  -H "Content-Type: application/json" \
  -d '{
    "amount_in_cents": 10000,
    "currency": "COP",
    "customer_email": "test@example.com",
    "payment_method_type": "CARD",
    "reference": "test-ref-001",
    "token": "tok_test_xxxx_xxxxx",
    "installments": 1
  }'

# Expected response:
{
  "data": {
    "id": "trans_test_xxxx_xxxxx",
    "created_at": "2025-08-26T...",
    "amount_in_cents": 10000,
    "reference": "test-ref-001",
    "currency": "COP",
    "payment_method_type": "CARD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "brand": "VISA",
        "last_four": "4242",
        "exp_year": "30",
        "exp_month": "12"
      }
    },
    "status": "APPROVED",
    "status_message": null
  }
}

3. Query Banks

# List banks for PSE
curl -X GET http://localhost:8000/wompi/banks \
  -H "Content-Type: application/json"

# List banks (Payouts API)
curl -X GET http://localhost:8000/wompi/payouts/banks \
  -H "Content-Type: application/json"

# List banks for a specific merchant
curl -X GET http://localhost:8000/wompi/merchants/12345/banks \
  -H "Content-Type: application/json"

# Expected response:
{
  "data": [
    {
      "financial_institution_code": "1",
      "financial_institution_name": "Test Bank",
      "type": "PSE"
    }
  ]
}

4. Check Service Status

# Health check
curl -X GET http://localhost:8000/health

# Expected response:
{
  "status": "ok"
}

Testing Notes

• All examples use the sandbox environment
• Tokens shown are examples, use your own credentials
• For successful transactions, always use "APPROVED" as card_holder
• Card 4242 4242 4242 4242 will always be approved in sandbox

Implementation Notes

• Endpoints are configured for sandbox environment by default
• This is a quick POC - production implementations should include:
  • Caching for frequently used tokens
  • Appropriate timeouts in HTTP requests
  • Detailed logging for troubleshooting
  • Business-specific metrics
  • Error handling and retry policies
  • Rate limiting and security measures

Best Practices

1. Error Handling

   • Implement retry policies with exponential backoff
   • Handle Wompi-specific errors
   • Detailed error logging

2. Security

   • Validate all inputs
   • Do not store sensitive card data
   • Implement rate limiting
   • Use HTTPS/TLS 1.2+

3. Performance

   • Configure connection pooling
   • Implement caching where appropriate
   • Monitor response times

4. Operations

   • Keep documentation updated
   • Implement CI/CD
   • Proactive monitoring
   • Maintain rollback plans

Troubleshooting

• Check FastAPI application logs
• Use the /health endpoint to validate service status
• Review Wompi-specific error codes
• Validate credential configuration

MuleSoft Integration

This POC is designed to be consumed by MuleSoft applications. The FastAPI service acts as a proxy/wrapper around Wompi's APIs, simplifying integration for MuleSoft development teams.

Integration Pattern

• MuleSoft API → FastAPI Service → Wompi API
• The FastAPI service handles authentication and request formatting
• MuleSoft applications can focus on business logic and orchestration

References

• Wompi API Documentation
• Wompi Payouts API Documentation
• FastAPI Documentation
• MuleSoft Documentation

License

MIT License - See LICENSE file for details