diff --git a/api-reference/openapi.json b/api-reference/openapi.json index fb12bdc..80274fc 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "NTX Pay Public API — México", - "description": "API Pública NTX Pay para integração com SPEI (cash-in/cash-out) e OXXO (cash-in) no México. Todos os valores monetários são expressos em centavos MXN.", + "description": "API Pública NTX Pay para integração com SPEI (cash-in/cash-out) no México. Todos os valores monetários são expressos em centavos MXN.", "version": "1.0.0", "contact": {} }, @@ -25,10 +25,6 @@ "name": "SPEI", "description": "Transferências interbancárias instantâneas mexicanas (cash-in via CLABE descartável; cash-out para CLABE)" }, - { - "name": "OXXO", - "description": "Cobrança em dinheiro na rede OXXO (cash-in via boleto/código de barras)" - }, { "name": "Webhooks Config", "description": "Configuração de webhooks para notificações de eventos" @@ -456,86 +452,6 @@ } } }, - "OxxoCashInInputDto": { - "type": "object", - "required": [ - "amountCentavos", - "customerName" - ], - "properties": { - "amountCentavos": { - "type": "integer", - "minimum": 1, - "example": 20000 - }, - "customerName": { - "type": "string", - "minLength": 3, - "maxLength": 255, - "example": "Juan Perez" - }, - "customerTaxId": { - "type": "string", - "minLength": 10, - "maxLength": 20, - "description": "RFC/CURP (opcional)", - "example": "PEPJ800101ABC" - }, - "externalId": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "example": "order-xyz-789" - } - } - }, - "OxxoCashInOutputDto": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "example": 33333 - }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "EXPIRED" - ], - "example": "PENDING" - }, - "barcode": { - "type": "string", - "nullable": true, - "description": "Código de barras OXXO para pagamento no caixa", - "example": "012345678901234567" - }, - "referenceNumerical": { - "type": "string", - "nullable": true, - "description": "Referência numérica OXXO", - "example": "12345-67890" - }, - "checkoutUrl": { - "type": "string", - "nullable": true, - "format": "uri", - "description": "URL do cupom imprimível", - "example": "https://pay.ntxpay.com/oxxo/abc" - }, - "expiresAt": { - "type": "string", - "nullable": true, - "format": "date-time", - "example": "2026-05-20T23:59:59.000Z" - }, - "amountCentavos": { - "type": "integer", - "example": 20000 - } - } - }, "WebhookItemOutputDto": { "type": "object", "properties": { @@ -985,52 +901,6 @@ } } }, - "/api/oxxo/cash-in": { - "post": { - "summary": "Criar cobrança OXXO (cash-in)", - "description": "**Requer Bearer JWT**. Gera código de barras / cupom OXXO para pagamento em dinheiro nas lojas da rede OXXO. Confirmação após a leitura no caixa (delay típico de minutos a horas).", - "operationId": "OxxoCashInController_create", - "tags": [ - "OXXO" - ], - "security": [ - { - "bearer": [] - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OxxoCashInInputDto" - } - } - } - }, - "responses": { - "201": { - "description": "Cobrança OXXO criada (PENDING)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OxxoCashInOutputDto" - } - } - } - }, - "400": { - "description": "Dados inválidos" - }, - "401": { - "description": "Token inválido" - }, - "502": { - "description": "mexico-ms indisponível" - } - } - } - }, "/api/webhooks-config": { "get": { "summary": "Listar webhooks da conta", diff --git a/docs.json b/docs.json index 44cd372..a09e423 100644 --- a/docs.json +++ b/docs.json @@ -79,7 +79,6 @@ "es/endpoints/spei-cash-in", "es/endpoints/spei-cash-out", "es/endpoints/spei-transaction", - "es/endpoints/oxxo-cash-in", "es/endpoints/webhooks-config-list", "es/endpoints/webhooks-config-setup", "es/endpoints/webhooks-config-delete" @@ -134,7 +133,6 @@ "en/endpoints/spei-cash-in", "en/endpoints/spei-cash-out", "en/endpoints/spei-transaction", - "en/endpoints/oxxo-cash-in", "en/endpoints/webhooks-config-list", "en/endpoints/webhooks-config-setup", "en/endpoints/webhooks-config-delete" @@ -197,12 +195,6 @@ "pt-br/endpoints/spei-transaction" ] }, - { - "group": "OXXO", - "pages": [ - "pt-br/endpoints/oxxo-cash-in" - ] - }, { "group": "Webhooks Config", "pages": [ @@ -244,13 +236,13 @@ }, "metadata": { "og:site_name": "Documentação da API NTX Pay México", - "og:title": "Documentação da API NTX Pay México — SPEI e OXXO", - "og:description": "Integração com SPEI (cash-in via CLABE, cash-out) e OXXO (cash-in em dinheiro) através de uma única API.", + "og:title": "Documentação da API NTX Pay México — SPEI", + "og:description": "Integração com SPEI (cash-in via CLABE, cash-out) através de uma única API.", "og:type": "website", "og:locale": "pt_BR", "twitter:card": "summary_large_image", "twitter:title": "Documentação da API NTX Pay México", - "twitter:description": "Integração SPEI e OXXO via API REST." + "twitter:description": "Integração SPEI via API REST." }, "seo": { "indexHiddenPages": false diff --git a/en/endpoints/oxxo-cash-in.mdx b/en/endpoints/oxxo-cash-in.mdx deleted file mode 100644 index b2bb33c..0000000 --- a/en/endpoints/oxxo-cash-in.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: post /api/oxxo/cash-in ---- diff --git a/en/guides/authentication.mdx b/en/guides/authentication.mdx index 53250a2..d7c39cf 100644 --- a/en/guides/authentication.mdx +++ b/en/guides/authentication.mdx @@ -38,7 +38,7 @@ ENCODED_CERT=$(cat client.cert.pem | python3 -c "import sys,urllib.parse; print( #### Request ```bash -curl -X POST https://api.ntxpay.com/api/auth/token \ +curl -X POST https://sandbox.ntxpay.com/api/auth/token \ -H "X-SSL-Client-Cert: $ENCODED_CERT" \ -H "Content-Type: application/json" \ -d '{ @@ -63,7 +63,7 @@ curl -X POST https://api.ntxpay.com/api/auth/token \ Include the `access_token` in all authenticated requests: ```bash -curl -X GET https://api.ntxpay.com/api/balance \ +curl -X GET https://sandbox.ntxpay.com/api/balance \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ``` @@ -95,7 +95,7 @@ const encodedCert = encodeURIComponent(cert); async function getToken(): Promise { const { data } = await axios.post( - 'https://api.ntxpay.com/api/auth/token', + 'https://sandbox.ntxpay.com/api/auth/token', { clientId: process.env.NTXPAY_CLIENT_ID, clientSecret: process.env.NTXPAY_CLIENT_SECRET, diff --git a/en/guides/balance.mdx b/en/guides/balance.mdx index 051abe6..8584afd 100644 --- a/en/guides/balance.mdx +++ b/en/guides/balance.mdx @@ -23,7 +23,7 @@ Authorization: Bearer {token} #### Request ```bash -curl -X GET https://api.ntxpay.com/api/balance \ +curl -X GET https://sandbox.ntxpay.com/api/balance \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ``` @@ -59,7 +59,7 @@ curl -X GET https://api.ntxpay.com/api/balance \ import axios from 'axios'; async function getBalance(token: string) { - const { data } = await axios.get('https://api.ntxpay.com/api/balance', { + const { data } = await axios.get('https://sandbox.ntxpay.com/api/balance', { headers: { Authorization: `Bearer ${token}` }, }); @@ -85,7 +85,7 @@ async function safeSpeiCashOut(amountCentavos: number, token: string, dto: any) ); } - return axios.post('https://api.ntxpay.com/api/spei/cash-out', dto, { + return axios.post('https://sandbox.ntxpay.com/api/spei/cash-out', dto, { headers: { Authorization: `Bearer ${token}` }, }); } diff --git a/en/guides/get-started.mdx b/en/guides/get-started.mdx index c689131..62ce736 100644 --- a/en/guides/get-started.mdx +++ b/en/guides/get-started.mdx @@ -1,6 +1,6 @@ --- title: 'Get Started' -description: 'Welcome to the NTX Pay México API. This guide walks you through the first steps to integrate and start using SPEI and OXXO.' +description: 'Welcome to the NTX Pay México API. This guide walks you through the first steps to integrate and start using SPEI.' --- ## Overview @@ -54,7 +54,7 @@ The NTX Pay México API lets your company perform payment operations, check bala | Environment | URL | Provider | |---|---|---| | Sandbox | `https://sandbox.ntxpay.com` | `sandbox` (simulated transactions) | -| Production | `https://api.ntxpay.com` | `smartfastpay` | +| Production | Provided at onboarding | `smartfastpay` | ## Support diff --git a/en/guides/migrating-from-voluti.mdx b/en/guides/migrating-from-voluti.mdx index f75e6c0..e62b13a 100644 --- a/en/guides/migrating-from-voluti.mdx +++ b/en/guides/migrating-from-voluti.mdx @@ -17,7 +17,7 @@ The NTX Pay México API was designed so that customers coming from **Voluti SPEI | Item | Voluti | NTX Pay | |---|---|---| -| Production host | `api.spei.magenpay.io` | `api.ntxpay.com` | +| Production host | `api.spei.magenpay.io` | Provided at onboarding | | Sandbox host | — | `sandbox.ntxpay.com` | | Versioning | `/api/v1` | `/api` | | Auth header | `Authorization: API_KEY:NONCE:SIGNATURE` | `Authorization: Bearer ` | @@ -51,7 +51,7 @@ curl -X POST https://api.spei.magenpay.io/api/v1/transaction/cashin \ }' # NTX Pay — IDENTICAL payload works -curl -X POST https://api.ntxpay.com/api/spei/cash-in \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-in \ -H "Authorization: Bearer $JWT" \ -d '{ "amount": "100.00", @@ -104,7 +104,7 @@ curl -X POST https://api.spei.magenpay.io/api/v1/transaction/cashout \ }' # NTX Pay — same payload accepted -curl -X POST https://api.ntxpay.com/api/spei/cash-out \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ -H "Authorization: Bearer $JWT" \ -d '{ "amount": "100.00", @@ -124,7 +124,7 @@ The dedicated endpoint keeps 1-to-1 semantics with Voluti's `conciliation`: curl -X GET https://api.spei.magenpay.io/api/v1/transaction/order_abc_123/conciliation # NTX Pay -curl -X GET https://api.ntxpay.com/api/spei/transaction/order_abc_123 \ +curl -X GET https://sandbox.ntxpay.com/api/spei/transaction/order_abc_123 \ -H "Authorization: Bearer $JWT" ``` @@ -196,7 +196,7 @@ Details in [Webhook Implementation](/en/guides/webhooks/implementation). Replace the HMAC header assembly with the `POST /api/auth/token` flow (cert + clientId/clientSecret) → cache the JWT for ~10 minutes. - From `api.spei.magenpay.io` → `api.ntxpay.com`. Payloads remain the same (aliases accepted). + From `api.spei.magenpay.io` → your NTX Pay production host (provided at onboarding). Payloads remain the same (aliases accepted). Create 1 or more `POST /api/webhooks-config`. Adjust your handler to validate the NTX Pay HMAC (header `X-NTXPay-Signature`). diff --git a/en/guides/oxxo-cash-in.mdx b/en/guides/oxxo-cash-in.mdx deleted file mode 100644 index f7ed4ff..0000000 --- a/en/guides/oxxo-cash-in.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: 'OXXO Cash-In' -description: 'Cash payment in the OXXO network via barcode / voucher' ---- - -## Overview - -**OXXO cash-in** generates a **barcode / voucher** that the payer prints or shows on their phone and takes to any **OXXO** store in México to pay in cash. After scanning at the register, NTX Pay receives confirmation and triggers the `cash_in` webhook. - -Characteristics: - -- **Offline** payment (physical OXXO store) -- **Delayed** confirmation — can take minutes to a few hours after payment -- Expires on configurable date (default ~7 days) - -## Endpoint - -### POST /api/oxxo/cash-in - -#### Headers - -``` -Authorization: Bearer {token} -Content-Type: application/json -``` - -#### Request - -```bash -curl -X POST https://api.ntxpay.com/api/oxxo/cash-in \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "amountCentavos": 20000, - "customerName": "Juan Perez", - "customerTaxId": "PEPJ800101ABC", - "externalId": "order-xyz-789" - }' -``` - -#### Response (201) - -```json -{ - "id": 33333, - "status": "PENDING", - "barcode": "012345678901234567", - "referenceNumerical": "12345-67890", - "checkoutUrl": "https://pay.ntxpay.com/oxxo/abc", - "expiresAt": "2026-05-20T23:59:59.000Z", - "amountCentavos": 20000 -} -``` - -## Request Fields - - - Value in MXN centavos (minimum 1). Ex.: `20000` = $200.00 MXN. - - - - Payer name (3–255 characters). Appears on the voucher. - - - - Payer RFC/CURP (10–20 characters). - - - - External identifier (up to 100 characters). Recommended for idempotency. - - -## What to show the payer - -The response includes three representations of the same charge: - -- **`barcode`** — barcode as string. Generate the image using a local lib (`bwip-js`, `python-barcode`, etc.). -- **`referenceNumerical`** — human-readable reference number for register entry. -- **`checkoutUrl`** — public URL with printable voucher ready. - -Recommendation: show the `checkoutUrl` (visual ready) or generate the `barcode` image in your app. - -## Flow - -```mermaid -sequenceDiagram - participant App as Your application - participant NTX as NTX Pay - participant Payer - participant OXXO as OXXO store - - App->>NTX: POST /api/oxxo/cash-in - NTX-->>App: 201 + barcode + checkoutUrl - App->>Payer: Voucher/code - Payer->>OXXO: Cash payment - OXXO-->>NTX: Confirmation (async, may take hours) - NTX->>App: webhook cash_in (CONFIRMED) -``` - -## States - -| Status | Meaning | -|---|---| -| `PENDING` | Charge issued, waiting for OXXO payment | -| `CONFIRMED` | Payment received and confirmed | -| `EXPIRED` | Charge expired unpaid | - -## Considerations - - - OXXO confirmation is **not real-time**. Don't show the product as "paid" before the `cash_in` webhook. For experiences that require immediate confirmation, prefer SPEI cash-in. - - -- The `barcode` is unique per charge and cannot be reused -- OXXO has a maximum limit of ~$10,000 MXN per transaction (varies by store) -- Partial payments not allowed — payer pays the exact voucher amount - -## Next Steps - - - - Receive async payment confirmation - - - For immediate confirmation, use SPEI - - diff --git a/en/guides/postman-collections.mdx b/en/guides/postman-collections.mdx index bcf1efe..a7ef0a6 100644 --- a/en/guides/postman-collections.mdx +++ b/en/guides/postman-collections.mdx @@ -48,7 +48,6 @@ The collection is organized in typical usage order: - `Signup` — account creation - `Balance` — balance query - `SPEI` — cash-in, cash-out, transaction by external ID -- `OXXO` — cash-in - `Transactions` — list - `Webhooks Config` — list, create, delete diff --git a/en/guides/quickstart.mdx b/en/guides/quickstart.mdx index 8f9a0e8..1c3ebf8 100644 --- a/en/guides/quickstart.mdx +++ b/en/guides/quickstart.mdx @@ -73,6 +73,6 @@ Returns `destinationClabe`. The payer transfers to that CLABE; confirmation arri | Environment | URL | Provider | |---|---|---| | Sandbox | `https://sandbox.ntxpay.com` | `sandbox` (simulated transactions) | -| Production | `https://api.ntxpay.com` | `smartfastpay` | +| Production | Provided at onboarding | `smartfastpay` | Sandbox account: `isSandbox: true` in signup. diff --git a/en/guides/sandbox-testing.mdx b/en/guides/sandbox-testing.mdx index 208f170..715aeae 100644 --- a/en/guides/sandbox-testing.mdx +++ b/en/guides/sandbox-testing.mdx @@ -1,6 +1,6 @@ --- title: 'Sandbox' -description: 'Simulate SPEI and OXXO scenarios with no cost or production risk' +description: 'Simulate SPEI scenarios with no cost or production risk' --- ## What it is @@ -36,7 +36,6 @@ curl -X POST https://sandbox.ntxpay.com/api/signup \ |---|---|---| | Provider | `sandbox` | `smartfastpay` | | SPEI cash-in confirmation | **Immediate** (~seconds) | Real (seconds to minutes) | -| OXXO cash-in confirmation | **Immediate** | After register payment (minutes to hours) | | SPEI cash-out | Settles immediately | Real Banxico settlement | | Webhooks | Same format | Same format | | Cost | Free | Per contract | @@ -90,9 +89,9 @@ In sandbox, specific `amountCentavos` values can trigger special behaviors (cons When comfortable: -1. Create a **new account** at `https://api.ntxpay.com/api/signup` **without** `isSandbox` +1. Create a **new account** via `POST /api/signup` on your production host (provided at onboarding) **without** `isSandbox` 2. Only change: - - Host: `sandbox.ntxpay.com` → `api.ntxpay.com` + - Host: `sandbox.ntxpay.com` → production host (provided at onboarding) - Credentials (`clientId`/`clientSecret`) - X.509 certificate (production is distinct from sandbox) 3. Reconfigure webhooks on the production account diff --git a/en/guides/signup.mdx b/en/guides/signup.mdx index 9ce2c05..0583331 100644 --- a/en/guides/signup.mdx +++ b/en/guides/signup.mdx @@ -40,7 +40,7 @@ curl -X POST https://sandbox.ntxpay.com/api/signup \ #### Request — Legal Entity (production) ```bash -curl -X POST https://api.ntxpay.com/api/signup \ +curl -X POST https://sandbox.ntxpay.com/api/signup \ -H "Content-Type: application/json" \ -d '{ "holderName": "Acme S.A. de C.V.", @@ -111,10 +111,9 @@ curl -X POST https://api.ntxpay.com/api/signup \ |---|---|---| | Provider | `sandbox` | `smartfastpay` | | SPEI confirmation | Immediate (simulated) | Real (seconds to minutes via Banxico) | -| OXXO confirmation | Immediate | After payment in store (minutes to hours) | | Cost | Free | Tariffs in production | | Limits | Permissive | Per contract | -| Base endpoint | `https://sandbox.ntxpay.com` | `https://api.ntxpay.com` | +| Base endpoint | `https://sandbox.ntxpay.com` | Provided at onboarding | ## Common Errors diff --git a/en/guides/spei-cash-in.mdx b/en/guides/spei-cash-in.mdx index 78deb02..3ceb10b 100644 --- a/en/guides/spei-cash-in.mdx +++ b/en/guides/spei-cash-in.mdx @@ -27,7 +27,7 @@ Content-Type: application/json #### Request ```bash -curl -X POST https://api.ntxpay.com/api/spei/cash-in \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-in \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ diff --git a/en/guides/spei-cash-out.mdx b/en/guides/spei-cash-out.mdx index 20f7666..4ea7224 100644 --- a/en/guides/spei-cash-out.mdx +++ b/en/guides/spei-cash-out.mdx @@ -21,7 +21,7 @@ Content-Type: application/json #### Request ```bash -curl -X POST https://api.ntxpay.com/api/spei/cash-out \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -105,7 +105,7 @@ if (balance.availableCentavos < amountCentavos) { async function speiCashOut(token: string, dto: any) { try { const { data } = await axios.post( - 'https://api.ntxpay.com/api/spei/cash-out', + 'https://sandbox.ntxpay.com/api/spei/cash-out', dto, { headers: { Authorization: `Bearer ${token}` } }, ); diff --git a/en/guides/transactions-list.mdx b/en/guides/transactions-list.mdx index 2522d2c..0a9113c 100644 --- a/en/guides/transactions-list.mdx +++ b/en/guides/transactions-list.mdx @@ -1,11 +1,11 @@ --- title: 'List Transactions' -description: 'Query the unified SPEI + OXXO history of your account' +description: 'Query the SPEI history of your account' --- ## Overview -`GET /api/transactions` returns the paginated list of transactions for the authenticated account, unifying **SPEI** and **OXXO** (cash-in, cash-out, refund-in, refund-out, internal_transfer). It's the source of truth when you need to **reconcile** or check status without depending on webhooks. +`GET /api/transactions` returns the paginated list of transactions for the authenticated account, covering **SPEI** (cash-in, cash-out, refund-in, refund-out, internal_transfer). It's the source of truth when you need to **reconcile** or check status without depending on webhooks. **Rate limit**: 30 requests per minute, per account. Above that, `429`. @@ -28,13 +28,13 @@ Authorization: Bearer {token} | `limit` | int (1–100) | 20 | Items per page | | `offset` | int (≥0) | 0 | Pagination offset | | `status` | enum | — | `PENDING`, `CONFIRMED`, `FAILED`, `EXPIRED` | -| `paymentMethod` | enum | — | `SPEI`, `OXXO` | +| `paymentMethod` | enum | — | `SPEI` | | `direction` | enum | — | `in` (received), `out` (sent) | #### Request ```bash -curl -X GET "https://api.ntxpay.com/api/transactions?status=CONFIRMED&paymentMethod=SPEI&limit=50" \ +curl -X GET "https://sandbox.ntxpay.com/api/transactions?status=CONFIRMED&paymentMethod=SPEI&limit=50" \ -H "Authorization: Bearer $TOKEN" ``` @@ -75,7 +75,7 @@ let offset = 0; const limit = 50; while (true) { - const { data } = await axios.get('https://api.ntxpay.com/api/transactions', { + const { data } = await axios.get('https://sandbox.ntxpay.com/api/transactions', { headers: { Authorization: `Bearer ${token}` }, params: { limit, offset, status: 'CONFIRMED' }, }); diff --git a/en/guides/webhooks/cash-in.mdx b/en/guides/webhooks/cash-in.mdx index 0bf55ee..1585673 100644 --- a/en/guides/webhooks/cash-in.mdx +++ b/en/guides/webhooks/cash-in.mdx @@ -1,6 +1,6 @@ --- title: 'cash_in event' -description: 'Notification sent when a SPEI or OXXO cash-in is confirmed' +description: 'Notification sent when a SPEI cash-in is confirmed' --- ## When it fires @@ -8,7 +8,6 @@ description: 'Notification sent when a SPEI or OXXO cash-in is confirmed' The `cash_in` event fires when: - A SPEI transfer arrives at the **disposable CLABE** issued by `POST /api/spei/cash-in` and is settled -- An OXXO payment issued by `POST /api/oxxo/cash-in` is paid at the register and confirmed ## Payload @@ -42,15 +41,6 @@ The `cash_in` event fires when: | `X-NTXPay-Timestamp` | Unix epoch (seconds) | | `X-NTXPay-Delivery` | unique delivery UUID | -## SPEI vs OXXO Differences - -| Aspect | SPEI | OXXO | -|---|---|---| -| `paymentMethod` | `SPEI` | `OXXO` | -| `clabe` | Source CLABE | `null` | -| Time to confirmation | Seconds to minutes | Minutes to hours after paying at register | -| Additional identifier | `referenceNumerical` | `referenceNumerical` | - ## Expected Response Respond `200 OK` in under 10 seconds. On any other status, NTX Pay retries up to 5 times in exponential backoff. diff --git a/en/guides/webhooks/overview.mdx b/en/guides/webhooks/overview.mdx index c868c8b..191d4d7 100644 --- a/en/guides/webhooks/overview.mdx +++ b/en/guides/webhooks/overview.mdx @@ -1,6 +1,6 @@ --- title: 'Webhooks Overview' -description: 'Automatic notifications for SPEI and OXXO events' +description: 'Automatic notifications for SPEI events' --- ## What are Webhooks @@ -11,7 +11,7 @@ Webhooks let NTX Pay send HTTPS notifications to your server whenever a relevant | Event | When it fires | |---|---| -| `cash_in` | SPEI cash-in confirmed **or** OXXO cash-in paid at the register | +| `cash_in` | SPEI cash-in confirmed | | `cash_out` | SPEI cash-out settled | | `refund_in` | **Received** refund (one of your cash-outs was returned) | | `refund_out` | **Sent** refund (you refunded a cash-in) | diff --git a/en/guides/webhooks/refund-out.mdx b/en/guides/webhooks/refund-out.mdx index 0b0ba93..2fe93b8 100644 --- a/en/guides/webhooks/refund-out.mdx +++ b/en/guides/webhooks/refund-out.mdx @@ -11,7 +11,6 @@ Common scenarios: - You triggered a refund for fraud or error - Customer requested cancellation within the SPEI deadline -- OXXO dispute in which NTX Pay returns the value ## Payload diff --git a/en/guides/webhooks/setup.mdx b/en/guides/webhooks/setup.mdx index 61d0c51..2fb6d64 100644 --- a/en/guides/webhooks/setup.mdx +++ b/en/guides/webhooks/setup.mdx @@ -1,6 +1,6 @@ --- title: 'Webhook Setup' -description: 'Configure webhook URLs programmatically for SPEI and OXXO' +description: 'Configure webhook URLs programmatically for SPEI' --- ## Overview @@ -16,7 +16,7 @@ Webhook configuration goes through three endpoints: ### Request ```bash -curl -X POST https://api.ntxpay.com/api/webhooks-config \ +curl -X POST https://sandbox.ntxpay.com/api/webhooks-config \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -59,7 +59,7 @@ curl -X POST https://api.ntxpay.com/api/webhooks-config \ ## List Webhooks ```bash -curl -X GET https://api.ntxpay.com/api/webhooks-config \ +curl -X GET https://sandbox.ntxpay.com/api/webhooks-config \ -H "Authorization: Bearer $TOKEN" ``` @@ -86,7 +86,7 @@ curl -X GET https://api.ntxpay.com/api/webhooks-config \ ## Remove Webhook ```bash -curl -X DELETE https://api.ntxpay.com/api/webhooks-config/42 \ +curl -X DELETE https://sandbox.ntxpay.com/api/webhooks-config/42 \ -H "Authorization: Bearer $TOKEN" ``` diff --git a/en/index.mdx b/en/index.mdx index 22a2a1d..b2a4fc5 100644 --- a/en/index.mdx +++ b/en/index.mdx @@ -1,16 +1,16 @@ --- title: 'NTX Pay México API' -description: 'SPEI and OXXO integration in a single API' +description: 'SPEI integration in a single API' --- -Public gateway for SPEI (instant interbank transfers) and OXXO (cash payments) integration. Receive via SPEI or OXXO, send via SPEI, query balance and transactions, receive signed webhooks. +Public gateway for SPEI (instant interbank transfers) integration. Receive and send via SPEI, query balance and transactions, receive signed webhooks. ## Environments | Environment | URL | |---|---| | Sandbox | `https://sandbox.ntxpay.com` | -| Production | `https://api.ntxpay.com` | +| Production | Provided at onboarding | ## Authentication @@ -50,9 +50,6 @@ ISO 8601 UTC: `2026-05-12T14:31:05.000Z`. Cash-in and cash-out via CLABE - - Cash-in in cash - HMAC notifications diff --git a/en/sandbox/introduction.mdx b/en/sandbox/introduction.mdx index 16620a2..2795606 100644 --- a/en/sandbox/introduction.mdx +++ b/en/sandbox/introduction.mdx @@ -22,7 +22,7 @@ Your API credentials are **structurally the same** as those you would use in pro |---|---| | Sandbox | `https://sandbox.ntxpay.com` | -All documented routes (`/api/auth/token`, `/api/spei/cash-in`, `/api/spei/cash-out`, `/api/oxxo/cash-in`, `/api/transactions`, `/api/webhooks-config`) are available exactly at this host. +All documented routes (`/api/auth/token`, `/api/spei/cash-in`, `/api/spei/cash-out`, `/api/transactions`, `/api/webhooks-config`) are available exactly at this host. ## Test scenarios @@ -36,7 +36,7 @@ Register your `webhookUrl` on the sandbox account exactly as you would in produc | Aspect | Sandbox | Production | |---|---|---| -| Base URL | `https://sandbox.ntxpay.com` | `https://api.ntxpay.com` | +| Base URL | `https://sandbox.ntxpay.com` | Provided at onboarding | | Provider | `sandbox` (simulated) | Real bank (Banxico/SPEI) | | Balance | Simulated | Real funds | | SPEI cash-in confirmation | Immediate (~1s) | Real (seconds to minutes) | diff --git a/en/sandbox/scenarios.mdx b/en/sandbox/scenarios.mdx index 53b062a..15f6e81 100644 --- a/en/sandbox/scenarios.mdx +++ b/en/sandbox/scenarios.mdx @@ -6,7 +6,7 @@ mode: 'wide' ## How to use -Add the header `X-Sandbox-Scenario: ` to any cash-in, cash-out, or OXXO call. Without the header, the sandbox uses the `success` scenario by default. +Add the header `X-Sandbox-Scenario: ` to any cash-in or cash-out call. Without the header, the sandbox uses the `success` scenario by default. ```bash curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ @@ -44,7 +44,6 @@ curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ | `error:account-blocked` | `201 PENDING` | `FAILED` with `errorCode: ACCOUNT_BLOCKED` | | `error:duplicate-external-id` | `201 PENDING` | `FAILED` with `errorCode: DUPLICATE_EXTERNAL_ID` | | `error:bank-rejected` | `201 PENDING` | `FAILED` with `errorCode: BANK_REJECTED` | -| `error:oxxo-expired` | `201 PENDING` | `EXPIRED` (OXXO only) | ### Delay scenarios diff --git a/es/endpoints/oxxo-cash-in.mdx b/es/endpoints/oxxo-cash-in.mdx deleted file mode 100644 index b2bb33c..0000000 --- a/es/endpoints/oxxo-cash-in.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: post /api/oxxo/cash-in ---- diff --git a/es/guides/authentication.mdx b/es/guides/authentication.mdx index 5dc0a10..c9e6358 100644 --- a/es/guides/authentication.mdx +++ b/es/guides/authentication.mdx @@ -38,7 +38,7 @@ ENCODED_CERT=$(cat client.cert.pem | python3 -c "import sys,urllib.parse; print( #### Request ```bash -curl -X POST https://api.ntxpay.com/api/auth/token \ +curl -X POST https://sandbox.ntxpay.com/api/auth/token \ -H "X-SSL-Client-Cert: $ENCODED_CERT" \ -H "Content-Type: application/json" \ -d '{ @@ -63,7 +63,7 @@ curl -X POST https://api.ntxpay.com/api/auth/token \ Incluye el `access_token` en todas las requests autenticadas: ```bash -curl -X GET https://api.ntxpay.com/api/balance \ +curl -X GET https://sandbox.ntxpay.com/api/balance \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ``` @@ -95,7 +95,7 @@ const encodedCert = encodeURIComponent(cert); async function getToken(): Promise { const { data } = await axios.post( - 'https://api.ntxpay.com/api/auth/token', + 'https://sandbox.ntxpay.com/api/auth/token', { clientId: process.env.NTXPAY_CLIENT_ID, clientSecret: process.env.NTXPAY_CLIENT_SECRET, diff --git a/es/guides/balance.mdx b/es/guides/balance.mdx index ce037f7..baa2de1 100644 --- a/es/guides/balance.mdx +++ b/es/guides/balance.mdx @@ -23,7 +23,7 @@ Authorization: Bearer {token} #### Request ```bash -curl -X GET https://api.ntxpay.com/api/balance \ +curl -X GET https://sandbox.ntxpay.com/api/balance \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ``` @@ -59,7 +59,7 @@ curl -X GET https://api.ntxpay.com/api/balance \ import axios from 'axios'; async function getBalance(token: string) { - const { data } = await axios.get('https://api.ntxpay.com/api/balance', { + const { data } = await axios.get('https://sandbox.ntxpay.com/api/balance', { headers: { Authorization: `Bearer ${token}` }, }); @@ -85,7 +85,7 @@ async function safeSpeiCashOut(amountCentavos: number, token: string, dto: any) ); } - return axios.post('https://api.ntxpay.com/api/spei/cash-out', dto, { + return axios.post('https://sandbox.ntxpay.com/api/spei/cash-out', dto, { headers: { Authorization: `Bearer ${token}` }, }); } diff --git a/es/guides/get-started.mdx b/es/guides/get-started.mdx index 84050e1..91f3f16 100644 --- a/es/guides/get-started.mdx +++ b/es/guides/get-started.mdx @@ -1,6 +1,6 @@ --- title: 'Get Started' -description: 'Bienvenido a la API NTX Pay México. Esta guía te lleva por los primeros pasos para integrar y comenzar a usar SPEI y OXXO.' +description: 'Bienvenido a la API NTX Pay México. Esta guía te lleva por los primeros pasos para integrar y comenzar a usar SPEI.' --- ## Overview @@ -54,7 +54,7 @@ La API NTX Pay México permite que tu empresa realice operaciones de pago, consu | Ambiente | URL | Provider | |---|---|---| | Sandbox | `https://sandbox.ntxpay.com` | `sandbox` (transacciones simuladas) | -| Producción | `https://api.ntxpay.com` | `smartfastpay` | +| Producción | Provista en el onboarding | `smartfastpay` | ## Soporte diff --git a/es/guides/migrating-from-voluti.mdx b/es/guides/migrating-from-voluti.mdx index 679ce2d..ebe3365 100644 --- a/es/guides/migrating-from-voluti.mdx +++ b/es/guides/migrating-from-voluti.mdx @@ -17,7 +17,7 @@ La API NTX Pay México fue diseñada para que clientes provenientes de **Voluti | Item | Voluti | NTX Pay | |---|---|---| -| Host producción | `api.spei.magenpay.io` | `api.ntxpay.com` | +| Host producción | `api.spei.magenpay.io` | Provista en el onboarding | | Host sandbox | — | `sandbox.ntxpay.com` | | Versionado | `/api/v1` | `/api` | | Auth header | `Authorization: API_KEY:NONCE:SIGNATURE` | `Authorization: Bearer ` | @@ -51,7 +51,7 @@ curl -X POST https://api.spei.magenpay.io/api/v1/transaction/cashin \ }' # NTX Pay — payload IDÉNTICO funciona -curl -X POST https://api.ntxpay.com/api/spei/cash-in \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-in \ -H "Authorization: Bearer $JWT" \ -d '{ "amount": "100.00", @@ -104,7 +104,7 @@ curl -X POST https://api.spei.magenpay.io/api/v1/transaction/cashout \ }' # NTX Pay — mismo payload aceptado -curl -X POST https://api.ntxpay.com/api/spei/cash-out \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ -H "Authorization: Bearer $JWT" \ -d '{ "amount": "100.00", @@ -124,7 +124,7 @@ El endpoint dedicado mantiene semántica 1-a-1 con el `conciliation` de Voluti: curl -X GET https://api.spei.magenpay.io/api/v1/transaction/order_abc_123/conciliation # NTX Pay -curl -X GET https://api.ntxpay.com/api/spei/transaction/order_abc_123 \ +curl -X GET https://sandbox.ntxpay.com/api/spei/transaction/order_abc_123 \ -H "Authorization: Bearer $JWT" ``` @@ -196,7 +196,7 @@ Detalles en [Implementación de Webhook](/es/guides/webhooks/implementation). Sustituye la construcción del header HMAC por el flujo `POST /api/auth/token` (cert + clientId/clientSecret) → guarda el JWT por ~10 minutos. - De `api.spei.magenpay.io` → `api.ntxpay.com`. Los payloads siguen iguales (aliases aceptados). + De `api.spei.magenpay.io` → tu host de producción NTX Pay (provisto en el onboarding). Los payloads siguen iguales (aliases aceptados). Crea 1 o más `POST /api/webhooks-config`. Ajusta tu handler para validar el HMAC NTX Pay (header `X-NTXPay-Signature`). diff --git a/es/guides/oxxo-cash-in.mdx b/es/guides/oxxo-cash-in.mdx deleted file mode 100644 index 4662c84..0000000 --- a/es/guides/oxxo-cash-in.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: 'OXXO Cash-In' -description: 'Cobro en efectivo en la red OXXO vía código de barras / cupón' ---- - -## Visión General - -El **OXXO cash-in** genera un **código de barras / cupón** que el pagador imprime o muestra en el celular y lleva a cualquier tienda de la red **OXXO** en México para pagar en efectivo. Tras la lectura en caja, NTX Pay recibe la confirmación y dispara el webhook `cash_in`. - -Características: - -- Pago **off-line** (tienda física OXXO) -- Confirmación **tardía** — puede tomar minutos a algunas horas tras el pago -- Expira en fecha configurable (default ~7 días) - -## Endpoint - -### POST /api/oxxo/cash-in - -#### Headers - -``` -Authorization: Bearer {token} -Content-Type: application/json -``` - -#### Request - -```bash -curl -X POST https://api.ntxpay.com/api/oxxo/cash-in \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "amountCentavos": 20000, - "customerName": "Juan Perez", - "customerTaxId": "PEPJ800101ABC", - "externalId": "order-xyz-789" - }' -``` - -#### Response (201) - -```json -{ - "id": 33333, - "status": "PENDING", - "barcode": "012345678901234567", - "referenceNumerical": "12345-67890", - "checkoutUrl": "https://pay.ntxpay.com/oxxo/abc", - "expiresAt": "2026-05-20T23:59:59.000Z", - "amountCentavos": 20000 -} -``` - -## Campos del Request - - - Valor en centavos MXN (mínimo 1). Ej.: `20000` = $200.00 MXN. - - - - Nombre del pagador (3–255 caracteres). Aparece en el cupón. - - - - RFC/CURP del pagador (10–20 caracteres). - - - - Identificador externo (hasta 100 caracteres). Recomendado para idempotencia. - - -## Qué mostrar al pagador - -La respuesta trae tres representaciones del mismo cobro: - -- **`barcode`** — código de barras en string. Genera la imagen usando una lib local (`bwip-js`, `python-barcode`, etc.). -- **`referenceNumerical`** — número de referencia legible para teclear en caja. -- **`checkoutUrl`** — URL pública con cupón imprimible listo. - -Recomendación: muestra el `checkoutUrl` (visual ya listo) o genera la imagen del `barcode` en tu app. - -## Flujo - -```mermaid -sequenceDiagram - participant App as Tu aplicación - participant NTX as NTX Pay - participant Pagador - participant OXXO as Tienda OXXO - - App->>NTX: POST /api/oxxo/cash-in - NTX-->>App: 201 + barcode + checkoutUrl - App->>Pagador: Cupón/código - Pagador->>OXXO: Pago en efectivo - OXXO-->>NTX: Confirmación (asíncrona, puede demorar horas) - NTX->>App: webhook cash_in (CONFIRMED) -``` - -## Estados - -| Status | Significado | -|---|---| -| `PENDING` | Cobro emitido, esperando pago en OXXO | -| `CONFIRMED` | Pago recibido y confirmado | -| `EXPIRED` | Cobro expiró sin ser pagado | - -## Consideraciones - - - La confirmación OXXO **no es en tiempo real**. No muestres el producto como "pagado" antes del webhook `cash_in`. Para experiencias que requieren confirmación inmediata, prefiere SPEI cash-in. - - -- El `barcode` es único por cobro y no puede reutilizarse -- OXXO tiene límite máximo de ~$10 000 MXN por transacción (varía por tienda) -- No se puede pagar parcial — el pagador paga el monto exacto del cupón - -## Próximos Pasos - - - - Recibe confirmación asíncrona del pago - - - Para confirmación inmediata, usa SPEI - - diff --git a/es/guides/postman-collections.mdx b/es/guides/postman-collections.mdx index 971da2d..1d44f02 100644 --- a/es/guides/postman-collections.mdx +++ b/es/guides/postman-collections.mdx @@ -48,7 +48,6 @@ La colección está organizada en el orden de uso típico: - `Signup` — creación de cuenta - `Balance` — consulta de saldo - `SPEI` — cash-in, cash-out, transaction by external ID -- `OXXO` — cash-in - `Transactions` — listar - `Webhooks Config` — listar, crear, eliminar diff --git a/es/guides/quickstart.mdx b/es/guides/quickstart.mdx index 465a2f6..a7691cb 100644 --- a/es/guides/quickstart.mdx +++ b/es/guides/quickstart.mdx @@ -73,6 +73,6 @@ Retorna `destinationClabe`. El pagador transfiere a esa CLABE; la confirmación | Ambiente | URL | Provider | |---|---|---| | Sandbox | `https://sandbox.ntxpay.com` | `sandbox` (transacciones simuladas) | -| Producción | `https://api.ntxpay.com` | `smartfastpay` | +| Producción | Provista en el onboarding | `smartfastpay` | Cuenta sandbox: `isSandbox: true` en el signup. diff --git a/es/guides/sandbox-testing.mdx b/es/guides/sandbox-testing.mdx index 9a6ffbe..3b04b21 100644 --- a/es/guides/sandbox-testing.mdx +++ b/es/guides/sandbox-testing.mdx @@ -1,6 +1,6 @@ --- title: 'Sandbox Testing' -description: 'Cómo usar el ambiente sandbox del NTX Pay México para simular escenarios SPEI y OXXO sin costo ni riesgo de producción.' +description: 'Cómo usar el ambiente sandbox del NTX Pay México para simular escenarios SPEI sin costo ni riesgo de producción.' --- ## What is Sandbox? @@ -16,7 +16,7 @@ El sandbox es un **modo de operación** de tu cuenta — no un ambiente separado | Aspecto | Sandbox | Producción | |---|---|---| -| Base URL | `https://api.ntxpay.com` (misma) | `https://api.ntxpay.com` | +| Base URL | `https://sandbox.ntxpay.com` | Provista en el onboarding | | Cuenta | Dedicada de sandbox | Dedicada de producción | | Credenciales | Certificado + `clientId`/`clientSecret` propios | Certificado + credenciales propios | | Saldo | Simulado | Fondos reales | @@ -68,7 +68,7 @@ El header **no altera la respuesta HTTP**. La API siempre responde `201 Created` ```bash cURL -curl -X POST https://api.ntxpay.com/api/spei/cash-out \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ -H "Authorization: Bearer $TOKEN" \ -H "X-Sandbox-Scenario: error:insufficient-funds" \ -H "Content-Type: application/json" \ @@ -82,7 +82,7 @@ curl -X POST https://api.ntxpay.com/api/spei/cash-out \ ```javascript JavaScript const response = await axios.post( - 'https://api.ntxpay.com/api/spei/cash-out', + 'https://sandbox.ntxpay.com/api/spei/cash-out', { amountCentavos: 15000, destinationClabe: '012180001234567890', @@ -100,7 +100,7 @@ const response = await axios.post( ```python Python response = requests.post( - "https://api.ntxpay.com/api/spei/cash-out", + "https://sandbox.ntxpay.com/api/spei/cash-out", json={ "amountCentavos": 15000, "destinationClabe": "012180001234567890", @@ -128,7 +128,6 @@ response = requests.post( | `error:account-blocked` | Cuenta destino bloqueada o cerrada | `FAILED` | | `error:duplicate-external-id` | `externalId` ya usado en otra transacción | `FAILED` | | `error:bank-rejected` | Banco destino rechazó la transferencia (genérico) | `FAILED` | -| `error:oxxo-expired` | Cupón OXXO expiró sin pago | `EXPIRED` | ### Success Scenario @@ -226,7 +225,6 @@ Notas: |---|---|---| | `/api/spei/cash-in` | POST | Generar CLABE desechable de cobro | | `/api/spei/cash-out` | POST | Enviar SPEI por CLABE | -| `/api/oxxo/cash-in` | POST | Generar cupón OXXO | ## Behavior diff --git a/es/guides/signup.mdx b/es/guides/signup.mdx index 3794ef5..1d2fe5d 100644 --- a/es/guides/signup.mdx +++ b/es/guides/signup.mdx @@ -40,7 +40,7 @@ curl -X POST https://sandbox.ntxpay.com/api/signup \ #### Request — Persona Moral (producción) ```bash -curl -X POST https://api.ntxpay.com/api/signup \ +curl -X POST https://sandbox.ntxpay.com/api/signup \ -H "Content-Type: application/json" \ -d '{ "holderName": "Acme S.A. de C.V.", @@ -111,10 +111,9 @@ curl -X POST https://api.ntxpay.com/api/signup \ |---|---|---| | Provider | `sandbox` | `smartfastpay` | | Confirmación SPEI | Inmediata (simulada) | Real (segundos a minutos vía Banxico) | -| Confirmación OXXO | Inmediata | Tras lectura en caja (minutos a horas) | | Costo | Gratuito | Tarifas en producción | | Límites | Permisivos | Según contrato | -| Endpoint base | `https://sandbox.ntxpay.com` | `https://api.ntxpay.com` | +| Endpoint base | `https://sandbox.ntxpay.com` | Provista en el onboarding | ## Errores Comunes diff --git a/es/guides/spei-cash-in.mdx b/es/guides/spei-cash-in.mdx index 2a0d17f..fa2594a 100644 --- a/es/guides/spei-cash-in.mdx +++ b/es/guides/spei-cash-in.mdx @@ -27,7 +27,7 @@ Content-Type: application/json #### Request ```bash -curl -X POST https://api.ntxpay.com/api/spei/cash-in \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-in \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ diff --git a/es/guides/spei-cash-out.mdx b/es/guides/spei-cash-out.mdx index 7beda25..b53db54 100644 --- a/es/guides/spei-cash-out.mdx +++ b/es/guides/spei-cash-out.mdx @@ -21,7 +21,7 @@ Content-Type: application/json #### Request ```bash -curl -X POST https://api.ntxpay.com/api/spei/cash-out \ +curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -105,7 +105,7 @@ if (balance.availableCentavos < amountCentavos) { async function speiCashOut(token: string, dto: any) { try { const { data } = await axios.post( - 'https://api.ntxpay.com/api/spei/cash-out', + 'https://sandbox.ntxpay.com/api/spei/cash-out', dto, { headers: { Authorization: `Bearer ${token}` } }, ); diff --git a/es/guides/transactions-list.mdx b/es/guides/transactions-list.mdx index 9749595..7847020 100644 --- a/es/guides/transactions-list.mdx +++ b/es/guides/transactions-list.mdx @@ -1,11 +1,11 @@ --- title: 'Listar Transacciones' -description: 'Consulta el historial unificado SPEI + OXXO de tu cuenta' +description: 'Consulta el historial SPEI de tu cuenta' --- ## Visión General -`GET /api/transactions` retorna la lista paginada de transacciones de la cuenta autenticada, unificando **SPEI** y **OXXO** (cash-in, cash-out, refund-in, refund-out, internal_transfer). Es la fuente de verdad cuando necesitas **reconciliar** o consultar el status sin depender de webhooks. +`GET /api/transactions` retorna la lista paginada de transacciones **SPEI** de la cuenta autenticada (cash-in, cash-out, refund-in, refund-out, internal_transfer). Es la fuente de verdad cuando necesitas **reconciliar** o consultar el status sin depender de webhooks. **Rate limit**: 30 requests por minuto, por cuenta. Por encima de eso, `429`. @@ -28,13 +28,13 @@ Authorization: Bearer {token} | `limit` | int (1–100) | 20 | Cantidad por página | | `offset` | int (≥0) | 0 | Offset para paginación | | `status` | enum | — | `PENDING`, `CONFIRMED`, `FAILED`, `EXPIRED` | -| `paymentMethod` | enum | — | `SPEI`, `OXXO` | +| `paymentMethod` | enum | — | `SPEI` | | `direction` | enum | — | `in` (recibido), `out` (enviado) | #### Request ```bash -curl -X GET "https://api.ntxpay.com/api/transactions?status=CONFIRMED&paymentMethod=SPEI&limit=50" \ +curl -X GET "https://sandbox.ntxpay.com/api/transactions?status=CONFIRMED&paymentMethod=SPEI&limit=50" \ -H "Authorization: Bearer $TOKEN" ``` @@ -75,7 +75,7 @@ let offset = 0; const limit = 50; while (true) { - const { data } = await axios.get('https://api.ntxpay.com/api/transactions', { + const { data } = await axios.get('https://sandbox.ntxpay.com/api/transactions', { headers: { Authorization: `Bearer ${token}` }, params: { limit, offset, status: 'CONFIRMED' }, }); diff --git a/es/guides/webhooks/cash-in.mdx b/es/guides/webhooks/cash-in.mdx index 42b69fc..b2c6b57 100644 --- a/es/guides/webhooks/cash-in.mdx +++ b/es/guides/webhooks/cash-in.mdx @@ -1,6 +1,6 @@ --- title: 'Evento cash_in' -description: 'Notificación enviada cuando un SPEI o OXXO cash-in es confirmado' +description: 'Notificación enviada cuando un SPEI cash-in es confirmado' --- ## Cuándo dispara @@ -8,7 +8,6 @@ description: 'Notificación enviada cuando un SPEI o OXXO cash-in es confirmado' El evento `cash_in` se dispara cuando: - Una transferencia SPEI llega a la **CLABE desechable** emitida por `POST /api/spei/cash-in` y es liquidada -- Un pago OXXO emitido por `POST /api/oxxo/cash-in` es pagado en la caja de la tienda y confirmado ## Payload @@ -42,15 +41,6 @@ El evento `cash_in` se dispara cuando: | `X-NTXPay-Timestamp` | Unix epoch (segundos) | | `X-NTXPay-Delivery` | UUID único del envío | -## Diferencias SPEI vs OXXO - -| Aspecto | SPEI | OXXO | -|---|---|---| -| `paymentMethod` | `SPEI` | `OXXO` | -| `clabe` | CLABE de origen | `null` | -| Tiempo hasta confirmación | Segundos a minutos | Minutos a horas tras pagar en caja | -| Identificador adicional | `referenceNumerical` | `referenceNumerical` | - ## Respuesta Esperada Responde `200 OK` en menos de 10 segundos. Ante cualquier status distinto, NTX Pay reintenta hasta 5 veces en backoff exponencial. diff --git a/es/guides/webhooks/overview.mdx b/es/guides/webhooks/overview.mdx index 7d5c6f8..c7e4090 100644 --- a/es/guides/webhooks/overview.mdx +++ b/es/guides/webhooks/overview.mdx @@ -1,6 +1,6 @@ --- title: 'Visión General de Webhooks' -description: 'Notificaciones automáticas para eventos SPEI y OXXO' +description: 'Notificaciones automáticas para eventos SPEI' --- ## Qué son los Webhooks @@ -11,7 +11,7 @@ Los webhooks permiten que NTX Pay envíe notificaciones HTTPS a tu servidor siem | Evento | Cuándo dispara | |---|---| -| `cash_in` | SPEI cash-in confirmado **o** OXXO cash-in pagado en caja | +| `cash_in` | SPEI cash-in confirmado | | `cash_out` | SPEI cash-out liquidado | | `refund_in` | Estorno **recibido** (una transacción cash-out tuya fue devuelta) | | `refund_out` | Estorno **enviado** (devolviste un cash-in) | diff --git a/es/guides/webhooks/refund-out.mdx b/es/guides/webhooks/refund-out.mdx index acb59d7..2edc3a5 100644 --- a/es/guides/webhooks/refund-out.mdx +++ b/es/guides/webhooks/refund-out.mdx @@ -11,7 +11,6 @@ Escenarios comunes: - Accionaste un estorno por motivo de fraude o error - El cliente solicitó cancelación dentro del plazo SPEI -- Disputa OXXO en la que NTX Pay devuelve el valor ## Payload diff --git a/es/guides/webhooks/setup.mdx b/es/guides/webhooks/setup.mdx index a296f29..c1b9eff 100644 --- a/es/guides/webhooks/setup.mdx +++ b/es/guides/webhooks/setup.mdx @@ -1,6 +1,6 @@ --- title: 'Setup de Webhooks' -description: 'Configura URLs de webhook programáticamente para SPEI y OXXO' +description: 'Configura URLs de webhook programáticamente para SPEI' --- ## Visión General @@ -16,7 +16,7 @@ La configuración de webhooks se hace vía tres endpoints: ### Request ```bash -curl -X POST https://api.ntxpay.com/api/webhooks-config \ +curl -X POST https://sandbox.ntxpay.com/api/webhooks-config \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -59,7 +59,7 @@ curl -X POST https://api.ntxpay.com/api/webhooks-config \ ## Listar Webhooks ```bash -curl -X GET https://api.ntxpay.com/api/webhooks-config \ +curl -X GET https://sandbox.ntxpay.com/api/webhooks-config \ -H "Authorization: Bearer $TOKEN" ``` @@ -86,7 +86,7 @@ curl -X GET https://api.ntxpay.com/api/webhooks-config \ ## Remover Webhook ```bash -curl -X DELETE https://api.ntxpay.com/api/webhooks-config/42 \ +curl -X DELETE https://sandbox.ntxpay.com/api/webhooks-config/42 \ -H "Authorization: Bearer $TOKEN" ``` diff --git a/es/index.mdx b/es/index.mdx index 190bb75..6b8bc26 100644 --- a/es/index.mdx +++ b/es/index.mdx @@ -1,16 +1,16 @@ --- title: 'API NTX Pay México' -description: 'Integración con SPEI y OXXO en una única API' +description: 'Integración con SPEI en una única API' --- -Gateway público para integración con SPEI (transferencias interbancarias instantáneas) y OXXO (pago en efectivo). Recepción vía SPEI u OXXO, envío vía SPEI, consulta de saldo y transacciones, webhooks firmados. +Gateway público para integración con SPEI (transferencias interbancarias instantáneas). Recepción y envío vía SPEI, consulta de saldo y transacciones, webhooks firmados. ## Ambientes | Ambiente | URL | |---|---| | Sandbox | `https://sandbox.ntxpay.com` | -| Producción | `https://api.ntxpay.com` | +| Producción | Provista en el onboarding | ## Autenticación @@ -50,9 +50,6 @@ ISO 8601 UTC: `2026-05-12T14:31:05.000Z`. Cash-in y cash-out vía CLABE - - Cash-in en efectivo - Notificaciones HMAC diff --git a/es/sandbox/introduction.mdx b/es/sandbox/introduction.mdx index bff42f2..75f1ee9 100644 --- a/es/sandbox/introduction.mdx +++ b/es/sandbox/introduction.mdx @@ -22,7 +22,7 @@ Tus credenciales de API son **estructuralmente las mismas** que usarías en prod |---|---| | Sandbox | `https://sandbox.ntxpay.com` | -Todas las rutas documentadas (`/api/auth/token`, `/api/spei/cash-in`, `/api/spei/cash-out`, `/api/oxxo/cash-in`, `/api/transactions`, `/api/webhooks-config`) están disponibles exactamente en este host. +Todas las rutas documentadas (`/api/auth/token`, `/api/spei/cash-in`, `/api/spei/cash-out`, `/api/transactions`, `/api/webhooks-config`) están disponibles exactamente en este host. ## Escenarios de prueba @@ -36,7 +36,7 @@ Registra tu `webhookUrl` en la cuenta sandbox exactamente como lo harías en pro | Aspecto | Sandbox | Producción | |---|---|---| -| Base URL | `https://sandbox.ntxpay.com` | `https://api.ntxpay.com` | +| Base URL | `https://sandbox.ntxpay.com` | Provista en el onboarding | | Provider | `sandbox` (simulado) | Banco real (Banxico/SPEI) | | Saldo | Simulado | Fondos reales | | Confirmación SPEI cash-in | Inmediata (~1s) | Real (segundos a minutos) | diff --git a/es/sandbox/scenarios.mdx b/es/sandbox/scenarios.mdx index d16c7fc..eab4e08 100644 --- a/es/sandbox/scenarios.mdx +++ b/es/sandbox/scenarios.mdx @@ -6,7 +6,7 @@ mode: 'wide' ## Cómo usar -Agrega el header `X-Sandbox-Scenario: ` a cualquier llamada de cash-in, cash-out u OXXO. Sin el header, el sandbox usa el escenario `success` por defecto. +Agrega el header `X-Sandbox-Scenario: ` a cualquier llamada de cash-in o cash-out. Sin el header, el sandbox usa el escenario `success` por defecto. ```bash curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ @@ -44,7 +44,6 @@ curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ | `error:account-blocked` | `201 PENDING` | `FAILED` con `errorCode: ACCOUNT_BLOCKED` | | `error:duplicate-external-id` | `201 PENDING` | `FAILED` con `errorCode: DUPLICATE_EXTERNAL_ID` | | `error:bank-rejected` | `201 PENDING` | `FAILED` con `errorCode: BANK_REJECTED` | -| `error:oxxo-expired` | `201 PENDING` | `EXPIRED` (solo OXXO) | ### Escenarios de atraso diff --git a/pt-br/endpoints/oxxo-cash-in.mdx b/pt-br/endpoints/oxxo-cash-in.mdx deleted file mode 100644 index b2bb33c..0000000 --- a/pt-br/endpoints/oxxo-cash-in.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: post /api/oxxo/cash-in ---- diff --git a/pt-br/guides/get-started.mdx b/pt-br/guides/get-started.mdx index 927de19..b2164a4 100644 --- a/pt-br/guides/get-started.mdx +++ b/pt-br/guides/get-started.mdx @@ -1,6 +1,6 @@ --- title: 'Primeiros Passos' -description: 'Boas-vindas à API NTX Pay México. Este guia te leva pelos primeiros passos para integrar e começar a usar SPEI e OXXO.' +description: 'Boas-vindas à API NTX Pay México. Este guia te leva pelos primeiros passos para integrar e começar a usar SPEI.' mode: 'wide' --- @@ -26,7 +26,7 @@ A API NTX Pay México permite que sua empresa realize operações de pagamento, -H "Content-Type: application/json" \ -d '{ "url": "https://meu-servidor.com/webhooks/ntxpay", - "events": ["cash_in", "cash_out"] + "events": ["cash_in"] }' ``` diff --git a/pt-br/guides/postman-collections.mdx b/pt-br/guides/postman-collections.mdx index 16b0152..83f65ce 100644 --- a/pt-br/guides/postman-collections.mdx +++ b/pt-br/guides/postman-collections.mdx @@ -37,7 +37,6 @@ A coleção está organizada na ordem típica de uso: - `Auth` — geração de JWT - `SPEI` — cash-in, cash-out, get transaction by externalId -- `OXXO` — cash-in - `Transactions` — listar - `Webhooks Config` — listar, criar, deletar diff --git a/pt-br/guides/sandbox-testing.mdx b/pt-br/guides/sandbox-testing.mdx index 36b6587..5b45a3c 100644 --- a/pt-br/guides/sandbox-testing.mdx +++ b/pt-br/guides/sandbox-testing.mdx @@ -1,6 +1,6 @@ --- title: 'Testes em Sandbox' -description: 'Como usar o ambiente sandbox do NTX Pay México para simular cenários SPEI e OXXO sem custo nem risco.' +description: 'Como usar o ambiente sandbox do NTX Pay México para simular cenários SPEI sem custo nem risco.' mode: 'wide' --- @@ -101,7 +101,6 @@ response = requests.post( | `error:account-blocked` | Conta destino bloqueada ou encerrada | `FAILED` | | `error:duplicate-external-id` | `externalId` já usado em outra transação | `FAILED` | | `error:bank-rejected` | Banco destino rejeitou a transferência (genérico) | `FAILED` | -| `error:oxxo-expired` | Cupom OXXO expirou sem pagamento | `EXPIRED` | ### Cenário de Sucesso @@ -199,7 +198,6 @@ Notas: |---|---|---| | `/api/spei/cash-in` | POST | Gerar CLABE descartável de cobrança | | `/api/spei/cash-out` | POST | Enviar SPEI por CLABE | -| `/api/oxxo/cash-in` | POST | Gerar cupom OXXO | ## Comportamento diff --git a/pt-br/guides/webhooks/cash-in.mdx b/pt-br/guides/webhooks/cash-in.mdx index fd31f4b..3127cbf 100644 --- a/pt-br/guides/webhooks/cash-in.mdx +++ b/pt-br/guides/webhooks/cash-in.mdx @@ -1,6 +1,6 @@ --- title: 'Evento cash_in' -description: 'Notificação enviada quando um SPEI ou OXXO cash-in é confirmado' +description: 'Notificação enviada quando um SPEI cash-in é confirmado' mode: 'wide' --- @@ -9,7 +9,6 @@ mode: 'wide' O evento `cash_in` é disparado quando: - Uma transferência SPEI chega na **CLABE descartável** emitida por `POST /api/spei/cash-in` e é liquidada -- Um pagamento OXXO emitido por `POST /api/oxxo/cash-in` é pago no caixa da loja e confirmado ## Payload @@ -43,15 +42,6 @@ O evento `cash_in` é disparado quando: | `X-NTXPay-Timestamp` | Unix epoch (segundos) | | `X-NTXPay-Delivery` | UUID único do envio | -## Diferenças SPEI vs OXXO - -| Aspecto | SPEI | OXXO | -|---|---|---| -| `paymentMethod` | `SPEI` | `OXXO` | -| `clabe` | CLABE de origem | `null` | -| Tempo até confirmação | Segundos a minutos | Minutos a horas após pagar no caixa | -| Identificador adicional | `referenceNumerical` | `referenceNumerical` | - ## Resposta Esperada Responda `200 OK` em menos de 10 segundos. Em caso de qualquer status diferente, o NTX Pay tenta novamente até 5 vezes em backoff exponencial. diff --git a/pt-br/guides/webhooks/overview.mdx b/pt-br/guides/webhooks/overview.mdx index 66a3140..6e88c06 100644 --- a/pt-br/guides/webhooks/overview.mdx +++ b/pt-br/guides/webhooks/overview.mdx @@ -1,6 +1,6 @@ --- title: 'Visão Geral de Webhooks' -description: 'Notificações automáticas para eventos SPEI e OXXO' +description: 'Notificações automáticas para eventos SPEI' mode: 'wide' --- @@ -12,7 +12,7 @@ Webhooks permitem que o NTX Pay envie notificações HTTPS para o seu servidor s | Evento | Quando dispara | |---|---| -| `cash_in` | SPEI cash-in confirmado **ou** OXXO cash-in pago no caixa | +| `cash_in` | SPEI cash-in confirmado | | `cash_out` | SPEI cash-out liquidado | | `refund_in` | Estorno **recebido** (uma transação cash-out sua foi devolvida) | | `refund_out` | Estorno **enviado** (você devolveu um cash-in) | diff --git a/pt-br/guides/webhooks/refund-out.mdx b/pt-br/guides/webhooks/refund-out.mdx index 72242bf..2bd0e4b 100644 --- a/pt-br/guides/webhooks/refund-out.mdx +++ b/pt-br/guides/webhooks/refund-out.mdx @@ -12,7 +12,6 @@ Cenários comuns: - Você acionou um estorno por motivo de fraude ou erro - Cliente solicitou cancelamento dentro do prazo SPEI -- Disputa OXXO em que o NTX Pay devolve o valor ## Payload diff --git a/pt-br/guides/webhooks/setup.mdx b/pt-br/guides/webhooks/setup.mdx index fe4f544..50c1c1c 100644 --- a/pt-br/guides/webhooks/setup.mdx +++ b/pt-br/guides/webhooks/setup.mdx @@ -1,6 +1,6 @@ --- title: 'Setup de Webhooks' -description: 'Configure URLs de webhook programaticamente para SPEI e OXXO' +description: 'Configure URLs de webhook programaticamente para SPEI' mode: 'wide' --- diff --git a/pt-br/sandbox/introduction.mdx b/pt-br/sandbox/introduction.mdx index 9a0561c..e879ef7 100644 --- a/pt-br/sandbox/introduction.mdx +++ b/pt-br/sandbox/introduction.mdx @@ -22,7 +22,7 @@ Suas credenciais de API são as **mesmas estruturalmente** que você usaria em p |---|---| | Sandbox | `https://sandbox.ntxpay.com` | -Todas as rotas documentadas (`/api/auth/token`, `/api/spei/cash-in`, `/api/spei/cash-out`, `/api/oxxo/cash-in`, `/api/transactions`, `/api/webhooks-config`) estão disponíveis exatamente neste host. +Todas as rotas documentadas (`/api/auth/token`, `/api/spei/cash-in`, `/api/spei/cash-out`, `/api/transactions`, `/api/webhooks-config`) estão disponíveis exatamente neste host. ## Cenários de teste @@ -36,7 +36,7 @@ Registre seu `webhookUrl` na conta sandbox exatamente como faria em produção | Aspecto | Sandbox | Produção | |---|---|---| -| Base URL | `https://sandbox.ntxpay.com` | `https://api.ntxpay.com` | +| Base URL | `https://sandbox.ntxpay.com` | Fornecida no onboarding | | Provider | `sandbox` (simulado) | Banco real (Banxico/SPEI) | | Saldo | Simulado | Fundos reais | | Confirmação SPEI cash-in | Imediata (~1s) | Real (segundos a minutos) | diff --git a/pt-br/sandbox/scenarios.mdx b/pt-br/sandbox/scenarios.mdx index 906761a..ea57292 100644 --- a/pt-br/sandbox/scenarios.mdx +++ b/pt-br/sandbox/scenarios.mdx @@ -6,7 +6,7 @@ mode: 'wide' ## Como usar -Adicione o header `X-Sandbox-Scenario: ` a qualquer chamada de cash-in, cash-out ou OXXO. Sem o header, o sandbox usa o cenário `success` por padrão. +Adicione o header `X-Sandbox-Scenario: ` a qualquer chamada de cash-in ou cash-out. Sem o header, o sandbox usa o cenário `success` por padrão. ```bash curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ @@ -44,7 +44,6 @@ curl -X POST https://sandbox.ntxpay.com/api/spei/cash-out \ | `error:account-blocked` | `201 PENDING` | `FAILED` com `errorCode: ACCOUNT_BLOCKED` | | `error:duplicate-external-id` | `201 PENDING` | `FAILED` com `errorCode: DUPLICATE_EXTERNAL_ID` | | `error:bank-rejected` | `201 PENDING` | `FAILED` com `errorCode: BANK_REJECTED` | -| `error:oxxo-expired` | `201 PENDING` | `EXPIRED` (apenas OXXO) | ### Cenários de atraso