Especificación de API - Registro de Comercios

Esta especificación describe el servicio v2-es de Onboarding de comercios, que permite registrar nuevos establecimientos mediante una solicitud.
Incluye los detalles de endpoints, headers requeridos y estructura del mensaje. Este servicio está orientado a integraciones backend en entornos controlados de desarrollo y producción.

Ambiente

Ambiente	Endpoint	Método
Desarrollo	`https://gz9zkw23la.execute-api.us-east-1.amazonaws.com/dev/onboarding/merchant`	`POST`
Producción	(por definir)	`POST`

Headers Requeridos

Cabecera	Valor	Requerido
Content-Type	application/json	SÍ
Authorization	Bearer <Access_Token>	SÍ
payment-facilitator-code	UUID del PF asignado	SÍ

Ejemplo:

CODE

"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi...",
"payment-facilitator-code": "804a8528-36b3-4631-8dfa-bb14c4ef4d95"

Request Body

Campo	Tipo	Longitud	Descripción	Requerido
merchant_name	String	1 - 25 caracteres	Razón Social del Comercio	SÍ
merchant_category_code	String	4 caracteres	MCC principal del comercio	SÍ
company	Object	-	Objeto con información legal y de contacto	SÍ
payment_methods	Array	-	Lista de métodos de pago	SÍ
services	Object	-	Servicios opcionales (tokenización, notificaciones)	No
capture	Array	-	Configuración de captura de pagos	No

COMPANY

Campo	Tipo	Longitud	Descripción	Requerido
company_name	String	Hasta 75 caracteres	Nombre comercial del comercio	SÍ
phone	String	9 - 30	Teléfono del comercio	No
website	String	Hasta 100	Sitio web del comercio	No
location.country	String	Hasta 10	País del comercio	SÍ
location.country_gov	String	2 caracteres	Código ISO del país	SÍ
location.city	String	1 - 29	Ciudad	SÍ
location.state	String	1 - 200	Estado / Departamento	SÍ
location.postal_code	String	1 - 10	Código postal	SÍ
location.address	String	1 - 60	Dirección legal	SÍ
contacts[].contact_type	String	-	Tipo: legal_representative, operational_contact	SÍ
contacts[].name	String	1 - 140	Nombre del contacto	SÍ
contacts[].lastname	String	1 - 140	Apellido del contacto	SÍ
contacts[].document_type	String	-	Tipo de documento	SÍ
contacts[].document_value	String	1 - 12	Número del documento	SÍ
contacts[].work_position	String	1 - 80	Cargo o función	SÍ
contacts[].email	String	-	Email del contacto	SÍ
contacts[].phone	String	9 - 30	Teléfono del contacto	SÍ
tax_information.tax_identification_number	String	11 - 14	RUC o ID fiscal	SÍ (POST)
tax_information.tax_identification_type	String	Hasta 15	Tipo de documento fiscal	SÍ (POST)
tax_information.tax_identification_country	String	2 caracteres	País (código ISO)	SÍ (POST)
tax_information.tax_identification_country_number	String	3 dígitos	Código país numérico	SÍ (POST)
tax_information.tax_category	String	Hasta 50	Categoría fiscal	SÍ (POST)

En PUT, tax_information no se incluye, ya que estos datos no son modificables.

PAYMENT_METHODS

Campo	Tipo	Longitud	Descripción	Requerido
channel	String	-	Canal de ventas (`ecommerce`, `pos`, etc.)	SÍ
code	String	-	Código del método (`CARD`, etc.)	SÍ
currencies[]	Array	3 caracteres	Monedas permitidas (`604`, `840`, etc.)	SÍ
brands[].name	String	-	Marca (ej: `VISA`, `MSCD`)	SÍ
brands[].merchant_category_code	String	4	MCC asociado a la marca	SÍ
brands[].authentication.enabled	Boolean	-	(Opcional) Activar métodos de autenticación	No

📆 Ejemplo de Request

CODE

{
  "merchant_name": "TIENDA DEMO TEST",
  "merchant_category_code": "4565",
  "company": {
    "company_name": "TIENDA DEMO S.A.C.",
    "tax_information": {
      "tax_identification_number": "20999999999",
      "tax_identification_type": "RUC",
      "tax_identification_country": "PE",
      "tax_identification_country_number": "604",
      "tax_category": "Retail"
    },
    "phone": "(+51)900000000",
    "website": "https://demo-tienda.com",
    "email": "contacto@demo-tienda.com",
    "location": {
      "country": "Perú",
      "country_gov": "PE",
      "city": "LIMA",
      "state": "LIMA",
      "postal_code": "15074",
      "address": "Av. Ficticia 999, San Isidro"
    },
    "contacts": [
      {
        "contact_type": "legal_representative",
        "name": "Javier",
        "lastname": "Torres",
        "document_type": "DNI",
        "document_value": "11112222",
        "work_position": "Gerente Legal",
        "email": "j.torres@demo-tienda.com",
        "phone": "(+51)900111111"
      },
      {
        "contact_type": "legal_representative",
        "name": "Lucía",
        "lastname": "Salas",
        "document_type": "DNI",
        "document_value": "33334444",
        "work_position": "Directora Comercial",
        "email": "l.salas@demo-tienda.com",
        "phone": "(+51)900222222"
      }
    ]
  },
  "payment_methods": [
    {
      "channel": "ecommerce",
      "currencies": ["604", "840"],
      "code": "CARD",
      "brands": [
        {
          "name": "VISA",
          "merchant_category_code": "0780"
        },
        {
          "name": "MSCD",
          "merchant_category_code": "0780"
        }
      ]
    }
  ]
}

📥 Ejemplo de Response

CODE

{
  "success": "true",
  "onboarding": {
    "merchant_credentials": {
      "client_id": "demoClient123456789",
      "client_secret": "demoSecret987654321XYZ"
    },
    "merchant_name": "TIENDA DEMO TEST",
    "merchant_code": "f1e2d3c4-b5a6-7890-1234-abcdef123456",
    "merchant_alias": "36049999999",
    "created_at": "2025-07-07T15:04:47.716827",
    "brand_merchant_identifier": "20999999999001",
    "merchant_category_code": "4565",
    "payment_methods_enabled": [
      {
        "method_name": "CARD",
        "processor": "ALIGNET",
        "channels": ["ecommerce"],
        "brands": ["VISA", "MSCD"],
        "currencies": ["840", "604"]
      }
    ],
    "payment_methods_failed": []
  },
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Comercio creado correctamente"
        }
      ]
    }
  }
}

IMPORTANTE: En el método PUT, no se retornan las credenciales (client_id, client_secret) ya que son las mismas generadas al momento del POST.