Skip to Content
Integra pagos con terminales POS directamente desde tu app Android 🚀 - Conoce el SDK Android
API EndpointsProcesar pagos

Procesar pagos

Esta sección detalla el uso del endpoint para procesar pagos. Sigue las instrucciones para integrar esta funcionalidad en tu aplicación.

Detalles del endpoint

  • Método: POST
  • URL: /api/v1/transactions

El endpoint permite efectuar cobros mediante el envío de datos del cliente y de la tarjeta de forma segura.

Configuración de la solicitud

Headers

HeaderDescripción
X-API-KEYAPI Key generada en Cubo Admin.

Si aún no has generado tu API Key, revisa nuestra sección de autenticación.

Cuerpo de la solicitud

Puedes procesar pagos de dos formas:

  • Con datos de tarjeta: Envía cardHolder, cardNumber, cvv, month y year.
  • Con tarjeta tokenizada: Envía el cardIdentifier obtenido desde el endpoint de tokenización en lugar de los datos de la tarjeta.
ParámetroTipoDescripción
clientNamestringNombre del cliente.
clientEmailstringCorreo electrónico del cliente.
clientPhonestringTeléfono del cliente con código de país.
descriptionstringDescripción de la transacción.
amountnumberCantidad de dinero a pagar.
cardIdentifierstringToken de tarjeta tokenizada (opcional).
cardHolderstringNombre del titular de la tarjeta.
cardNumberstringNúmero de la tarjeta de crédito o débito.
cvvstringCódigo de seguridad de la tarjeta.
monthstringMes de expiración de la tarjeta en formato MM.
yearstringAño de expiración de la tarjeta en formato YY.
branchIdnumberID de la sucursal del comercio (opcional).

El campo amount siempre debe enviarse como un número entero en centavos.

Sucursal del comercio

Puedes asociar la transacción a una sucursal de tu comercio agregando el campo branchId en tu solicitud. Este campo recibe el id de la sucursal, que puedes consultar en el endpoint de sucursales.

El branchId debe corresponder al id de una sucursal válida de tu comercio; de lo contrario, la solicitud será rechazada.

A continuación se muestran ejemplos de la solicitud en formato JSON:

Con datos de tarjeta:

{
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientPhone": "+50322577777",
  "description": "Test API",
  "amount": 100, // Monto en centavos (100 = $1.00)
  "cardHolder": "John Doe",
  "cardNumber": "4000000000000416",
  "cvv": "123",
  "month": "12",
  "year": "26",
  "branchId": 2 // opcional: ID de la sucursal del comercio
}

Con tarjeta tokenizada:

{
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientPhone": "+50322577777",
  "description": "Test API",
  "amount": 100, // Monto en centavos (100 = $1.00)
  "cardIdentifier": "c71cf205-b7d9-4982-80d6-26dc3542ee0e"
}

Revisa la sección tokenizar tarjeta para aprender cómo realizar la tokenización.

Ejemplos de uso

Pago con datos de tarjeta

fetch('https://<CUBO_API_URL>/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'TU_API_KEY_AQUI',
  },
  body: JSON.stringify({
    clientName: 'John Doe',
    clientEmail: '[email protected]',
    clientPhone: '+50322577777',
    description: 'Test API',
    amount: 100,  // Monto en centavos (100 = $1.00)
    cardHolder: 'John Doe',
    cardNumber: '4000000000000416',
    cvv: '123',
    month: '12',
    year: '26',
  }),
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Pago con tarjeta tokenizada

fetch('https://<CUBO_API_URL>/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'TU_API_KEY_AQUI',
  },
  body: JSON.stringify({
    clientName: 'John Doe',
    clientEmail: '[email protected]',
    clientPhone: '+50322577777',
    description: 'Test API',
    amount: 100,  // Monto en centavos (100 = $1.00)
    cardIdentifier: 'c71cf205-b7d9-4982-80d6-26dc3542ee0e',
  }),
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Montos de prueba

Existen montos específicos que puedes utilizar durante tus pruebas para simular distintos tipos de respuesta de la Cubo API. Cada monto está asociado a un mensaje de error particular, lo que te permite validar cómo se manejan los rechazos en tu integración.

Monto (amount)Mensaje de respuesta
4000EB - ERROR DE DÍGITO
403030 - ERROR DE FORMATO
400101 - LLAMAR AL EMISOR
405151 - FONDOS INSUFICIENTES

Estos montos son ideales para asegurarte de que tu manejo de errores funciona correctamente antes de salir a producción.

Respuestas del servidor

✅ Respuesta exitosa

Indica que el pago fue aprobado exitosamente.

{
  "status": "SUCCEEDED",
  "paymentIntentToken": "INTENT_TOKEN",
  "referenceId": "354247606061629",
  "authorizationCode": "015163",
  "processedAt": "2025-02-10T22:27:17.317Z"
}

❌ Respuesta de error

Indica que el pago fue rechazado.

{
  "statusCode": 400,
  "message": "15 - EMISOR NO DISPONIBLE"
}

Asegúrate de manejar correctamente las respuestas del servidor en tu aplicación para ofrecer una mejor experiencia al usuario.

AutenticaciónPago de suscripción