AI resources
One-time payments with saved cards
One-time payments with saved cards (Card on File) are payments that use the registered payment method data to make occasional charges without requiring the user to re-enter the card information.
These are payments that do not have a recurrence, but rather depend on an action by the merchant or the customer to be executed, such as automatic toll charges or payments in delivery apps with saved cards, respectively.
To process one-time payments with saved cards, 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 }, "stored_credential": { "payment_initiator": "merchant", "reason": "card_on_file", "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.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 one-time payments with saved cards is card_on_file. | 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" }, "stored_credential": { "payment_initiator": "merchant", "reason": "card_on_file", "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.