DocumentaciónAPIDevToolsRecipesForoTarjetas de PruebasEstado del ServicioChangelog
Iniciar Sesión

Generar una Dispersión a Terceros con Direct API

Dispersión a terceros de fondos recibidos en Conekta

Suggest Edits

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ámetroDescripciónTypeValueMandatorio
typeEl tipo de destinatarioStringSiempre colocar "bank_account"Sí
account_numberNúmero de cuenta bancaria (CLABE interbancaria)Integer18 caracteres numéricosSí
account_holder_nameNombre del beneficiarioStringMenos de 250 caracteresSí

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.

1871

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ámetroDescripciónTipo
objectContiene el valor "error"string
typeContiene el tipo de error.string
log_idEl id del log de la petición http está registrado en este error.string
detailsLista detallada de los errores.array
debug_messageMensaje 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
messageMensaje 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
paramsEl parámetro al cual este error está relacionado. Puedes usar este error para subrayar campos de texto erróneos.string
codeUn código corto y específico.string

Descripción de errores

TipoDebug MessageDescripción
authentication_errorUnrecognized access keyLa llave usada en esta petición era inválida o no tiene permisos para ejecutar esta petición.
api_errorThere was a runtime error and Conekta engineers have been notified.Error en el valor del campo TYPE.
processing_errorInsufficient fundsNo tiene saldo suficiente para realizar una dispersión a terceros.
parameter_validation_errorThe 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_errorThe payee could not be foundEl payee_id no se encuentra entre los payee creados anteriormente.
parameter_validation_errorThe provided currency is invalidError en el valor del campo CURRENCY.
parameter_validation_errorThe transfer amount is requiredEl monto de la dispersión a terceros debe ser mayor a cero ($0.00 MXN).

Updated about 2 months ago