Registro Individual de Comercio (API)

Este servicio permite realizar el proceso de Onboarding de comercios patrocinados por un Payment Facilitator, mediante un registro individual usando un endpoint REST.

⚠️ Si se requiere autorizar con un Token, se debe revisar previamente la documentación: API Token de Acceso.

📶 Ambientes y Endpoint

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`	✔️
`Authorization`	`Bearer <Access_Token>`	✔️
`payment-facilitator-code`	UUID del PF asignado	✔️

Ejemplo:

CODE

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

📢 Request Body — Estructura General

Campo	Tipo	Longitud	Descripción	Req
`merchant_name`	String	1–25	Razón social del comercio	✔️
`merchant_category_code`	String	4	MCC principal	✔️
`company`	Object	-	Datos legales y de contacto	✔️
`payment_methods`	Array	-	Métodos de pago del comercio	✔️
`services`	Object	-	Servicios opcionales	No
`capture`	Array	-	Configuración de captura	No

🏢 company — Detalle del Objeto

Campo	Tipo	Long.	Descripción	Req
`company_name`	String	hasta 75	Nombre comercial	✔️
`phone`	String	9–30	Teléfono	No
`website`	String	hasta 100	Sitio web	No

📍 location

Campo	Long.	Req
`country`	hasta 10	✔️
`country_gov`	2	✔️
`city`	1–29	✔️
`state`	1–200	✔️
`postal_code`	1–10	✔️
`address`	1–60	✔️

👥 contacts[]

Campo	Descripción	Req
`contact_type`	legal_representative / operational_contact	✔️
`name`	Nombre	✔️
`lastname`	Apellido	✔️
`document_type`	Tipo de documento	✔️
`document_value`	1–12	✔️
`work_position`	1–80	✔️
`email`	Email del contacto	✔️
`phone`	9–30	✔️

🧾 tax_information (solo POST)

Campo	Long.	Req
`tax_identification_number`	11–14	✔️
`tax_identification_type`	hasta 15	✔️
`tax_identification_country`	2	✔️
`tax_identification_country_number`	3 dígitos	✔️
`tax_category`	hasta 50	✔️

⚠️ En PUT, tax_information no se envía porque no es modificable.

📈 payment_methods — Detalle

Campo	Tipo	Descripción	Req
`channel`	String	ecommerce, pos, etc.	✔️
`code`	String	CARD, etc.	✔️
`currencies[]`	Array	Monedas permitidas (604, 840…)	✔️
`brands[].name`	String	VISA, MSCD	✔️
`brands[].merchant_category_code`	String (4)	MCC por marca	✔️
`brands[].authentication_enabled`	Boolean	Opcional	No

📆 Ejemplo de Request

CODE

{
  "merchant_name": "COMERCIO LUMIO TEST 4",
  "merchant_category_code": "4565",
  "company": {
    "company_name": "COMERCIO LUMIO TEST",
    "tax_information": {
      "tax_identification_number": "20110892999",
      "tax_identification_type": "RUC",
      "tax_identification_country": "PE",
      "tax_identification_country_number": "604",
      "tax_category": "Retail"
    },
    "phone": "(+51)923456789",
    "website": "https://lumio.com",
    "location": {
      "country": "Perú",
      "country_gov": "PE",
      "city": "LIMA",
      "state": "LIMA",
      "postal_code": "01",
      "address": "Av. Principal 123, Miraflores"
    },
    "contacts": [
      {
        "contact_type": "legal_representative",
        "name": "Carlos",
        "lastname": "Pérez",
        "document_type": "DNI",
        "document_value": "12345678",
        "work_position": "Gerente General",
        "email": "carlos.perez@supertienda.com",
        "phone": "(+51)923456789"
      },
      {
        "contact_type": "legal_representative",
        "name": "María",
        "lastname": "Gómez",
        "document_type": "DNI",
        "document_value": "87654321",
        "work_position": "Jefa de Operaciones",
        "email": "maria.gomez@supertienda.com",
        "phone": "(+51)923456789"
      }
    ]
  },
  "payment_methods": [
    {
      "channel": "ecommerce",
      "currencies": ["604", "840"],
      "code": "CARD",
      "brands": [
        {
          "name": "VISA",
          "merchant_category_code": "0780",
          "authentication_enabled": true
        },
        {
          "name": "MSCD",
          "merchant_category_code": "0780",
          "authentication_enabled": false
        }
      ]
    }
  ]
}

📥 Ejemplo de Response

CODE

{
  "success": "true",
  "onboarding": {
    "merchant_credentials": {
      "client_id": "zldS8MgyQuGg5MMJ1IB607oH3FlFgV",
      "client_secret": "s8bS1kO7a3wxC3nIktZGsRTDCNyJOoRHCIMTSyTd1iK6f9X1UpPWkFhsaKQzUR7F"
    },
    "merchant_name": "COMERCIO LUMIO TEST 4",
    "merchant_code": "5ddd4cd0-5f58-4084-9ec5-210a8c429bae",
    "merchant_alias": "36040082084",
    "created_at": "2025-07-07T15:04:47.716827",
    "brand_merchant_identifier": "20110892999065",
    "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"
        }
      ]
    }
  }
}

ℹ️ Consideración importante en PUT

En modificaciones:

NO se retornan nuevamente client_id y client_secret.
NO se permite modificar tax_information.