Benky
Última actualización: March 03 2025 - 1933 v1.5
Envíos /
Transferencias
Permite realizar envíos / transferencias a la
cuenta del cliente.
Autenticación
Todos los llamados que realices a los endpoint
disponibles deberán incluir el encabezado de
autenticación con el token de acceso.
Para conocer en detalle cómo obtener el token
de acceso, consulta la sección Primeros pasos
de la documentación general
Id del producto
Antes de empezar la integración, es necesario
conocer el Id asociado al producto. Para ello,
consulta la sección Obtener productos de la
documentación general.
Benky
Endpoints
disponibles
A continuación se explicará cada uno de los
endpoints disponibles para lograr el consumo
exitoso del producto.
Obtener datos del producto
Ruta del Endpoint
GET [Link]
seleccionado/products/getProductDetails
Este endpoint proporciona información
detallada del producto, incluyendo los valores
base del formulario, como son, tipos de
documento, listado de bancos, tipos de cuenta,
etc.
Parámetros:
Nombre Descripción Valor Ti
predeterminado
productId Identificador O
único del
producto.
A continuación, se detalla cómo realizar la
solicitud y se explica la estructura de la
respuesta.
Importante
Se debe incluir en los headers el token de
Benky
acceso obtenido mediante el proceso de
autenticación.
Ejemplos de solicitud:
Javascript php curl
Javascript
const axios = require('axios');
const apiUrl = '[Link]
const accessToken = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJI
const productId = 1;
const config = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
};
[Link](`${apiUrl}?productId=${productId}`, con
.then(response => {
// Manejar la respuesta exitosa
const productData = [Link];
[Link]('Información del Producto:', prod
})
.catch(error => {
// Manejar errores de la solicitud
[Link]('Error en la solicitud:', error
});
200: Respuesta exitosa
La respuesta exitosa proporcionará un array
JSON con los siguientes datos:
json
json
Benky
{
"hasSubproducts": false,
"status": "OK",
"productName": "Envíos",
"productDescription": "Envia dinero a tus famil
"productImage": "https:\/\/system-assets.nyc3.d
"token": "d37781627d91fc70858149122cea9bd61785b
"ts": 1739481980,
"subProductsData": "[]",
"productId": 1,
"prefix": "TFR",
"currency": "USD",
"formData": [
{
"field": "celularSender",
"type": "text",
"label": "Whatsapp de quien envía",
"placeholder": "Para notificaciones",
"class": "form-control required",
"containerClass": "col-12 mb-3 col-sm-3
},
{
"field": "pais_receiver",
"type": "select",
"label": "Pais destino",
"labelClass": "text-nowrap",
"options": [ // Se recomienda consultar
{
"id": "",
"value": "Selecciona el país de
},
{
"id": "29",
"value": "Bolivia (COP)"
},
{
"id": "33",
"value": "Brasil (COP)"
},
{
"id": "46",
"value": "Chile (CLP)"
},
{
"id": "1",
Benky "value": "Colombia (COP)"
},
{
"id": "252",
"value": "Costa Rica (USD)"
},
{
"id": "3",
"value": "Ecuador (USD)"
},
{
"id": "208",
"value": "España (USD)"
},
{
"id": "2",
"value": "Venezuela (VES)"
}
],
"value": "",
"class": "form-control",
"containerClass": "col-6 col-sm-3 mb-3
},
{
"field": "tipodocReceiver",
"type": "select",
"label": "Tipo documento destinatario",
"options": [
{
"id": "",
"value": "Selecciona el país de
}
],
"class": "form-control required",
"containerClass": "col-6 col-sm-3 mb-3"
},
{
"field": "ccReceiver",
"type": "text",
"label": "Identificación destinatario",
"class": "form-control required",
"containerClass": "col-6 col-sm-3 mb-3"
"inputButton": {
"id": "enableQRreader",
"class": "btn bg-green py-0 ps-1 pe
"text": "<svg width='24px' height=
Benky
}
},
{
"field": "nombre_1Receiver",
"type": "text",
"label": "Nombre completo destinatario"
"class": "form-control text-uppercase r
"containerClass": "col-8 mb-3"
},
{
"field": "celularReceiver",
"type": "text",
"label": "Telefono móvil destinatario",
"placeholder": "Para notificaciones",
"class": "form-control required",
"containerClass": "col-4 mb-3"
},
{
"field": "cuenta",
"type": "radio",
"label": "Tipo cuenta",
"options": [
{
"id": "1",
"value": "Ahorros",
"data": {
"accountLength": "20",
"separateEach": "4"
}
},
{
"id": "2",
"value": "Corriente",
"data": {
"accountLength": "20",
"separateEach": "4"
}
},
{
"id": "3",
"value": "Pago Movil",
"data": {
"accountLength": "11",
"separateEach": "3"
}
}
Benky
],
"class": "form-check-input required m-1
"labelClass": "form-check-label",
"labelContainerClass": "form-check form
"containerClass": "col-12 mb-2 col-md-4
},
{
"field": "nocuenta",
"type": "text",
"label": "No. cuenta",
"maxlength": 24,
"class": "form-control required",
"containerClass": "col-12 mb-2 col-md-4
},
{
"field": "banco",
"type": "select",
"label": "Banco",
"options": [
{
"id": "",
"value": "Selecciona el país de
}
],
"class": "form-select required",
"containerClass": "col-12 mb-2 col-md-4
},
{
"field": "detallesEnvio",
"type": "label",
"class": "",
"containerClass": "col-12 col-sm-12 sha
"label": "Detalles del envío"
},
{
"field": "tasasTitle",
"type": "label",
"class": "",
"containerClass": "border rounded-3 sha
"label": "La tasa de envío se calculará
},
{
"field": "calcOrig",
"type": "text",
"label": "Vr enviar",
"labelClass": "text-nowrap",
Benky "maxlength": 8,
"class": "form-control text-end",
"containerClass": "col-6 col-sm-2 mb-3
"foothint": "(Mínimo USD 10.00)"
},
{
"field": "trmData",
"type": "text",
"label": "Tasa",
"labelClass": "text-nowrap",
"readOnly": true,
"class": "form-control text-end bg-gray
"containerClass": "col-6 col-sm-2 mb-3
},
{
"field": "costoEnvio",
"type": "text",
"label": "Costo envío",
"labelClass": "text-nowrap",
"class": "form-control text-end bg-gray
"readOnly": true,
"containerClass": "col-6 col-sm-2 mb-3
},
{
"field": "valorDestino",
"type": "text",
"label": "Valor destino",
"labelClass": "text-nowrap",
"class": "form-control text-end bg-gray
"readOnly": true,
"containerClass": "col-6 col-sm-2 mb-3
}
],
"customData": {
"minTopup": 10
}
}
Campos de la respuesta:
* hasSubproducts: false - Indica que el
producto no tiene subproductos
* status: OK - Estado de la solicitud
* productName: Nombre del producto
* productDescription: Descripción detallada del
Benky
producto
* productImage: Imagen identificadora del
producto
* token: Token de transacción (NO usado)
* ts: Timestamp de la transacción (NO usado)
* subProductsData: En blanco siempre para
este producto
* productId: 1 - Id del producto (debe ser igual
al Id enviado en la consulta)
* prefix: TFR - Código alfanumérico del
producto
* currency: USD - Código ISO3 de la moneda en
la que se vende el producto (moneda que se
recibe)
* formData: Objeto JSON con los campos base
del formulario requeridos para hacer la venta
del producto. (Incluye datos de los selectores
por ejemplo, países de destino)
* customData: Objeto JSON con propiedades
adicionales para el producto. (Ejemplo:
minTopup que contiene el valor mínimo
permitido para hacer el envío)
4xx - 5xx: Respuesta de error
En el caso de una respuesta de error, la API
podría devolver un objeto similar al siguiente:
json
json
{
"status": "ERROR",
"message": "No autorizado. Error de autenticaci
"error": "bad_info"
}
Campos de la respuesta:
status: Indica el estado de la respuesta. En este
Benky
caso, es ERROR, lo que indica que hubo un
problema durante el proceso de consulta.
message: Proporciona un mensaje descriptivo
del error. En este ejemplo, indica que el recurso
no fue encontrado. La subcadena "->
wrong_productId" puede proporcionar detalles
adicionales sobre la naturaleza del error.
error: Proporciona un código específico del
error. En este caso, el código es
"wrong_productId", lo que podría ser útil para
identificar y manejar programáticamente el
tipo de error que ocurrió.
Obtener datos del país de
destino
Ruta del Endpoint
GET [Link]
seleccionado/products/getSubproductDetails
Este endpoint permite obtener datos del país de
destino. por ejemplo. Bancos, tipos de
documento, tipos de cuenta (si cambian)
Parámetros:
Nombre Descripción Valor
predetermina
subproductId Identificador
único del
país (Se
debe enviar
el Id país
que se
Benky obtuvo en el
endpoint
anterior [1] ).
countryReceiver Código del
país a
consultar
queryType Tipo de
consulta
A continuación, se detalla cómo realizar la
solicitud y se explica la estructura de la
respuesta.
Importante
Se debe incluir en los headers el token de
acceso obtenido mediante el proceso de
autenticación.
Ejemplos de solicitud:
Javascript php curl
Javascript
const axios = require('axios');
const apiUrl = '[Link]
const accessToken = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJI
const subproductId = 1;
const countryReceiver = "1";
const queryType = "getCountrySettings";
const config = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`,
}, Benky
};
[Link](`${apiUrl}?subproductId=${subproductId}
.then(response => {
// Manejar la respuesta exitosa
const productData = [Link];
[Link]('Información del país:', productD
})
.catch(error => {
// Manejar errores de la solicitud
[Link]('Error en la solicitud:', error
});
200: Respuesta exitosa
La respuesta exitosa proporcionará un array
JSON con los siguientes datos:
json
json
{
"status": "OK",
"message": {
"bank": [
{
"value": "47",
"label": "AV VILLAS"
},
{
"value": "45",
"label": "BANCO DE BOGOTA"
},
{
"value": "41",
"label": "BANCOLOMBIA"
},
{
"value": "48",
"label": "COLPATRIA"
},
{
"value": "44",
Benky"label": "DAVIPLATA"
},
{
"value": "42",
"label": "DAVIVIENDA"
},
{
"value": "49",
"label": "FALABELLA"
},
{
"value": "46",
"label": "ITAU"
},
{
"value": "43",
"label": "NEQUI"
}
],
"documentType": [
{
"value": "3",
"label": "Cédula de ciudadanía"
},
{
"value": "4",
"label": "Cédula de extranjería"
},
{
"value": "1",
"label": "NIT"
},
{
"value": "6",
"label": "Otro"
},
{
"value": "5",
"label": "Pasaporte"
},
{
"value": "2",
"label": "RUT"
}
]
}
} Benky
Campos de la respuesta:
* status: OK - Estado de la solicitud
* message: Objeto con los datos del
destinatario -
- bank: [] Array con el par value/label de los
bancos disponibles para el país,
- documentType: [] Array con el par value/label
de los tipos de documentos disponibles para el
país,
- *accountType: [] Array con el par value/label
de los tipos de cuenta disponibles para el país, *
Solo se envía si cambian de los tipos base
Ahorros/Corriente/#celular(PagoMovil)
4xx - 5xx: Respuesta de error
En el caso de una respuesta de error, la API
podría devolver un objeto similar al siguiente:
json
json
{
"status": "ERROR",
"message": "No se encuentra el usuario"
}
Campos de la respuesta:
status: Indica el estado de la respuesta. En este
caso, es ERROR, lo que indica que hubo un
problema durante el proceso de consulta.
message: Proporciona un mensaje descriptivo
del error.
Benky
Obtener datos del destinatario
Ruta del Endpoint
GET [Link]
seleccionado/products/getSubproductDetails
Este endpoint permite obtener datos del
destinatario enviando en la consulta, el
parámetro queryType = searchReceiver
Parámetros:
Nombre Descripción Valor
predeterminad
subproductId Identificador
único del
producto
(Se debe
enviar el Id
producto
que se
obtuvo en el
endpoint
anterior [1] ).
documentType Tipo de
documento
del
destinatario.
customerId Número de
documento
de
identidad
del
destinatario.
queryType Tipo de
Benky consulta
A continuación, se detalla cómo realizar la
solicitud y se explica la estructura de la
respuesta.
Importante
Se debe incluir en los headers el token de
acceso obtenido mediante el proceso de
autenticación.
Ejemplos de solicitud:
Javascript php curl
Javascript
const axios = require('axios');
const apiUrl = '[Link]
const accessToken = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJI
const subproductId = 1;
const documentType = "V";
const customerId = "123456789";
const queryType = "searchReceiver";
const config = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
};
[Link](`${apiUrl}?subproductId=${subproductId}
.then(response => {
// Manejar la respuesta exitosa
const productData = [Link];
Benky
[Link]('Información del Producto:', prod
})
.catch(error => {
// Manejar errores de la solicitud
[Link]('Error en la solicitud:', error
});
200: Respuesta exitosa
La respuesta exitosa proporcionará un array
JSON con los siguientes datos:
json
json
{
"status": "OK",
"message": {
"tipoid": "V",
"cedula": "12345678",
"nombre_1": "MARIA MORALES",
"celular": "987654321",
"banco": 16,
"tipo_cuenta": 2,
"numero": "01020102123456781212",
}
}
Campos de la respuesta:
* status: OK - Estado de la solicitud
* message: Objeto con los datos del
destinatario -
- Tipo de documento,
- Cédula,
- Nombres y apellidos,
- Celular,
- y datos bancarios (Id Banco, Tipo de cuenta y
número de cuenta).
4xx - 5xx: Respuesta de error
Benky
En el caso de una respuesta de error, la API
podría devolver un objeto similar al siguiente:
json
json
{
"status": "ERROR",
"message": "No se encuentra el usuario"
}
Campos de la respuesta:
status: Indica el estado de la respuesta. En este
caso, es ERROR, lo que indica que hubo un
problema durante el proceso de consulta.
message: Proporciona un mensaje descriptivo
del error.
Obtener cálculo de
equivalencias
Ruta del Endpoint
[Link]
GET
seleccionado/products/getSubproductDetails
Este endpoint permite obtener datos del envío,
enviando en la consulta, el parámetro
queryType = calculateTransferValue
Parámetros:
Nombre Descripción Valor
predetermina
subproductId Identificador
Benky único del
producto
(Se debe
enviar el Id
producto
que se
obtuvo en el
endpoint
anterior [1] ).
countryReceiver Código del
país de
destino
cantidadOrigen Valor que se
desea
enviar en la
moneda
origen del
país
bancoReceiver Id del banco
del
destinatario
queryType Tipo de
consulta
A continuación, se detalla cómo realizar la
solicitud y se explica la estructura de la
respuesta.
Importante
Se debe incluir en los headers el token de
Benky
acceso obtenido mediante el proceso de
autenticación.
Ejemplos de solicitud:
Javascript php curl
Javascript
const axios = require('axios');
const apiUrl = '[Link]
const accessToken = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJI
const subproductId = 1;
const countryReceiver = 1;
const cantidadOrigen = 10;
const bancoReceiver = 41;
const queryType = "calculateTransferValue";
const config = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
};
[Link](`${apiUrl}?subproductId=${subproductId}
.then(response => {
// Manejar la respuesta exitosa
const productData = [Link];
[Link]('Información del Producto:', prod
})
.catch(error => {
// Manejar errores de la solicitud
[Link]('Error en la solicitud:', error
});
200: Respuesta exitosa
La respuesta exitosa proporcionará un array
JSON con los siguientes datos:
json
Benky
json
{
"status": "OK",
"message": {
"moneda_equivalencia": "USD",
"trm": "28.05",
"comision": 1.5,
"total_pagar": 101.5,
"total_recibir": 2805
}
}
Campos de la respuesta:
* status: OK - Estado de la solicitud
* message: Objeto con los datos del cálculo
- moneda_equivalencia,
- trm, (tasa de equivalencia)
- comision (en caso de que se realice algun
cargo por el envío),
- total_pagar (Valor total que debe pagar
quien solicita el envío),
- total_recibir (Valor que se consignará en la
cuenta del destinatario).
4xx - 5xx: Respuesta de error
En el caso de una respuesta de error, la API
podría devolver un objeto similar al siguiente:
json
json
{
"status": "ERROR",
"message": "Detalle del error"
}
Campos de la respuesta:
Benky
status: Indica el estado de la respuesta. En este
caso, es ERROR, lo que indica que hubo un
problema durante el proceso de consulta.
message: Proporciona un mensaje descriptivo
del error.
Guardar envío
Ruta del Endpoint
POST [Link]
seleccionado/sales/create
Se debe usar este endpoint para finalizar y
almacenar los datos del envío.
A continuación, se proporciona información
detallada junto con ejemplos de solicitud y
respuestas.
Parámetros:
Nombre Descripción Valor
predetermin
transactionId Identificador
único de
transacción,
se usa para
identificar y
tener
trazabilidad
de la
transacción
desde
origen. (max
Benky 32
caracteres)
productId Identificador
único del
producto
(Se debe
enviar el Id
producto
que se
obtuvo en el
endpoint
anterior [1] ).
getBalance Puedes false
incluir este
parámetro
si deseas
que al
guardar la
transacción,
retorne el
saldo de la
cuenta.
countryReceiver Código del
país del
destinatario
celularSender Celular del
remitente
tipodocReceiver Tipo de
documento
del
destinatario
ccReceiver Número de
documento
del
destinatario
nombre_1Receiver Nombre
Benky completo
del
destinatario
celularReceiver Número de
celular del
destinatario
accountType Tipo de
cuenta del
destinatario
accountNumber Número de
cuenta del
destinatario
bankReceiver Id del banco
del
destinatario
transferAmount Cantidad a
transferir
A continuación, se detalla cómo realizar la
solicitud y se explica la estructura de la
respuesta.
Importante
Se debe incluir en los headers el token de
acceso obtenido mediante el proceso de
autenticación.
Ejemplos de solicitud:
Javascript php curl
Javascript
Benky
const axios = require('axios');
const accessToken = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJI
var data = {
productId: 1,
countryReceiver: "1",
getBalance: true,
transferRate: 'O2D',
celularSender: '9876543210',
tipodocReceiver: 'V',
ccReceiver: '65432174',
nombre_1Receiver: 'Pedro Antonio Rojas',
celularReceiver: '0123456789',
accountNumber: '0102-0102-1234-5678-1212',
bankReceiver: '15',
accountType: '2',
transferAmount: '10',
"transactionId": "1234567-12345"
}
[Link]('[Link]
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
}
})
.then(response => {
[Link]([Link]);
})
.catch(error => {
[Link]([Link]);
});
200: Respuesta exitosa
La respuesta exitosa proporcionará un array
JSON con los resultados de la solicitud de envío.
json
json
Benky
{
"status": "OK",
"message": "Información almacenada correctament
"bankId": "15",
"accountNumber": "01020102123456781212",
"transferAmount": 10,
"foreignAmount": 310.2,
"rate": "31.02",
"saleId": 236,
"saleReference": "TFR1591423948",
"saleTotalValue": 11.05,
"accountBalance": 716.38,
"accountEarningsBalance": 48.67
"transactionId": "1234567-12345"
}
Campos de la respuesta exitosa:
status: Indica el estado de la respuesta (en este
caso, "OK").
message: Mensaje informativo sobre el
resultado de la venta.
bankId: Código del banco
accountNumber: Número de cuenta
transferAmount: Valor a transferir
foreignAmount: Valor a entregar
rate: Tasa de equivalencia
saleId: Id de la venta
saleReference: Referencia de la venta
saleTotalValue: Total pagado por el cliente
accountBalance: Saldo actual de tu cuenta (Si
se incluyó el parámetro getBalance = true en la
petición)
accountEarningsBalance: Saldo actual de
comisionesde tu cuenta (Si se incluyó el
parámetro getBalance = true en la petición)
4xx - 5xx: Respuesta de autenticación no autorizada
En el caso de una respuesta de autenticación
no autorizada, la API podría devolver un objeto
similarBenky
al siguiente:
json
json
{
"status": "ERROR",
"message": "El valor mínimo para enviar es: 10.
}
Campos de la respuesta:
status: Indica el estado de la respuesta. En este
caso, es ERROR, lo que indica que hubo un
problema durante el proceso de consulta.
message: Proporciona un mensaje descriptivo
del error.
IMPORTANTE Ante cualquier respuesta que
no cumpla con el formato ni las características
descritas en esta documentación, se deberá
validar el estado final de la solicitud ya sea
mediante el transactionId (si se envía), o
manualmente, con el fin de evitar
procesamientos duplicados
Flujo de proceso
Benky
Benky
Designed with by Xiaoying Riley