Pagos
Crear Pago
Aprende a crear pagos usando el endpoint POST /stores//payments.
POST
Create payment
📌 Endpoint
POST /stores/{storeId}/payments
Crea un pago para uno o varios productos de la tienda.
🔐 Autenticación
Ruta pública. La suscripción activa del dueño de la tienda se valida internamente.🧾 Parámetros de ruta
🧍 Body (JSON)
🧩 items[]
💳 Gateways soportados
El campogateway sigue el patrón <PROVEEDOR>_ORDER_<MÉTODO>:
Nota: el gateway necesita estar activo en la tienda y con credenciales configuradas. La tienda solo recibe los métodos que habilitó en las credenciales (paymentMethods).
URLs de retorno de Stripe
Para crear una sesión de Stripe Checkout, puedes enviarsuccessUrl y cancelUrl (válidas con http:// o https://) dentro de metadata. Cuando se omiten, la API usa el dominio configurado en la tienda (store.Domain) o recurre a la URL base de la plataforma (SiteBaseURL) cuando store.Domain está vacío.
💳 Parcelamiento en tarjeta
Para cobrar la tarjeta en cuotas, informa el número de cuotas enmetadata.gateway.card.installmentCount:
- El número elegido es el que vale — debe estar entre
1y elmaxInstallmentsconfigurado en el gateway de la tienda (máximo 12). Si supera el límite, la API rechaza con400 MAX_INSTALLMENTS_EXCEEDED; si es inválido (< 1 o no entero),400 INVALID_INSTALLMENT_COUNT. - Cuando el lojista configuró rangos de cuotas (
installmentFees) en el gateway, la tarifa del rango que contiene elinstallmentCountsustituye la tarifa plana defees.card— aplicada una única vez sobre el total, que luego se divide igualmente entre las cuotas. Ej.: rangos 1x0% + R$ 0, 2–6x3,49% + R$ 0,49, 7–12x3,99% + R$ 0,49. - Aplicación en la gateway: las gateways de tarjeta soportadas (Asaas y Mercado Pago) reciben el número de cuotas elegido y dividen el total (tarifa ya incluida) igualmente en las N× en todos los flujos — factura hospedada o tarjeta tokenizada. En Mercado Pago el checkout queda limitado al número elegido (
max_installments). - Sin el campo, la tarjeta se cobra a la vista (1x) con la tarifa plana de
fees.card(en Mercado Pago, hasta elmaxInstallmentsdel lojista). - El
installmentCountqueda registrado en el pago enmetadata.gateway.card.installmentCount(junto agateway.FeePercentage/gateway.FeeAmount), permitiendo rastrear en cuántas veces se parceló la venta. - Los errores de parcelamiento devuelven solo el código (sin
message), siguiendo el estándar de la ruta:
💳 Tarjeta transparente (tokenizada)
Para cobrar la tarjeta sin redirigir al comprador, el frontend tokeniza los datos en el navegador (SDK público de la gateway, con la public key) y envía solo el token enmetadata.card — los datos de la tarjeta nunca pasan por la API:
- El token también se acepta en
metadata.gateway.card.creditCardToken. Las cuotas siguen enmetadata.gateway.card.installmentCount(validado contra elmaxInstallmentsde la tienda). - Sin token, nada cambia: el flujo cae en el checkout hospedado (redirect) como antes.
- Mercado Pago: con token, la API cobra directo (
POST /v1/payments) y responde sininit_point— vienepaymentId,statusystatusDetail; el estado final se acompaña por la cola de verificación (consulta el payment en la gateway). Opcional:paymentMethodIdeissuerId(el SDK del MP informa ambos). - Asaas: con token (
creditCardToken, ocreditCard+creditCardHolderInfo), cobra directo; sin token, genera la factura hospedada (invoiceUrl/init_point). - EFI Bank: los pagos con tarjeta requieren
metadata.gateway.card.payment_tokendel SDK frontend de EFI ymetadata.gateway.card.phone_number. - Error de la gateway (ej.: token inválido) devuelve
502 GATEWAY_ERRORcon el campoerrorconteniendo el cuerpo del proveedor — no se crea ninguna cobranza.
✅ Ejemplo de solicitud
gateway como MERCADOPAGO_ORDER_BOLETO; para saldo de Mercado Pago, usa MERCADOPAGO_ORDER_SALDO. Ambos usan el mismo body del ejemplo PIX; solo cambia gateway.
💳 Ejemplo con Asaas (PIX)
gateway por ASAAS_ORDER_BOLETO. Para tarjeta alojada, usa ASAAS_ORDER_CARD; para un cobro directo con tarjeta, envía también un token y los datos del titular según la sección Tarjeta transparente (tokenizada).
💳 Ejemplo con EFI Bank (PIX)
EFI_BANK_ORDER_BOLETO. La tarjeta EFI requiere tokenización en el frontend y el teléfono del comprador:
💳 Ejemplo con Stripe Checkout (PIX)
gateway por STRIPE_ORDER_CARD o STRIPE_ORDER_BOLETO. Si successUrl o cancelUrl se omiten, la API usa el dominio de la tienda (store.Domain) o SiteBaseURL cuando la tienda no tiene un dominio configurado.
💳 Ejemplo con Tarjeta parcelada (6x, Mercado Pago)
🧩 Snippet (cURL)
📦 Respuestas
201 — Pago via gateway (PIX / Mercado Pago)
201 — Pago via gateway (Tarjeta / Mercado Pago)
201 — Pago via gateway (PIX / Asaas)
Para Asaas, acompaña elstatus/idviametadata.gatewayen el filtro de pagos (la cola de verificación consulta la gateway directamente). La factura hospedada (invoiceUrl/init_point) permite al comprador pagar por PIX, tarjeta o boleto sin tokenización.
201 — Pago gratuito
200 — Replay de idempotencia (Idempotency-Key / idempotencyKey)
Cuando la solicitud reutiliza una clave ya procesada en la tienda (vía header Idempotency-Key o campo idempotencyKey en el body), la API no crea un pago duplicado y devuelve HTTP 200 con el payload original guardado de la creación:
Si la respuesta original aún no se ha guardado, el fallback200devuelve{"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}.
⚠️ Errores
En los errores400 OUT_OF_STOCK,400 PRODUCT_DISABLEDy404 PRODUCT_NOT_FOUND, la respuesta incluye el campoproductIdidentificando el elemento ({"code": "...", "productId": "..."}).
Encabezados
Cuerpo
application/json
Charge details (items, customer, gateway).