Rapipago and Pago Fácil

To be able to receive payments, you need to add a form in the frontend that securely captures the payer's information.

If you already have a development that includes your own payment form, make sure to include Rapipago and Pago Fácil among the payment options you want to offer, as indicated below, and continue to the Get document types step.

If you do not have a payment form, add the one below to your project, including the identifier of the payment methods to be offered.

html
<form id="form-checkout" action="/process_payment" method="post">
    <div>
      <div>
        <label for="payerFirstName">Nombre</label>
        <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
      </div>
      <div>
        <label for="payerLastName">Appelido</label>
        <input id="form-checkout__payerLastName" name="payerLastName" type="text">
      </div>
      <div>
        <label for="email">E-mail</label>
        <input id="form-checkout__email" name="email" type="text">
      </div>
      <div>
        <label for="identificationType">Tipo de documento</label>
        <select id="form-checkout__identificationType" name="identificationType" type="text"></select>
      </div>
      <div>
        <label for="identificationNumber">Número del documento</label>
        <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
      </div>
    </div>

    <div>
      <div>
        <input type="hidden" name="transactionAmount" id="transactionAmount" value="100">
        <input type="hidden" name="description" id="description" value="Nome do Produto">
        <br>
        <button type="submit">Pagar</button>
      </div>
    </div>
  </form>

To facilitate the correct entry of data in the payment form, it is necessary to obtain the possible document types to be accepted.

The function below will allow you to automatically populate the available options, thanks to the inclusion of the select element with the id: form-checkout__identificationType found in the form used as an example in the previous step.

If you already have a development that includes the retrieval of document types, as indicated below, proceed to the Submit payment step.

If you do not have this function, add the following to your project.

javascript
function createSelectOptions(elem, options, labelsAndKeys = { label : "name", value : "id"}){
   const {label, value} = labelsAndKeys;

   elem.options.length = 0;

   const tempOptions = document.createDocumentFragment();

   options.forEach( option => {
       const optValue = option[value];
       const optLabel = option[label];

       const opt = document.createElement('option');
       opt.value = optValue;
       opt.textContent = optLabel;

       tempOptions.appendChild(opt);
   });

   elem.appendChild(tempOptions);
}

// Get Identification Types
(async function getIdentificationTypes () {
   try {
       const identificationTypes = await mp.getIdentificationTypes();
       const docTypeElement = document.getElementById('docType');

       createSelectOptions(docTypeElement, identificationTypes)
   }catch(e) {
       return console.error('Error getting identificationTypes: ', e);
   }
})()

The payment submission must be made by creating an order that contains associated payment transactions.

To do this, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix. and the required parameters listed below to the endpoint /v1/ordersPOST.

curl
curl --location --request POST 'https://api.mercadopago.com/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data-raw '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "total_amount": "50.00",
  "payer": {
    "email": "test_payer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "identification": {
      "type": "DNI",
      "number": "99999999999"
    }
  },
  "config": {
    "location": {
      "state_id": "AR-B"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "50.00",
        "expiration_time": "P3D",
        "payment_method": {
          "id": "rapipago",
          "type": "ticket"
        }
      }
    ]
  }
}'

See the table below for descriptions of the parameters that are mandatory in the request and those that, although optional, have some important particularity that should be highlighted.

The creation of the payment occurs asynchronously in the order. While it is being processed, the order is returned with a processing status and without information.

Once processing is complete, and since this is an offline payment method, the order transitions to action_required with the detail waiting_payment, indicating that the buyer still needs to complete the payment, as shown in the following response example. We recommend setting up Order topic notifications to receive updates on the status change, including the updated order data. Alternatively, you can choose to send a request to the /v1/orders/{id}GET endpoint to retrieve the updated status.

json
{
  "id": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "country_code": "ARG",
  "user_id": "1245621468",
  "status": "action_required",
  "status_detail": "waiting_payment",
  "capture_mode": "automatic",
  "created_date": "2024-09-02T22:04:01.880469Z",
  "last_updated_date": "2024-09-02T22:04:04.429289Z",
  "integration_data": {
    "application_id": "4599991948843755"
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J6TC8BYRR0T4ZKY0QRTZ0E24",
        "reference_id": "22dvqmsbq8c",
        "amount": "50.00",
        "status": "action_required",
        "status_detail": "waiting_payment",
        "payment_method": {
          "id": "rapipago",
          "type": "ticket",
          "ticket_url": "https://www.mercadopago.com.ar/payments/86797024510/ticket?caller_id=1870026883&payment_method_id=rapipago&payment_id=86797024510&payment_method_reference_id=6004835002&hash=0331521a-9ddb-44a2-851c-65f77d8d394e",
          "barcode_content": "3335008800000000006004835002100020000242462010",
          "reference": "6005407530",
          "verification_code": "6005407530"
        }
      }
    ]
  }
}

Among the returned parameters, the ones indicated in the table below stand out.

If you wish, you can cancel a payment created, as long as it is pending or in process; that is, with status=action_required.

Additionally, we recommend canceling payments that were not made by the established due date to avoid billing and reconciliation issues.

For more information, please consult the Refunds and cancellations section.