Skip to main content
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

The gateway 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 valid http:// 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 in metadata.gateway.card.installmentCount:
  • The chosen number is the one that applies — it must be between 1 and the maxInstallments configured in the store gateway (maximum 12). If it exceeds the limit, the API rejects it with 400 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 the installmentCount replaces the flat fee of fees.card — applied only once over the total, which is then equally divided among the installments. Ex.: tiers 1x 0% + R$ 0, 2–6x 3,49% + R$ 0,49, 7–12x 3,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’s maxInstallments).
  • The installmentCount is recorded on the payment in metadata.gateway.card.installmentCount (alongside gateway.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 in metadata.card — the card data never passes through the API:
  • The token is also accepted in metadata.gateway.card.creditCardToken. The installments remain in metadata.gateway.card.installmentCount (validated against the store’s maxInstallments).
  • 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 without init_point — comes paymentId, status and statusDetail; the final status is tracked by the verification queue (queries the payment in the gateway). Optional: paymentMethodId and issuerId (the MP SDK reports both).
  • Asaas: with a token (creditCardToken, or creditCard + creditCardHolderInfo), charges directly; without a token, generates the hosted invoice (invoiceUrl / init_point).
  • EFI Bank: card payments require metadata.gateway.card.payment_token from the EFI frontend SDK and metadata.gateway.card.phone_number.
  • Gateway error (e.g.: invalid token) returns 502 GATEWAY_ERROR with the error field containing the provider’s response body — no charge is created.

✅ Example request

For Mercado Pago boleto, set 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)

For Asaas boleto, use the same request and set 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)

For boleto, set gateway to EFI_BANK_ORDER_BOLETO. EFI card requires frontend tokenization and the buyer’s phone number:

💳 Example with Stripe Checkout (PIX)

For Stripe card or boleto, change 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 the status / id via metadata.gateway in 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, the 200 fallback returns {"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}.

⚠️ Errors

For 400 OUT_OF_STOCK, 400 PRODUCT_DISABLED, and 404 PRODUCT_NOT_FOUND, the response includes the productId field identifying the item ({"code": "...", "productId": "..."}).

Headers

Idempotency-Key
string

Optional idempotency key to prevent duplicate charges.

Maximum string length: 255

Path Parameters

storeId
string
required
Required string length: 1 - 50

Body

application/json

Charge details (items, customer, gateway).

name
string
required
Required string length: 3 - 50
email
string<email>
required
Required string length: 12 - 100
gateway
string
required
Required string length: 1 - 50
items
object[]
required
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

Response

Idempotent replay of an already-created payment.

data
object
required
status
boolean
Example:

true