mercadopago.payments.create-payment

Creates a payment. For card payments, generate a card token client-side via MercadoPago.js before calling this endpoint. For cash/offline methods (Boleto, OXXO, Pix), the response includes a payment URL in transaction_details.external_resource_url. Idempotency: Include X-Idempotency-Key to safely retry on network errors without risk of double charges. Recommendation: For new integrations, prefer the Orders API (POST /v1/orders). Idempotent: Supports X-Idempotency-Key header to safely retry without duplicate charges. Webhook events triggered: payment, merchant_order

Create a payment

Overview

Property	Value
Workflow type	Atomic
Library	App-mercadopago
Version	1.0

Input Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Mercadopago API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
x_idempotency_key	string	No	—	Unique key per payment attempt. If you retry with the same key and the original payment was processed, MP returns the original result without creating a duplicate.
transaction_amount	float	Yes	—	Payment amount as a decimal number. MercadoPago does NOT use integer cents — send 100.50 for R$100,50 (not 10050). CLP uses 0 decimal places.
token	string	No	—	Card token created client-side via MercadoPago.js / MP Secure Fields. Required for credit/debit card payments. Single-use; expires in 7 days.
description	string	No	—	Description of the purchased product or service
installments	integer	No	—	Number of installments (1 = no installments)
payment_method_id	string	No	—	Payment method identifier. Examples: visa, master, bolbradesco (Boleto), pix, oxxo, rapipago, pse. Use GET /v1/payment_methods to list available methods for a given site_id.
issuer_id	string	No	—	Card issuer ID (required for some credit cards)
payer	json	Yes	—	—
capture	boolean	No	—	Two-step payment flow: set false to only authorize (reserve funds), then PUT /v1/payments/{id} with capture=true to capture. Debit cards do not support two-step capture.
binary_mode	boolean	No	—	When true, payments can only be in_process → approved or rejected — no pending state. Useful for in-store flows.
external_reference	string	No	—	Your internal order or reference ID. Max 256 chars.
notification_url	string	No	—	URL to receive IPN notifications when payment status changes. DEPRECATED — use Webhooks instead.
statement_descriptor	string	No	—	Text that appears on the payer's card statement. Max 22 chars.
callback_url	string	No	—	Redirect URL after bank transfer (redirect-based methods only)
date_of_expiration	string	No	—	Expiration date for cash/offline payment methods (boleto, OXXO, etc.). ISO 8601 format. Default varies by method.
metadata	json	No	—	Free key-value object for your own internal data (not used by MP)
additional_info	json	No	—	Additional context for fraud scoring and installment calculation
application_fee	float	No	—	Marketplace fee charged to the seller (marketplace integrations only)
coupon_code	string	No	—	Discount coupon code
coupon_amount	float	No	—	Coupon discount value

Output Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Mercadopago API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
x_idempotency_key	string	No	—	Unique key per payment attempt. If you retry with the same key and the original payment was processed, MP returns the original result without creating a duplicate.
transaction_amount	float	Yes	—	Payment amount as a decimal number. MercadoPago does NOT use integer cents — send 100.50 for R$100,50 (not 10050). CLP uses 0 decimal places.
token	string	No	—	Card token created client-side via MercadoPago.js / MP Secure Fields. Required for credit/debit card payments. Single-use; expires in 7 days.
description	string	No	—	Description of the purchased product or service
installments	integer	No	—	Number of installments (1 = no installments)
payment_method_id	string	No	—	Payment method identifier. Examples: visa, master, bolbradesco (Boleto), pix, oxxo, rapipago, pse. Use GET /v1/payment_methods to list available methods for a given site_id.
issuer_id	string	No	—	Card issuer ID (required for some credit cards)
payer	json	Yes	—	—
capture	boolean	No	—	Two-step payment flow: set false to only authorize (reserve funds), then PUT /v1/payments/{id} with capture=true to capture. Debit cards do not support two-step capture.
binary_mode	boolean	No	—	When true, payments can only be in_process → approved or rejected — no pending state. Useful for in-store flows.
external_reference	string	No	—	Your internal order or reference ID. Max 256 chars.
notification_url	string	No	—	URL to receive IPN notifications when payment status changes. DEPRECATED — use Webhooks instead.
statement_descriptor	string	No	—	Text that appears on the payer's card statement. Max 22 chars.
callback_url	string	No	—	Redirect URL after bank transfer (redirect-based methods only)
date_of_expiration	string	No	—	Expiration date for cash/offline payment methods (boleto, OXXO, etc.). ISO 8601 format. Default varies by method.
metadata	json	No	—	Free key-value object for your own internal data (not used by MP)
additional_info	json	No	—	Additional context for fraud scoring and installment calculation
application_fee	float	No	—	Marketplace fee charged to the seller (marketplace integrations only)
coupon_code	string	No	—	Discount coupon code
coupon_amount	float	No	—	Coupon discount value
status_code	integer	No	—	HTTP status code of the completed call
response	json	No	—	Parsed JSON response body
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_at	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
failed_at_state	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Waiting to call POST /v1/payments
completed	No	Yes	Yes	—	HTTP call succeeded
failed	No	Yes	No	—	HTTP call failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	Perform POST /v1/payments
* (any state)	fail	failed	Record the failure reason

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "mercadopago.payments.create-payment",
  "initial_data": {
    "base_url": "value",
    "transaction_amount": "value",
    "payer": "value"
  }
}