advanced-digital-services · adsonrodrigues · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
diff --git a/en/guides/get-started.mdx b/en/guides/get-started.mdx
@@ -25,7 +25,7 @@ The NTX Pay México API lets your company perform payment operations, check bala
       -H "Content-Type: application/json" \
       -d '{
         "url": "https://my-server.com/webhooks/ntxpay",
-        "events": ["cash_in", "cash_out"]
+        "events": ["cash_in"]
       }'
     ```
   </Step>
@@ -38,12 +38,13 @@ The NTX Pay México API lets your company perform payment operations, check bala
     ```bash
     curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \
       -H "Authorization: Bearer $TOKEN" \
-      -H "X-Sandbox-Scenario: cash_in_failed" \
+      -H "X-Sandbox-Scenario: rejected" \
       -H "Content-Type: application/json" \
       -d '{
         "amountCentavos": 50000,
         "externalId": "order-001",
-        "customerName": "Juan Perez"
+        "customerName": "Juan Perez",
+        "customerEmail": "juan@example.com"
       }'
     ```
   </Step>

diff --git a/en/guides/migrating-from-voluti.mdx b/en/guides/migrating-from-voluti.mdx
diff --git a/en/guides/quickstart.mdx b/en/guides/quickstart.mdx
@@ -15,11 +15,9 @@ description: 'Signup, authentication and first SPEI transaction'
 curl -X POST https://sandbox.mx.ntxpay.com/api/signup \
   -H "Content-Type: application/json" \
   -d '{
-    "holderName": "Maria Lopez",
-    "holderTaxIdPrimary": "LOMA850101ABC",
-    "holderTaxIdPrimaryType": "RFC",
-    "accountType": "PF",
     "email": "maria@example.com",
+    "holderName": "Maria Lopez",
+    "entityType": "OTHER",
     "isSandbox": true
   }'
 ```
@@ -47,7 +45,7 @@ curl -X POST https://sandbox.mx.ntxpay.com/api/webhooks-config \
   -H "Content-Type: application/json" \
   -d '{
     "url": "https://my-server.com/webhooks/ntxpay",
-    "events": ["cash_in", "cash_out"]
+    "events": ["cash_in"]
   }'
 ```
 

diff --git a/en/guides/sandbox-testing.mdx b/en/guides/sandbox-testing.mdx
@@ -19,10 +19,9 @@ The **sandbox** is an isolated environment with simulated transactions. Useful f
 curl -X POST https://sandbox.mx.ntxpay.com/api/signup \
   -H "Content-Type: application/json" \
   -d '{
+    "email": "dev@example.com",
     "holderName": "Test",
-    "holderTaxIdPrimary": "TEST850101ABC",
-    "holderTaxIdPrimaryType": "RFC",
-    "accountType": "PF",
+    "entityType": "OTHER",
     "isSandbox": true
   }'
 ```

diff --git a/en/guides/signup.mdx b/en/guides/signup.mdx
@@ -12,8 +12,8 @@ On creation, NTX Pay:
 1. Sets up the account in Keycloak (identity provider)
 2. Applies default limits and fees
 3. Sets the `mainProvider`:
-   - `sandbox` if `isSandbox=true` (simulated transactions)
-   - `smartfastpay` otherwise (production)
+   - `sandbox` if `isSandbox=true` (default — self-service simulated transactions)
+   - `smartfastpay` otherwise (production — **not** self-service; requires KYC onboarding with the team)
 4. Issues OAuth 2.0 credentials (`clientId` + `clientSecret`)
 5. Optionally issues mTLS certificate
 
@@ -27,27 +27,30 @@ On creation, NTX Pay:
 curl -X POST https://sandbox.mx.ntxpay.com/api/signup \
   -H "Content-Type: application/json" \
   -d '{
-    "holderName": "Maria Lopez",
-    "holderTaxIdPrimary": "LOMA850101ABC",
-    "holderTaxIdPrimaryType": "RFC",
-    "accountType": "PF",
     "email": "maria@example.com",
+    "holderName": "Maria Lopez",
+    "entityType": "OTHER",
     "phone": "+5215512345678",
     "isSandbox": true
   }'
 ```
 
-#### Request — Legal Entity (production)
+<Note>
+  In sandbox, `holderTaxIdPrimary` (RFC) is optional — if omitted, a unique test RFC is generated automatically.
+</Note>
+
+#### Request — Legal Entity (`SA_CV` / `SAPI_CV`)
 
 ```bash
 curl -X POST https://sandbox.mx.ntxpay.com/api/signup \
   -H "Content-Type: application/json" \
   -d '{
+    "email": "contact@acme.mx",
     "holderName": "Acme S.A. de C.V.",
+    "entityType": "SA_CV",
+    "razonSocial": "Acme S.A. de C.V.",
     "holderTaxIdPrimary": "ACM850101AB1",
-    "holderTaxIdPrimaryType": "RFC",
-    "accountType": "PJ",
-    "email": "contact@acme.mx"
+    "isSandbox": true
   }'
 ```
 
@@ -76,33 +79,41 @@ curl -X POST https://sandbox.mx.ntxpay.com/api/signup \
 
 ## Request Fields
 
-<ParamField path="holderName" type="string" required>
-  Full name of the holder (minimum 3, maximum 255 characters).
+<ParamField path="email" type="string" required>
+  Contact email — becomes the portal login (owner).
 </ParamField>
 
-<ParamField path="holderTaxIdPrimary" type="string" required>
-  RFC (Individual or Legal Entity) or CURP (Individual). 10–20 characters.
+<ParamField path="holderName" type="string" required>
+  Name / legal name of the account holder (minimum 3, maximum 255 characters).
 </ParamField>
 
-<ParamField path="holderTaxIdPrimaryType" type="enum" required>
-  `RFC` or `CURP`.
+<ParamField path="entityType" type="enum" required>
+  Mexican legal entity type: `SAPI_CV`, `SA_CV` or `OTHER`. `SAPI_CV` and `SA_CV` require `razonSocial`.
 </ParamField>
 
-<ParamField path="accountType" type="enum" required>
-  `PJ` (legal entity) or `PF` (individual).
+<ParamField path="razonSocial" type="string">
+  Legal name (razón social). **Required** when `entityType` is `SAPI_CV` (suffix "S.A.P.I. de C.V.") or `SA_CV` (suffix "S.A. de C.V."). Optional for `OTHER`.
 </ParamField>
 
-<ParamField path="email" type="string">
-  Contact email. Optional, but recommended.
+<ParamField path="holderTaxIdPrimary" type="string">
+  RFC of the holder (10–20 characters). **Optional in sandbox**: if omitted, a unique test RFC is generated automatically.
 </ParamField>
 
 <ParamField path="phone" type="string">
   Phone in E.164 format (8–20 characters). Ex.: `+5215512345678`.
 </ParamField>
 
-<ParamField path="isSandbox" type="boolean" default="false">
-  `true` → sandbox environment account (provider `sandbox`, simulated transactions).
-  `false` → production account (provider `smartfastpay`).
+<ParamField path="isSandbox" type="boolean" default="true">
+  Defaults to **`true`** → self-service sandbox account (provider `sandbox`, simulated transactions).
+  `false` → production account (provider `smartfastpay`) — **not** self-service; requires KYC onboarding with the team.
+</ParamField>
+
+<ParamField path="holderTaxIdPrimaryType" type="enum" deprecated>
+  **Deprecated** — accepted but ignored by the backend (the document type is always RFC). Legal classification comes from `entityType`.
+</ParamField>
+
+<ParamField path="accountType" type="enum" deprecated>
+  **Deprecated** — accepted but ignored by the backend. Use `entityType` instead.
 </ParamField>
 
 ## Sandbox vs Production
@@ -119,7 +130,7 @@ curl -X POST https://sandbox.mx.ntxpay.com/api/signup \
 
 | Code | Cause |
 |---|---|
-| `400` | Invalid RFC/CURP, invalid accountType, or tax ID already in use |
+| `400` | Missing required field (`email`/`holderName`/`entityType`), missing `razonSocial` for `SAPI_CV`/`SA_CV`, invalid RFC, or tax ID already in use |
 | `502` | `account-ms` (provisioning) unavailable — retry |
 
 ## Next Steps