Create Transaction

POST /api/transactions

Creates a new currency exchange transaction for the authenticated user. The endpoint automatically calculates commissions based on the transaction amount and validates the exchange rate against the current market rate with a tolerance of 0.35 Bs.

Authentication

This endpoint requires authentication. Include a valid JWT token in the Authorization header:

Authorization: Bearer <your_token>

Request Body

transaction_type

string

required

The type of transaction. Must be either "Comprar" (Buy) or "Vender" (Sell).

Comprar: User buys USD, commission is added to the amount
Vender: User sells USD, commission is deducted from the amount

amount_usd

number

required

The base amount in USD for the transaction. Must be a positive number.The commission is automatically calculated based on this amount:

$1 -$ 9.99: $0.80 commission
$10 -$ 14.99: $1.00 commission
$15 -$ 25: $1.40 commission
Above $25:$ 1.40 + ( $0.08 × (amount -$ 25))

rate_bs

number

required

The exchange rate in Bolivares (Bs) per USD. This rate is validated against the current market rate stored in the system.The provided rate must be within 0.35 Bs tolerance of the current rate, otherwise the request will be rejected with a 400 error.

payment_reference

string

required

A unique payment reference number for this transaction. This field is checked for duplicates to prevent processing the same payment twice.If a transaction with this reference already exists, the request will fail with a 409 Conflict error.

type_pay

string

The payment method used for this transaction (e.g., “Pago Móvil”, “Transferencia”, “Zelle”).

recipient_account

string

The account information for the recipient. Format depends on the payment method.

Example Request

curl -X POST http://localhost:3001/api/transactions \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_type": "Comprar",
    "amount_usd": 50.00,
    "rate_bs": 36.50,
    "payment_reference": "REF123456789",
    "type_pay": "Pago Móvil",
    "recipient_account": "0414-1234567"
  }'

Response

message

string

Success message confirming the transaction was created.

transaction

object

The created transaction object with all calculated fields.

Show transaction properties

integer

The unique identifier for the transaction.

user_id

integer

The ID of the authenticated user who created this transaction.

transaction_type

string

The type of transaction: "Comprar" or "Vender".

amount_usd

number

The base amount in USD before commission.

commission_usd

number

The calculated commission in USD based on the amount.

total_usd

number

The final amount in USD after applying commission.

For Comprar: amount_usd + commission_usd
For Vender: amount_usd - commission_usd

rate_bs

number

The exchange rate in Bolivares per USD used for this transaction.

total_bs

number

The total amount in Bolivares, calculated as total_usd * rate_bs.

payment_reference

string

The unique payment reference provided in the request.

status

string

The current status of the transaction. Always "Pendiente" (Pending) for new transactions.

type_pay

string

The payment method used.

recipient_account

string

The recipient account information.

Success Response Example

{
  "message": "Transacción creada exitosamente",
  "transaction": {
    "id": 42,
    "user_id": 15,
    "transaction_type": "Comprar",
    "amount_usd": 50.00,
    "commission_usd": 3.40,
    "total_usd": 53.40,
    "rate_bs": 36.50,
    "total_bs": 1949.10,
    "payment_reference": "REF123456789",
    "status": "Pendiente",
    "type_pay": "Pago Móvil",
    "recipient_account": "0414-1234567"
  }
}

Error Responses

400 Bad Request

object

Returned when required fields are missing, rate validation fails, or commission exceeds the amount for sell transactions.

Show error scenarios

Missing Required Fields

{
  "message": "Todos los campos son obligatorios"
}

Rate Validation FailedReturned when the provided rate_bs differs from the current market rate by more than 0.35 Bs:

{
  "message": "La tasa ha cambiado. Por favor actualiza la página para continuar."
}

Commission Exceeds Amount (Sell Transactions Only)Returned when selling USD and the commission equals or exceeds the amount:

{
  "message": "La comisión excede o iguala el monto proporcionado"
}

401 Unauthorized

object

Returned when the authentication token is missing, invalid, or expired.

{
  "message": "Authentication required"
}

409 Conflict

object

Returned when the provided payment_reference has already been used in another transaction.

{
  "message": "La referencia de pago ya fue utilizada"
}

500 Internal Server Error

object

Returned when an unexpected server error occurs.

{
  "message": "Error del servidor"
}

Commission Calculation Details

The commission structure is tiered based on the transaction amount:

Amount Range	Commission
$1.00 -$ 9.99	$0.80 (flat)
$10.00 -$ 14.99	$1.00 (flat)
$15.00 -$ 25.00	$1.40 (flat)
Above $25.00	$1.40 + ($ 0.08 × (amount - $25))

Examples:

** $8.00**: Commission =$ 0.80
** $12.00**: Commission =$ 1.00
** $20.00**: Commission =$ 1.40
** $30.00**: Commission =$ 1.40 + ( $0.08 × 5) =$ 1.80
** $50.00**: Commission =$ 1.40 + ( $0.08 × 25) =$ 3.40

Rate Validation

The system validates that the exchange rate provided by the client is current and hasn’t changed significantly:

The server maintains a current exchange rate (fetched from external services)
When a transaction is created, the rate_bs is compared to the server’s rate
If the absolute difference is greater than 0.35 Bs, the transaction is rejected
This prevents transactions from being processed with stale or incorrect rates

Duplicate Prevention

To prevent accidental duplicate transactions, the payment_reference field is checked against all existing transactions. If a match is found, the request returns a 409 Conflict error. This ensures that each payment reference can only be used once across the entire system.

Authentication

Rates

Transactions

Payment Methods

Create Transaction

POST /api/transactions

Authentication

Request Body

Example Request

Response

Success Response Example

Error Responses

Commission Calculation Details

Examples:

Rate Validation

Duplicate Prevention

Build docs developers (and LLMs) love

Authentication

Rates

Transactions

Payment Methods

​POST /api/transactions

​Authentication

​Request Body

​Example Request

​Response

​Success Response Example

​Error Responses

​Commission Calculation Details

​Examples:

​Rate Validation

​Duplicate Prevention

Build docs developers (and LLMs) love

POST /api/transactions

Authentication

Request Body

Example Request

Response

Success Response Example

Error Responses

Commission Calculation Details

Examples:

Rate Validation

Duplicate Prevention