Dispersión

Este servicio permite generar solicitudes de retiro a través de los medios de dispersión habilitados.

Para utilizar el servicio, es necesario contar con un token de autenticación, que debe enviarse como un encabezado Authorization. Además, se requiere un token transaccional específico para el servicio de Dispersión, el cual debe incluirse en los encabezados de la siguiente manera:

Key : x-transaction-token

Value : 9b48edde-652d-11ed-984e-02c840fe****

A continuación, se detallan los ID correspondientes a cada método de dispersión disponible en nuestra API:

• 160 - Retiro online

• 245 - Dispersión como producto

Es importante tener en cuenta que, al generar la dispersión, se notificará la operación vía SMS. A partir de ese momento, se dispondrá de un plazo de 12 horas para aceptar la transacción desde la entidad bancaria correspondiente.

Además, debe haber un intervalo de al menos 30 segundos entre la generación de una transacción y otra. El usuario que realiza la dispersión debe contar con saldo suficiente para completar la solicitud.

Generar recurso de Dispersión

POST https://pay-api.qa.refacil.co/cash-out/generate/withdraw-method/token

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
amount*	number	Valor del pago
reference1*	string	Identificador único de la transacción generado por el cliente. No puede superar los 20 caracteres
webhookRequest	string	Url del webhook del cliente al cual se le notificará el estado del retiro
withdrawMethod*	object	Objeto donde se agregará el método de pago y el celular destino de la dispersión
id*	number	Identificación del método de pago
cellphone*	string	Celular destino de la dispersión
bankName	string	Nombre del banco destino de la dispersión

Response

Name	Type	Description
statusCode	string	Código de estado de la operación
message	string	Mensaje descriptivo de la operación
transactionReference	string	Referencia generada por el sistema (Refacil Pay) con la que se puede consultar el estado de la dispersión
withdraw.transactionId	string	Identificador único de la transacción generada por el sistema (Refacil Pay)
withdraw.userId	number	ID del usuario asociado a la transacción
withdraw.accountNumber	number	Número de cuenta o celular destino de la dispersión
withdraw.infoReference	string	Información de referencia asignada por el cliente (reference1)
withdraw.providerReference	string	Referencia generada por el proveedor del servicio (Transfiya)
withdraw.accountId	null/string	ID de la cuenta si aplica, o null
withdraw.observation	null/string	Observación adicional si existe, o null
withdraw.id	string	ID único de la operación de retiro (Refacil Pay)
withdraw.createdAt	string (ISO 8601)	Fecha y hora de creación de la transacción
withdraw.updatedAt	string (ISO 8601)	Fecha y hora de la última actualización de la transacción

200: OK Exitosa

Request

{
  "withdrawMethod": {
    "id": 160,
    "cellphone": "3125763074"
  },
  "amount": 10000,
  "reference1": "string",
  "bankName": "Banco Rojo",
  "webhookRequest": "https://****gerstg.azure-api.net/SkCo.PagosEnLinea.API/payonline/PostStatus",
}

Response

{
    "statusCode": "00",
    "message": "Operación exitosa.",
    "data": {
        "withdraw": {
            "transactionId": "3622588",
            "userId": 302043,
            "accountNumber": "3125763074",
            "infoReference": "pruebaQA_2",
            "providerReference": "hwc3eGcWQLANWUEvs",
            "accountId": null,
            "deletedAt": null,
            "observation": null,
            "id": "661",
            "createdAt": "2024-02-21T21:40:10.437Z",
            "updatedAt": "2024-02-21T21:40:10.437Z"
        },
        "transactionReference": "305284e0-9145-11ef-8b96-87e99a18bcae"
    }
}

401: Unauthorized Sin permisos

Response

{
  "message": "Autenticación no encontrada",
  "statusCode": "01",
  "data": {}
}

500: Internal Server Error Internal server error

Response

{
    "statusCode": "03",
    "message": "Error al generar el recurso.",
    "data": {
        "errorCode": "",
        "detail": "Request failed with status code 503"
    }
}

400: Bad Request Monto ingresado no válido

Response

{
    "statusCode": "03",
    "message": "Error al generar el recurso.",
    "data": {
        "errorCode": "",
        "detail": "El monto ingresado está fuera del rango aceptado"
    }
}

Consulta de saldos

POST https://pay-api.qa.refacil.co/customer/getBalance

Este servicio permite consultar la bolsa de saldo y la bolsa de dispersión asociada al identificador del cliente.

Para utilizar el servicio, es necesario contar con un token de autenticación, que debe enviarse como un encabezado Authorization.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
userId*	number	Identificador único del usuario integrado

Example

200: Ok Exitosa

Request

{
    "userId": 1085718
}

Response

{
    "bags": [
        {
            "bag": "Saldo de dispersión",
            "amount": "9823225.00"
        },
        {
            "bag": "Bolsa de Multiproducto",
            "amount": "10104980.00"
        }
    ],
    "date": "29/08/2024 15:18:47"
}

401: Unauthorized Sin permisos

Response

{
  "message": "Autenticación no encontrada",
  "statusCode": "01",
  "data": {}
}

500: Internal Server Error Internal server error

Response

{
    "statusCode": "03",
    "message": "Error al generar el recurso.",
    "data": {
        "errorCode": "",
        "detail": "Request failed with status code 503"
    }
}

400: Bad Request Usuario no válido

Response

{
    "statusCode": 400,
    "errorCode": "server.error",
    "message": "Ocurrió un error al consultar las bolsas",
    "path": "/customer/getBalance",
    "date": 1724962461988
}

Consulta de bancos

POST https://pay-api.qa.refacil.co/payment/transfiya-banks

Este servicio permite obtener una lista de los bancos asociados a un número telefónico vinculado al medio de Transfiya.

Para utilizar el servicio, es necesario contar con un token de autenticación, que debe enviarse como un encabezado Authorization.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
cellphone*	string	El número de celular con el cual se realizará la consulta del listado de bancos.

Example

200: Ok Exitosa

Request

{
    "cellphone": "3051000002"
}

Response

{
    "statusCode": "00",
    "message": "Operación exitosa.",
    "data": {
        "banks": [
            {
                "name": "Banco Rojo",
                "bankAccountNumber": "xxxx1111"
            },
            {
                "name": "Banco Rojo",
                "bankAccountNumber": "xxxxxxxx8777"
            }
        ]
    }
}

401: Unauthorized Sin permisos

Response

{
    "statusCode": 401,
    "errorCode": "server.error",
    "message": "Autenticación no encontrada",
    "path": "/payment/transfiya-banks",
    "date": 1721771849919
}

500: Internal Server Error Internal server error

Response

{
    "statusCode": "03",
    "message": "Error al generar el recurso.",
    "data": {
        "errorCode": "",
        "detail": "Request failed with status code 503"
    }
}