Payments
Create Payment
Learn how to create payments using the endpoint POST /stores//payments.
POST
Create payment
📌 Endpoint
POST /stores/{storeId}/payments
Creates a payment for one or more products of the store.
🔐 Authentication
Public route. The active subscription of the store owner is validated internally.🧾 Route parameters
🧍 Body (JSON)
🧩 items[]
💳 Supported gateways
Thegateway field follows the pattern <PROVIDER>_ORDER_<METHOD>:
Note: the gateway needs to be active in the store and with credentials configured. The store only receives the methods it enabled in the credentials (paymentMethods).
Stripe return URLs
To create a Stripe Checkout Session, you can send validhttp:// or https:// successUrl and cancelUrl values inside metadata. When omitted, the API falls back to the store’s configured domain (store.Domain) or, when store.Domain is empty, to the platform base URL (SiteBaseURL).
💳 Card installments
To charge a card in installments, inform the number of installments inmetadata.gateway.card.installmentCount:
- The chosen number is the one that applies — it must be between
1and themaxInstallmentsconfigured in the store gateway (maximum 12). If it exceeds the limit, the API rejects it with400 MAX_INSTALLMENTS_EXCEEDED; if it is invalid (< 1 or non-integer),400 INVALID_INSTALLMENT_COUNT. - When the merchant configured installment fee tiers (
installmentFees) in the gateway, the fee of the tier containing theinstallmentCountreplaces the flat fee offees.card— applied only once over the total, which is then equally divided among the installments. Ex.: tiers 1x0% + R$ 0, 2–6x3,49% + R$ 0,49, 7–12x3,99% + R$ 0,49. - Application in the gateway: the supported card gateways (Asaas and Mercado Pago) receive the chosen number of installments and divide the total (fee already embedded) equally in N× across all flows — hosted invoice or tokenized card. On Mercado Pago the checkout is limited to the chosen number (
max_installments). - Without the field, the card is charged upfront (1x) with the flat fee of
fees.card(on Mercado Pago, up to the merchant’smaxInstallments). - The
installmentCountis recorded on the payment inmetadata.gateway.card.installmentCount(alongsidegateway.FeePercentage/gateway.FeeAmount), allowing tracking of how many installments the sale was split into. - Installment errors return only the code (no
message), following the route standard:
💳 Transparent card (tokenized)
To charge the card without redirecting the buyer, the frontend tokenizes the data in the browser (public SDK of the gateway, with the public key) and sends only the token inmetadata.card — the card data never passes through the API:
- The token is also accepted in
metadata.gateway.card.creditCardToken. The installments remain inmetadata.gateway.card.installmentCount(validated against the store’smaxInstallments). - Without a token, nothing changes: the flow falls back to the hosted checkout (redirect) as before.
- Mercado Pago: with a token, the API charges directly (
POST /v1/payments) and responds withoutinit_point— comespaymentId,statusandstatusDetail; the final status is tracked by the verification queue (queries the payment in the gateway). Optional:paymentMethodIdandissuerId(the MP SDK reports both). - Asaas: with a token (
creditCardToken, orcreditCard+creditCardHolderInfo), charges directly; without a token, generates the hosted invoice (invoiceUrl/init_point). - EFI Bank: card payments require
metadata.gateway.card.payment_tokenfrom the EFI frontend SDK andmetadata.gateway.card.phone_number. - Gateway error (e.g.: invalid token) returns
502 GATEWAY_ERRORwith theerrorfield containing the provider’s response body — no charge is created.
✅ Example request
gateway to MERCADOPAGO_ORDER_BOLETO; for Mercado Pago balance, use MERCADOPAGO_ORDER_SALDO. Both use the same body as the PIX example; only change gateway.
💳 Example with Asaas (PIX)
gateway to ASAAS_ORDER_BOLETO. For hosted card checkout, use ASAAS_ORDER_CARD; for a direct card charge, also send a card token and holder details as described in the Transparent card (tokenized) section.
💳 Example with EFI Bank (PIX)
gateway to EFI_BANK_ORDER_BOLETO. EFI card requires frontend tokenization and the buyer’s phone number:
💳 Example with Stripe Checkout (PIX)
gateway to STRIPE_ORDER_CARD or STRIPE_ORDER_BOLETO. If successUrl or cancelUrl are omitted, the API falls back to the store’s domain (store.Domain) or SiteBaseURL when the store has no domain configured.
💳 Example with installment card (6x, Mercado Pago)
🧩 Snippet (cURL)
📦 Responses
201 — Payment via gateway (PIX / Mercado Pago)
201 — Payment via gateway (Card / Mercado Pago)
201 — Payment via gateway (PIX / Asaas)
For Asaas, track thestatus/idviametadata.gatewayin the payment filter (the verification queue queries the gateway directly). The hosted invoice (invoiceUrl/init_point) lets the buyer pay by PIX, card or boleto without tokenization.
201 — Free payment
200 — Idempotency replay (Idempotency-Key / idempotencyKey)
When a request reuses an already processed key in the store (via the Idempotency-Key header or the idempotencyKey body field), the API does not create a duplicate payment and returns HTTP 200 with the original saved response payload:
If the original response has not been persisted yet, the200fallback returns{"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}.
⚠️ Errors
For400 OUT_OF_STOCK,400 PRODUCT_DISABLED, and404 PRODUCT_NOT_FOUND, the response includes theproductIdfield identifying the item ({"code": "...", "productId": "..."}).
Headers
Body
application/json
Charge details (items, customer, gateway).