Skip to content

Latest commit

 

History

History
375 lines (316 loc) · 9.18 KB

README.md

File metadata and controls

375 lines (316 loc) · 9.18 KB

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

License

MIT License - See LICENSE file for details