Generar una Dispersión a Terceros con Direct API
Dispersión a terceros de fondos recibidos en Conekta
En este documento se describe cómo se realiza una Dispersión a terceros a través de Direct API. Conoce cómo enviar fondos que has recibido con Conekta (dispersar) a un payee o beneficiario, cómo enviar notificaciones, revisar tu Estado de Cuenta en Panel, hacer consultas de una Dispersión a Terceros generada y los eventos relacionados.
¿Qué es una Dispersión a Terceros?
Una dispersión, es el envío de fondos a una cuenta ajena a tu Negocio. Para conocer todos los detalles, ingresa en nuestro Resumen.
Recuerda que antes de utilizar esta funcionalidad debes consultar con tu Ejecutivo de Cuentas de Conekta si la misma se encuentra disponible para tu negocio o envíanos un correo a [email protected]
Importante
Esta funcionalidad no soporta Dispersiones a Terceros a partir de fondeo propio del comercio, solo soporta Dispersiones a Terceros a partir del saldo generado por los cobros en Conekta.
Diagrama de secuencia
Agregar API Keys y la versión de API
Necesitas tu API Key Privada de pruebas sandbox. Puedes encontrarla en Panel en el módulo de Desarrolladores, en el cuadro "Ver API Keys". Si requieres más información del proceso consulta nuestro documento Cómo obtener tus API Keys.
require_once("/path/to/lib/Conekta.php");
\Conekta\Conekta::setApiKey("key_DePruebaDeApi");
\Conekta\Conekta::setApiVersion("2.0.0");
var conekta = require('conekta');
conekta.api_key = 'key_DePruebaDeApi';
conekta.api_version = '2.0.0';
import conekta
conekta.api_key = "key_DePruebaDeApi"
conekta.api_version = "2.0.0"
import com.conekta;
Conekta.setApiKey("key_DePruebaDeApi");
com.conekta.Conekta.apiVersion = "2.0.0"
using conekta;
conekta.Api.apiKey = "key_DePruebaDeApi";
conekta.Api.version = "2.0.0";
import (
conekta "github.com/conekta/conekta-go"
)
conekta.APIKey = "key_DePruebaDeApi"
N/A
Crear un beneficiario
Cuando creas un Beneficiario o Payee a través del siguiente endpoint, podrás enviar fondos usando el Objeto Transfers.
Un Payee puede tener solo un destinations predeterminado, es decir, una cuenta bancaria asignada a la cual se realizará la dispersión.
Utilizando la Key obtenida en el punto anterior podrás crear al Beneficiario
curl --request POST \
--url https://api.conekta.io/payees \
--header 'accept: application/vnd.conekta-v2.0.0+json' \
-u key_DePruebaDeApi: \
--header 'content-type: application/json' \
--data '{
"name": "Jon Doe",
"email": "[email protected]",
"phone": "5555555555",
"destinations": [{
"type": "bank_account",
"account_number": "123456789012345678",
"account_holder_name": "Jon Doe Account"
}]
}'
try:
payee = conekta.Payee.create({
'name': 'Jon Doe',
'email': '[email protected]',
'phone': '5555555555',
'destinations': [{
'type': 'bank_account',
'account_number': '123456789012345673',
'account_holder_name': 'Jon Doe Account'
}]
})
except conekta.ConektaError as e:
print e.message
customer = Conekta::Payee.create({
name: 'Jon Doe',
email: '[email protected]',
phone: '5555555555',
destinations: [{
type: 'bank_account',
account_number: '123456789012345673',
account_holder_name: 'Jon Doe Account'
}]
})
Parámetros destinations
Parámetro | Descripción | Type | Value | Mandatorio |
---|---|---|---|---|
type | El tipo de destinatario | String | Siempre colocar "bank_account" | Sí |
account_number | Número de cuenta bancaria (CLABE interbancaria) | Integer | 18 caracteres numéricos | Sí |
account_holder_name | Nombre del beneficiario | String | Menos de 250 caracteres | Sí |
Respuesta a la creación de un Beneficiario
{
"id": "payee_DePrueba",
"email": "[email protected]",
"name": "Jon Doe",
"phone": "5555555555",
"livemode": true,
"destinations": [
{
"id": "pytdst_2tP8Ghmusukdshfj",
"payee_id": "payee_DePrueba",
"object": "destination",
"created_at": 1676655906,
"type": "bank_account",
"currency": "MXN",
"last4": "1000",
"account_holder_name": "Jon Doe Account",
"bank": "banorte"
}
],
"object": "payee",
"default_destination_id": "payee_DePrueba",
"created_at": 1676655906
}
Crear una dispersión
La creación de un Objeto Transfer genera una nueva solicitud de Dispersión para el Beneficiario. La solicitud se ejecutará dentro de un día hábil después de que se haya programado la solicitud. Por ejemplo, si se solicita el Lunes, se ejecutará el Martes; si se solicita el Viernes se ejecutará el Lunes siguiente.
A continuación te mostramos como puedes crear una Dispersión para el Payee creado anteriormente:
API Key & Payee_ID
Utiliza la misma API Key Privada que se obtuvo en pasos previos. El payee_id debe ser el que obtuvimos al crear el Payee, en el ejemplo: payee_DePrueba
curl --request POST \
--url https://api.conekta.io/transfers \
--header 'accept: application/vnd.conekta-v2.0.0+json' \
-u key_DePruebaDeApi: \
--header 'content-type: application/json' \
--data '{
"payee_id": "payee_DePrueba",
"amount": 50000,
"currency": "MXN"
}'
try:
order = conekta.Transfer.create({
'payee_id': 'payee_DePrueba',
'amount': 50000,
'currency': 'MXN'
})
except conekta.ConektaError as e:
print e.message
begin
payee = Conekta::Transfer.create({
'payee_id': 'payee_DePrueba',
'amount': 50000,
'currency': 'MXN'
})
rescue Conekta::Error => error
for error_detail in error.details do
puts error_detail.message
end
end
Amount
El amount, es decir, el monto a dispersar, acepta centavos. Para dispersar $10.00 MXN (Diez pesos mexicanos) se debe colocar "amount": 1000, es decir sin el punto decimal. Los centavos pueden ser diferentes a cero.
Respuesta al crear una Dispersión
{
"livemode": true,
"currency": "MXN",
"destination": {
"payee_id": "payee_DePrueba",
"id": "pytdst_2tP8Ghmusukdshfj",
"created_at": 1676656070,
"object": "destination",
"type": "bank_transfer",
"last4": "1000",
"account_holder_name": "Jon Doe Account",
"bank": "banorte"
},
"object": "transfer",
"amount": 10000,
"id": "abcdefghijklmnopq1111111",
"created_at": 1676656070,
"status": "pending",
"statement_reference": "1111111",
"statement_description": "Jon Doe Account 1111111"
}
Importante.
Si has generado una dispersión y los parámetros son correctos, se ejecutará; una vez realizada la solicitud no es posible cancelar una dispersión.
No olvides cambiar tus API Keys por las productivas después de ejecutar tus pruebas en sandbox.
Estado de cuenta
En el menú de Finanzas, módulo Estado de cuenta se encuentra el detalle de movimientos y las Dispersiones a terceros realizadas, podrás identificarlas en la Descripción como "Dispersión a Cuenta de Tercero", podrás ver el Importe (Monto que se dispersó), la Comisión aplicada, el IVA (Impuesto sobre el Valor Agregado) y el Saldo disponible hasta el momento de esa transacción.
Recibir notificaciones
Agrega un Webhook (Evento) para poder recibir actualizaciones de la Dispersión, con ello podrás recibir las notificaciones. Los dos tipos principales de notificaciones que puedes recibir son payout.created y payout.paid_out.
Para agregar el Evento, ingresa en el módulo de Desarrolladores dentro de tu Panel Conekta y selecciona Revisar Webhooks en el apartado Webhooks; crea un Webhook pegando la URL. También puedes utilizar Direct API para generarlos, consulta nuestra referencia de Webhooks.
Uso de URLs públicas: Si no tienes una dirección IP pública o dominio, puedes usar servicios como Webhook.site, Ultrahook o Localtunnel. Consulta nuestra referencia de webhooks aquí.
Response payout.created
{
"livemode": true,
"currency": "MXN",
"method": {
"id": "pytmtd_dePrueba",
"created_at": 1676053647,
"payee_id": "payee_dePrueba",
"_type": "BankTransferPayoutMethod",
"object": "bank_transfer_payout_method",
"account_number": "123456789012345673",
"account_holder": "Jon Doe Account",
"bank": "banorte"
},
"object": "transfer",
"amount": 1000,
"id": "abcdefghijklmnopq1111111",
"created_at": 1676053647,
"status": "pending",
"statement_reference": "1111111",
"statement_description": "Jon Doe Account 1111111"
}
Response payout.paid_out
{
"livemode": true,
"currency": "MXN",
"method": {
"id": "pytmtd_dePrueba",
"created_at": 1676415729,
"payee_id": "payee_dePrueba",
"_type": "BankTransferPayoutMethod",
"object": "bank_transfer_payout_method",
"account_number": "123456789012345673",
"account_holder": "Jon Doe Account",
"bank": "bancoppel"
},
"object": "transfer",
"amount": 1000,
"id": "abcdefghijklmnopq1111111",
"created_at": 1676415729,
"status": "in_transit",
"statement_reference": "1111111",
"statement_description": "Jon Doe Account 1111111"
}
Prueba tu Webhook
Con Panel. Ingresa al módulo de Desarrolladores en tu Panel, y selecciona Revisar Webhooks en el apartado Webhooks .
Con Ngrok. Consulta nuestra guía: Probar localmente los webhooks con ngrok
Consulta de Dispersión
Dispersión Pagada
Ejemplo:
{
"data": {
"object": {
"livemode": true,
"currency": "MXN",
"method": {
"id": "pytmtd_dePrueba",
"created_at": 1601910621,
"payee_id": "payee_dePrueba",
"_type": "BankTransferPayoutMethod",
"object": "bank_transfer_payout_method",
"account_number": "123456789012345673",
"account_holder": "Jon Doe",
"bank": "BBVA Bancomer, S.A."
},
"object": "transfer",
"amount": 1000,
"id": "abcdefghijklmnopq1111111",
"created_at": 1601910621,
"status": "paid_out",
"statement_reference": "1111111",
"statement_description": "My Company 1111111"
},
"previous_attributes": {
"status": "in_transit"
}
},
"livemode": false,
"webhook_status": "successful",
"webhook_logs": [
{
"id": "webhl_dePrueba",
"url": "https://www.example.com/my_webhook_listener",
"failed_attempts": 0,
"last_http_response_status": 200,
"object": "webhook_log",
"last_attempted_at": 152825
}
],
"id": "abcdefghijklmnopq1111111",
"object": "event",
"type": "payout.paid_out",
"created_at": 1601910621
}
Dispersión Fallida
Ejemplo:
{
"data": {
"object": {
"livemode": true,
"currency": "MXN",
"method": {
"id": "pytmtd_dePrueba",
"created_at": 1601910621,
"payee_id": "payee_dePrueba",
"_type": "BankTransferPayoutMethod",
"object": "bank_transfer_payout_method",
"account_number": "123456789012345678",
"account_holder": "Jon Doe",
"bank": "BBVA Bancomer, S.A."
},
"object": "transfer",
"amount": 676,
"id": "abcdefghijklmnopq1111111",
"created_at": 1601910621,
"status": "failed",
"statement_reference": "1111111",
"statement_description": "My Company 1111111"
},
"previous_attributes": {
"status": "in_transit"
}
},
"livemode": false,
"webhook_status": "successful",
"webhook_logs": [
{
"id": "webhl_dePrueba",
"url": "https://www.example.com/my_webhook_listener",
"failed_attempts": 0,
"last_http_response_status": 200,
"object": "webhook_log",
"last_attempted_at": 152827
}
],
"id": "abcdefghijklmnopq1111111",
"object": "event",
"type": "payout.failed",
"created_at": 16019106
}
Errores
Por medio de nuestra Direct API, podrás ser notificado con toda la información en caso de cualquier error al momento de crear cualquier solicitud de Dispersión a terc.
{
"details": [
{
"debug_message": " ",
"message": " ",
"param": " ",
"code": " "
}
],
"object": "error",
"type": " ",
"log_id": " "
}
Parámetros
Parámetro | Descripción | Tipo |
---|---|---|
object | Contiene el valor "error" | string |
type | Contiene el tipo de error. | string |
log_id | El id del log de la petición http está registrado en este error. | string |
details | Lista detallada de los errores. | array |
debug_message | Mensaje legible para humanos el cual provee más detalles sobre el error. Este mensaje debe ser usado internamente para depuración y solo está disponible en inglés. | string |
message | Mensaje legible para humanos el cual provee más detalles sobre el error. Este mensaje debe ser desplegado al usuario y está disponible en inglés. | string |
params | El parámetro al cual este error está relacionado. Puedes usar este error para subrayar campos de texto erróneos. | string |
code | Un código corto y específico. | string |
Descripción de errores
Tipo | Debug Message | Descripción |
---|---|---|
authentication_error | Unrecognized access key | La llave usada en esta petición era inválida o no tiene permisos para ejecutar esta petición. |
api_error | There was a runtime error and Conekta engineers have been notified. | Error en el valor del campo TYPE. |
processing_error | Insufficient funds | No tiene saldo suficiente para realizar una dispersión a terceros. |
parameter_validation_error | The payee`s account number was invalid, please ensure that it is an 18 digit CLABE. | El campo ACCOUNT NUMBER tiene un valor de CLABE incorrecto. |
parameter_validation_error | The payee could not be found | El payee_id no se encuentra entre los payee creados anteriormente. |
parameter_validation_error | The provided currency is invalid | Error en el valor del campo CURRENCY. |
parameter_validation_error | The transfer amount is required | El monto de la dispersión a terceros debe ser mayor a cero ($0.00 MXN). |
Updated 8 months ago