Saltar al contenido principal
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 campo gateway 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 enviar successUrl 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 en metadata.gateway.card.installmentCount:
  • El número elegido es el que vale — debe estar entre 1 y el maxInstallments configurado en el gateway de la tienda (máximo 12). Si supera el límite, la API rechaza con 400 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 el installmentCount sustituye la tarifa plana de fees.card — aplicada una única vez sobre el total, que luego se divide igualmente entre las cuotas. Ej.: rangos 1x 0% + R$ 0, 2–6x 3,49% + R$ 0,49, 7–12x 3,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 el maxInstallments del lojista).
  • El installmentCount queda registrado en el pago en metadata.gateway.card.installmentCount (junto a gateway.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 en metadata.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 en metadata.gateway.card.installmentCount (validado contra el maxInstallments de 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 sin init_point — viene paymentId, status y statusDetail; el estado final se acompaña por la cola de verificación (consulta el payment en la gateway). Opcional: paymentMethodId e issuerId (el SDK del MP informa ambos).
  • Asaas: con token (creditCardToken, o creditCard + creditCardHolderInfo), cobra directo; sin token, genera la factura hospedada (invoiceUrl / init_point).
  • EFI Bank: los pagos con tarjeta requieren metadata.gateway.card.payment_token del SDK frontend de EFI y metadata.gateway.card.phone_number.
  • Error de la gateway (ej.: token inválido) devuelve 502 GATEWAY_ERROR con el campo error conteniendo el cuerpo del proveedor — no se crea ninguna cobranza.

✅ Ejemplo de solicitud

Para boleto de Mercado Pago, configura 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)

Para boleto de Asaas, usa la misma solicitud y cambia 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)

Para boleto, usa EFI_BANK_ORDER_BOLETO. La tarjeta EFI requiere tokenización en el frontend y el teléfono del comprador:

💳 Ejemplo con Stripe Checkout (PIX)

Para tarjeta o boleto en Stripe, cambia 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 el status / id via metadata.gateway en 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 fallback 200 devuelve {"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}.

⚠️ Errores

En los errores 400 OUT_OF_STOCK, 400 PRODUCT_DISABLED y 404 PRODUCT_NOT_FOUND, la respuesta incluye el campo productId identificando el elemento ({"code": "...", "productId": "..."}).

Encabezados

Idempotency-Key
string

Optional idempotency key to prevent duplicate charges.

Maximum string length: 255

Parámetros de ruta

storeId
string
requerido
Required string length: 1 - 50

Cuerpo

application/json

Charge details (items, customer, gateway).

name
string
requerido
Required string length: 3 - 50
email
string<email>
requerido
Required string length: 12 - 100
gateway
string
requerido
Required string length: 1 - 50
items
object[]
requerido
Minimum array length: 1
cpf
string | null
Maximum string length: 24
coupon
string | null
Maximum string length: 32
idempotencyKey
string | null
Maximum string length: 255
metadata
object | null

Respuesta

Idempotent replay of an already-created payment.

data
object
requerido
status
boolean
Ejemplo:

true