Clientes del comercio — pagos directos vía SPEI

Guía de integración para el equipo de desarrollo del comercio que va a consumir estos
servicios desde sus propios sistemas: consultar su centro de costos, consultar y dar de
alta clientes para que reciban pagos directos vía SPEI, y una forma de simular un depósito
de principio a fin en un ambiente de pruebas.

1. Flujo general

1. Bidzi registra el centro de costos del comercio como parte del alta inicial — este
   paso lo hace Bidzi, el comercio no lo ejecuta, solo lo consulta.
2. El comercio consulta su centro de costos para confirmar que ya está dado de alta
   antes de empezar a registrar clientes.
3. El comercio registra cada cliente que va a recibir pagos directos. Al registrarlo,
   Bidzi crea automáticamente una cuenta CLABE privada para ese cliente — el comercio
   recibe esa CLABE en la respuesta y es la que debe compartir con su cliente para que
   reciba depósitos.
4. El cliente del comercio hace un depósito SPEI a esa CLABE, desde su banco.
5. Bidzi recibe la notificación del depósito, la registra como transacción, y le entrega al
   comercio un webhook de tipo PAYMENT con los datos del depósito — ver
   tipos-de-eventos.md.

Este documento cubre los pasos 2 y 3, y una forma de simular el paso 4 para probar tu
integración de principio a fin sin esperar un depósito real (sección 5).

2. Autenticación

Todos los endpoints de este documento usan el mismo token que ya usas para el resto de
la API del portal de comercios: un JWT de Cognito, enviado como Authorization: Bearer <jwt>.

Cada token está asociado a un único comercio, así que todas las
operaciones quedan automáticamente acotadas al tuyo.

El usuario debe contar con los permisos necesarios para el acceso a los servicios. Si tu usuario no tiene alguno de estos permisos, Bidzi responde 403. Contacta a tu
contraparte en Bidzi para que los habilite en tu rol.

3. Centro de costos (solo lectura)

Tu comercio no puede registrar ni editar su centro de costos desde esta API — es un
paso de alta que hace Bidzi. Aquí solo lo consultas, normalmente para validar que ya está
listo antes de empezar a registrar clientes.

GET /v1/merchants/cost-center

curl --location 'https://{MERCHANT_API_HOST}/v1/merchants/cost-center' \
--header 'Authorization: Bearer {JWT}'

Respuesta:

Si tu comercio aún no tiene centro de costos registrado, la respuesta es 404
(bidzi.error.cost_center.not_found) — en ese caso, tampoco podrás registrar clientes
todavía (sección 4.3). Contacta a Bidzi para completar ese paso de alta.

4. Clientes de tu comercio

4.1 Listar tus clientes

curl --location 'https://{MERCHANT_API_HOST}/v1/merchants/customers' \
--header 'Authorization: Bearer {JWT}'

GET /v1/merchants/customers — responde un arreglo, cada elemento con la misma forma que
el objeto de la sección 4.3.

4.2 Consultar un cliente puntual

curl --location 'https://{MERCHANT_API_HOST}/v1/merchants/customers/34' \
--header 'Authorization: Bearer {JWT}'

GET /v1/merchants/customers/{customerId} — responde 404
(bidzi.error.merchant_customer.not_found) si ese customerId no pertenece a tu comercio.

4.3 Registrar un cliente nuevo

POST /v1/merchants/customers

Al registrar un cliente, Bidzi crea para él una cuenta CLABE privada asociada al centro de
costos de tu comercio (sección 3) — por eso necesitas tener uno registrado antes de poder
dar de alta clientes.

Body de la petición:

curl --location 'https://{MERCHANT_API_HOST}/v1/merchants/customers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {JWT}' \
--data '{
  "name": "Ernexto Gonzalez",
  "email": "[email protected]",
  "rfc": "XAXX010101000"
}'

Respuesta (201):

{
  "id": 34,
  "merchant_id": 1901,
  "name": "Ernexto Gonzalez",
  "email": "[email protected]",
  "rfc": "XAXX010101000",
  "phone": null,
  "status": "ACTIVE",
  "provider_account_id": "f1f785ba-9bea-445c-b961-2f09b9d73eb4",
  "provider_instrument_id": "374e820b-4c08-4119-a52d-89876f58901c",
  "provider_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "provider_owner_id": "875f449e-be03-4d0c-be36-9307374b02e8",
  "provider_alias": "",
  "provider_account_type": "PRIVATE_ACCOUNT",
  "account_number": "000066472185",
  "clabe_number": "734180000066472185",
  "holder_name": "Ernexto Gonzalez",
  "created_at": "2026-10-05T17:28:58.900884Z",
  "updated_at": "2026-10-05T17:28:58.900884Z"
}

Guarda clabe_number de la respuesta: es la CLABE que debes compartir con tu cliente para
que te pague — es el dato que usarás también para probar la sección 5.

Errores esperables:

5. Probar el flujo completo en tu ambiente de integración

En producción, tú no invocas este paso — es Monato quien le notifica a Bidzi cuando tu
cliente deposita. Pero puedes simular esa notificación en tu ambiente de pruebas para
validar que tu integración completa funciona (recibes el webhook PAYMENT correctamente),
sin esperar un depósito real.

Esta simulación llama a un endpoint distinto, que no es parte de la API del portal de
comercios: lo recibe bidzi-blumonpay-webhooks (POST /v1/webhooks/monato/money-in), con
su propia autenticación (un token fijo por ambiente, no tu JWT de comercio). Bidzi te
proporciona ese token para tu ambiente de pruebas por separado.

curl --location 'https://webhook.dev.bidzi.mx/v1/webhooks/monato/money-in' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN_DE_PRUEBAS}' \
--data '{
  "id_msg": "c61fc828-6188-4176-b3b4-07cf2317c30e",
  "msg_name": "MONEY_IN",
  "msg_date": "2026-10-05",
  "body": {
    "id": "dc4c59ce-1fbc-4a0c-8193-5e87d29a01af",
    "beneficiary_account": "734180000066472185",
    "beneficiary_name": "Ernexto Gonzalez",
    "beneficiary_rfc": "ND",
    "payer_account": "734180000066000007",
    "payer_name": "BIDZI PAGOS Y CUENTAS, S.A.P.I DE C.V. ",
    "payer_rfc": "ND",
    "payer_institution": "90734",
    "amount": "750.00",
    "transaction_date": "2026-10-05 19:20:00",
    "tracking_key": "20261005FINITBMJTEST02",
    "payment_concept": "Pago cliente Ernesto octubre",
    "numeric_reference": "445566",
    "sub_category": "INT_CREDIT",
    "created_at": "2026-10-05T19:20:00.244777-06:00",
    "owner_id": "875f449e-be03-4d0c-be36-9307374b02e8"
  }
}'

{TOKEN_DE_PRUEBAS}=G8kdWKkq4aAHjiVrG6k1fphJpK9ziAel9kpK8muSjpc es un secreto de prueba, solo para simular el depósito a la cuenta CLABE del cliente, esta notificación la realiza el proveedor de servicios de SPEI.
en texto plano fuera del lugar donde Bidzi te lo entregó, ni lo subas a tu repositorio.

Campos que debes ajustar para tu prueba:

• beneficiary_account: el clabe_number exacto del cliente que registraste (sección 4.3).
• owner_id: el owner_id de tu centro de costos (sección 3) — es el mismo para todos tus
  clientes.
• amount, tracking_key, numeric_reference, payment_concept: libres, para
  identificar tu prueba.

Qué validar después de enviarlo:

1. La respuesta es 200 {"message": "OK"}.
2. Recibes en tu webhook configurado un evento {"event_type": "PAYMENT", ...} con el
   deposit_clabe que usaste — forma completa documentada en
   tipos-de-eventos.md.

Si beneficiary_account no coincide con ningún cliente tuyo ya registrado, el depósito se
rechaza silenciosamente (no se genera transacción ni webhook) — revisa que hayas copiado
bien el clabe_number de la sección 4.3.

6. Referencia rápida de errores