Skip to main content

​
Overview

This endpoint allows authenticated users to add a new payment method to their account. Payment methods are used to facilitate currency exchange transactions and can include bank transfers, mobile payments, and email-based payment services.

​
Authentication

This endpoint requires authentication via the verifyToken middleware. Include a valid JWT token in the Authorization header.

​
Endpoint

​
POST
endpoint
/api/payments-methods/add

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authentication
Authorization: Bearer YOUR_JWT_TOKEN
​
Content-Type
string
required
Must be set to application/json

​
Body Parameters

​
type
string
required
The type of payment method being added. Common values include:
  • bank_transfer - For bank account transfers
  • mobile_payment - For mobile payment services
  • email_payment - For email-based payment services
​
ci
string
required
National identification number (CI - Cédula de Identidad) of the payment method owner. This is used for verification purposes.
​
bank
string
Name of the bank for bank transfer payment methods. Required when type is bank_transfer.Example: “Banco Nacional”, “Banco Provincial”
​
phone
string
Phone number for mobile payment methods. Required when type is mobile_payment.Example: “+58 412-1234567”
​
owner_name
string
required
Full name of the person who owns the payment method. This should match the name associated with the bank account, phone number, or email payment service.
​
mail_pay
string
Email address for email-based payment services. Required when type is email_payment.Example: “[email protected]”

​
Example Requests

​
Response

​
Success Response (201 Created)

Returns the newly created payment method object with its assigned ID.
​
id
integer
Unique identifier assigned to the newly created payment method
​
type
string
Type of payment method that was created
​
ci
string
National identification number associated with the payment method
​
bank
string
Bank name (null if not applicable)
​
phone
string
Phone number (null if not applicable)
​
owner_name
string
Name of the payment method owner
​
mail_pay
string
Email address (null if not applicable)

​
Example Response

{
  "id": 15,
  "type": "bank_transfer",
  "ci": "12345678",
  "bank": "Banco Nacional",
  "phone": null,
  "owner_name": "Juan Pérez",
  "mail_pay": null
}

​
Error Responses

​
Implementation Details

  • Controller: paymentsController.createPaymentMethod
  • Middleware: verifyToken (authentication required)
  • Database Operation: Inserts a new record into the payment_methods table
  • User Context: The user ID is automatically extracted from the JWT token via req.user.id
  • Response Code: Returns HTTP 201 (Created) on success

​
Business Logic

  1. The endpoint extracts the authenticated user’s ID from the JWT token
  2. All payment method data from the request body is validated
  3. A new record is inserted into the payment_methods table with the user’s ID
  4. The newly created payment method is returned with its database-assigned ID
  5. The user can then use this payment method for currency exchange transactions

​
Best Practices

  • Validation: Ensure required fields match the payment method type (e.g., bank for bank transfers, phone for mobile payments)
  • Data Format: Use consistent formatting for phone numbers and identification numbers
  • Security: Never expose sensitive banking information in logs or error messages
  • User Experience: Validate payment method details on the client side before submission
  • Uniqueness: Consider implementing checks to prevent duplicate payment methods

Build docs developers (and LLMs) love

Get started for freeTalk to us