AI resources
Scheduled recurring payments
Scheduled recurring payments allow you to make automatic charges at defined intervals, using the previously saved payment method data without the need for new user interaction. The recurrence logic is defined and managed by the seller through the creation of payments, adapting to business needs.
This model is indicated for recurring charges, such as subscriptions, plans, and continuous services.
To process scheduled recurring payments, send a POST to the endpoint /v1/ordersAPI. You must send your Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Application details. and the information detailed below for this type of payment.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "type": "online", "external_reference": "ext_ref_1234", "total_amount": "1000.00", "processing_mode": "automatic_async", "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "amount": "1000.00", "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943", "retries": 3, "subscription": { "id": "subscription-id", "sequence": { "number": 1, "total": 12 }, "invoice": { "id": "00000000000", "billing_date": "2024-09-02", "period": { "interval": 1, "type": "monthly" } } } }, "stored_credential": { "payment_initiator": "customer", "reason": "recurring", "previous_transaction_reference": "REF-987-654-321", "first_payment": false } } ] } }'
| Attribute | Type | Description | Required |
Authorization | Header | Refers to your private key, the Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Application details.. | Required |
X-Idempotency-Key | Header | Idempotency key. This key ensures that each request is processed only once, avoiding duplicates. Use a unique value in your request header, such as a UUID V4 or random strings. | Required |
type | Body. String | Order type, associated with the Mercado Pago solution for which it is created. For online payments with cards, the only possible value is online. | Required |
external_reference | Body. String | External reference for the order. It can be, for example, a Central Bank hashcode, functioning as a transaction origin identifier. This field must have a maximum of 64 characters and can only contain numbers, letters, hyphens (-) and underscores (_). Special characters such as ([ ], (), '', @) are not allowed. | Required |
total_amount | Body. String | Total transaction amount. | Required |
processing_mode | Body. String | Order processing mode. Possible values are: - automatic, to create and process the order in automatic mode. - automatic_async, to create the order with retry logic. For more information, access Orders processing modes. | Optional |
payer.customer_id | Body. String | Identifier of the customer who will make the payment. It is obtained in the Register payment method stage, when creating the customer, whether it is with a first time payment or a registration for future payments. | Required |
transactions.payments.amount | Body. String | Transaction amount. | Required |
transaction.payments.automatic_payments.payment_profile_id | Body. String | Customer's payment profile identifier. Obtained in the Register payment method stage, when creating the payment profile, whether it is with a first time payment or a registration for future payments. | Required |
transaction.payments.automatic_payments.retries | Body. Integer | Number of times the payment will be retried in case of initial failure. Must be a number between 1 and 5. This field is only allowed if processing_mode=automatic_async has been defined. Additionally, if the customer's payment profile has the max_day_overdue field configured, the retry configuration set for retries will not take priority. | Optional |
transaction.payments.automatic_payments.subscription.id | Body. String | Subscription identifier. We suggest that this value be composed of the collector + a unique subscription ID per user. | Required if sequence_control is manual |
transaction.payments.automatic_payments.subscription.sequence.number | Body. Integer | Indicates the subsequent payment number. | Required if sequence_control is manual |
transaction.payments.automatic_payments.subscription.sequence.total | Body. Integer | Indicates the total number of payments in the subscription. For permanent subscriptions, it should be null. | Required if sequence_control is manual |
transaction.payments.automatic_payments.subscription.invoice.id | Body. String | Invoice identifier associated with the billing cycle. | Required if sequence_control is manual |
transaction.payments.automatic_payments.subscription.invoice.billing_date | Body. String | Billing date corresponding to the subscription cycle. | Required if sequence_control is manual |
transaction.payments.automatic_payments.subscription.invoice.period.interval | Body. Number | Time interval between each charge. | Required if sequence_control is manual |
transaction.payments.automatic_payments.subscription.invoice.period.type | Body. String | Recurrence period type. Possible values are daily, weekly, or monthly. | Required if sequence_control is manual |
transaction.payments.stored_credentials.payment_initiator | Body. String | Identifies who initiates the transaction. Possible values are: - customer, when the transaction is initiated by the customer. - merchant, when the transaction is initiated by the seller. | Required |
transaction.payments.stored_credentials.reason | Body. String | Payment type identifier, which is the reason why it is being stored. The only possible value for scheduled recurring payments is recurring. If you send this field and the payment profile has the sequence_control field defined as auto, it is not necessary to send the automatic_payments.subscription node, as the recurrence information will be automatically managed by the system. Go to Manage scheduled recurring payments for more information | Optional |
transaction.payments.stored_credentials.previous_transaction_reference | Body. String | Reference code of the previous transaction being processed, if any. Must be sent from the second payment processed for the same customer. | Required when first_payment: false |
transaction.payments.stored_credentials.first_payment | Body. Boolean | Indicates whether this is the processing of a first payment (true) or a subsequent payment (false). | Optional |
If the request is sent correctly, the payment will have been created and the response will look like the example below.
json
{ "id": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE", "processing_mode": "automatic_async", "external_reference": "ext_ref_1234", "total_amount": "200.00", "country_code": "MEX", "user_id": "1245621468", "created_date": "2024-09-02T22:04:01.880469Z", "last_updated_date": "2024-09-02T22:04:04.429289Z", "type": "online", "status": "processing", "status_detail": "processing", "capture_mode": "automatic_async", "integration_data": { "application_id": "4599991948843755" }, "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "id": "PAY01J6TC8BYRR0T4ZKY0QRTZ0E24", "reference_id": "74e9f7137a3246d3a3ad607c82da9880", "amount": "200.00", "status": "processing", "status_detail": "processing", "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943", "subscription": { "id": "subscription-id", "sequence": { "number": 1, "total": 12 }, "invoice": { "id": "invoice-id", "billing_date": "2024-09-02", "period": { "interval": 1, "type": "month" } } } }, "stored_credential": { "payment_initiator": "customer", "reason": "recurring", "previous_transaction_reference": "REF-987-654-321", "first_payment": false } } ] } }
You can check the detail of possible statuses to be returned in the response by going to the Order status and Transaction status sections, respectively. Additionally, you can check the Possible errors when sending this request.
Manage scheduled recurring payments
When you create a scheduled recurring payment, certain fields linked to the payment frequency are required to improve the approval rate. In the Orders API, these fields are contained in the subscription node.
With the support of the Profiles API, the management of this information can be done in two ways: automatic or manual.
To automate the management of information related to payment recurrence, and avoid sending this information manually, you must:
- Set the
sequence_controlfield of the customer's payment profile toauto. If you need more information on how to do this, access our API Reference. - Create the payment by sending the value
recurringfor thetransaction.payments.stored_credentials.reasonfield.
This way, it will not be necessary to send the information contained in the transaction.payments.automatic_payments.subscription node as it will be automatically managed by the system.