Configuraciones de preferencia
Puedes adaptar la integración de Wallet Brick a tu modelo de negocio configurando atributos de preferencia.
Si ofreces compras de alto valor, por ejemplo, puedes excluir métodos de pago no deseado para tu operación.
Ejemplo de preferencia completa
json
{
"items": [
{
"id": "item-ID-1234",
"title": "Title of what you are paying for. It will be displayed in the payment process.",
"currency_id": "COP",
"picture_url": "https://www.mercadopago.com/org-img/MP3/home/logomp3.gif",
"description": "Item description",
"category_id": "art", // Available categories at https://api.mercadopago.com/item_categories
"quantity": 1,
"unit_price": 100
}
],
"payer": {
"name": "user-name",
"surname": "user-surname",
"email": "user@email.com",
"date_created": "2015-06-02T12:58:41.425-04:00",
"phone": {
"area_code": "11",
"number": "4444-4444"
},
"identification": {
"type": "RUT", // Available ID types at https://api.mercadopago.com/v1/identification_types
"number": "12345678"
},
"address": {
"street_name": "Street",
"street_number": 123,
"zip_code": "5700"
}
},
"back_urls": {
"success": "https://www.success.com",
"failure": "http://www.failure.com",
"pending": "http://www.pending.com"
},
"auto_return": "approved",
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"installments": 12,
"default_payment_method_id": null,
"default_installments": null
},
"shipments": {
"receiver_address": {
"zip_code": "5700",
"street_number": 123,
"street_name": "Street",
"floor": 4,
"apartment": "C"
}
},
"notification_url": "https://www.your-site.com/ipn",
"statement_descriptor": "MINEGOCIO",
"external_reference": "Reference_1234",
"expires": true,
"expiration_date_from": "2016-02-01T12:00:00.000-04:00",
"expiration_date_to": "2016-02-28T12:00:00.000-04:00",
"taxes": [
{
"type": "IVA",
"value": 16
}
]
}
Define los medios de pago
A través de la preferencia de pago, puedes configurar un método de pago por defecto, eliminar los no deseados, o elegir un número máximo de cuotas que se ofrecerán.
Atributo | Descripción |
payment_methods | Clase que describe los métodos y atributos de medios de pago de Wallet Brick. |
excluded_payment_types | Método que excluye tipos de medios de pago no deseados, como tarjetas de crédito, entre otros. |
excluded_payment_methods | Método que excluye marcas de tarjetas de crédito o débito, como Visa, Mastercard o American Express, entre otras. |
installments | Método que define la cantidad de cuotas máximas a ofrecer. |
purpose | Al indicar el valor wallet_purchase en este método, Wallet Brick solo aceptará pagos de usuarios registrados en Mercado Pago, con tarjeta y saldo de cuenta. |
Por ejemplo:
<?php
$preference = new MercadoPago\Preference();
// ...
$preference->payment_methods = array(
"excluded_payment_methods" => array(
array("id" => "master")
),
"excluded_payment_types" => array(
array("id" => "ticket")
),
"installments" => 12
);
// ...
?>
var preference = {}
preference = {
//...
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"installments": 12
}
//...
}
PreferenceClient client = new PreferenceClient();
//...
List<PreferencePaymentMethodRequest> excludedPaymentMethods = new ArrayList<>();
excludedPaymentMethods.add(PreferencePaymentMethodRequest.builder().id("master").build());
excludedPaymentMethods.add(PreferencePaymentMethodRequest.builder().id("amex").build());
List<PreferencePaymentTypeRequest> excludedPaymentTypes = new ArrayList<>();
excludedPaymentTypes.add(PreferencePaymentTypeRequest.builder().id("ticket").build());
PreferencePaymentMethodsRequest paymentMethods =
PreferencePaymentMethodsRequest.builder()
.excludedPaymentMethods(excludedPaymentMethods)
.excludedPaymentTypes(excludedPaymentTypes)
.installments(12)
.build();
PreferenceRequest request = PreferenceRequest.builder().paymentMethods(paymentMethods).build();
client.create(request);
//...
#...
preference_data = {
# ...
payment_methods: {
excluded_payment_methods: [
{ id: 'master' }
],
excluded_payment_types: [
{ id: 'ticket' }
],
installments: 12
}
# ...
}
#...
var paymentMethods = new PreferencePaymentMethodsRequest
{
ExcludedPaymentMethods = new List<PreferencePaymentMethodRequest>
{
new PreferencePaymentMethodRequest
{
Id = "master",
},
},
ExcludedPaymentTypes = new List<PreferencePaymentTypeRequest>
{
new PreferencePaymentTypeRequest
{
Id = "ticket",
},
},
Installments = 12,
};
var request = new PreferenceRequest
{
// ...
PaymentMethods = paymentMethods,
};
#...
preference_data = {
"excluded_payment_methods": [
{ "id": "master" }
],
"excluded_payment_types": [
{ "id": "ticket" }
],
"installments": 12
}
#...
Acepta pagos únicamente de usuarios registrados
Puedes aceptar pagos con la billetera de Mercado Pago exclusivamente de usuarios registrados, con tarjetas y dinero disponible.
Esto permite que tus clientes tengan disponible la información de su cuenta al instante en el momento del pago, como sus tarjetas y domicilios guardados.
Para aceptar pagos exclusivamente de usuarios registrados, agrega el siguiente atributo en tu preferencia:
json
"purpose": "wallet_purchase"
Al hacerlo, tu preferencia tendría una estructura similar al ejemplo siguiente:
json
{
"purpose": "wallet_purchase",
"items": [
{
"title": "Mi producto",
"quantity": 1,
"unit_price": 75.76
}
],
}
Modifica la tasa de impuestos DIAN
Puedes modificar el valor del impuesto para la Dirección de Impuestos y Aduanas Nacionales (DIAN), aplicado según el producto o servicio que ofrezcas.
Si no diferencias este valor, se aplicará por defecto una tarifa de 19%.
Atributo | Descripción |
type | Identificador del impuesto. Solo se admite IVA como valor. |
value | Monto del impuesto. Se admite un máximo de dos decimales. Para ítems excentos de impuestos se debe informar cero (0 ). |
Por ejemplo:
"taxes": [
{
"type": "IVA",
"value": 16
}
]
Cambia la fecha de vencimiento para pagos en efectivo
Puedes cambiar la fecha de vencimiento por defecto de un pago en efectivo enviando el campo date_of_expiration
en la solicitud de creación de la preferencia. La fecha configurada debe ser entre 1 y 30 días a partir de la fecha de creación de la preferencia de pago.
Por ejemplo:
"date_of_expiration": "2020-05-30T23:59:59.000-04:00"
Activa el modo binario
Puedes activar el modo binario si el modelo de negocio requiere que la aprobación del pago sea instantánea. De esta forma, el pago solo puede resultar aprobado o rechazado. En caso de no estar activado el modo binario, el pago puede quedar en pendiente (en caso de requerir alguna acción por parte del comprador) o en proceso (si es necesaria una revisión manual).
Para activarlo, solo debes configurar como true
el atributo binary_mode
de la preferencia de pago:
json
"binary_mode": true
Establece la vigencia de preferencias
Si se quiere habilitar el pago de una preferencia con un tiempo de duración determinado, se puede activar un periodo de vigencia o concluir directamente con los atributos expires
, expiration_date_from
y expiration_date_to
:
json
"expires": true,
"expiration_date_from": "2017-02-01T12:00:00.000-04:00",
"expiration_date_to": "2017-02-28T12:00:00.000-04:00"
Nota que la fecha usa el formato ISO 8601: yyyy-MM-dd'T'HH:mm:ssz
.
Envía una descripción en el resumen de la tarjeta
Puedes agregar una descripción para tu negocio a través del atributo statement_descriptor
de las preferencias de pago, como se muestra en el siguiente ejemplo:
json
"statement_descriptor": "MINEGOCIO"
El valor del atributo aparecerá en el resumen de la tarjeta de tu comprador dependiendo de la marca de la tarjeta utilizada.
Establece una preferencia para múltiples ítems
Si se necesita crear una preferencia para más de un ítem, solo debes agregarlos como una lista, tal como se muestra en el siguiente ejemplo:
<?php
# Crear un objeto preferencia
$preference = new MercadoPago\Preference();
# Crea ítems en la preferencia
$item1 = new MercadoPago\Item
$item1->title = "Item de Prueba 1";
$item1->quantity = 2;
$item1->unit_price = 11.96;
$item2= new MercadoPago\Item
$item2->title = "Item de Prueba 2";
$item2->quantity = 1;
$item2->unit_price = 11.96;
$preference->items = array($item1,$item2);
# Guardar y postear la preferencia
$preference->save();
?>
// Configura tu preferencia
var preference = {
items: [
{ title: 'Mi producto',
quantity: 1,
currency_id: 'COP',
unit_price: 75.56 },
{ title: 'Mi producto 2’,
quantity: 2,
currency_id: 'COP',
unit_price: 96.56 }
]
};
// Crea un botón de pago en tu sitio
mercadopago.preferences.create(preference)
.then(function(preference){
// Este valor reemplazará el string "$init_point$" en tu HTML
global.init_point = preference.body.init_point;
}).catch(function(error){
console.log(error);
});
// Crea un objeto preferencia
PreferenceClient client = new PreferenceClient();
// Crea ítems en la preferencia
List<PreferenceItemRequest> items = new ArrayList<>();
PreferenceItemRequest item1 =
PreferenceItemRequest.builder()
.id("1234")
.title("Produto 1")
.quantity(2)
.currencyId("BRL")
.unitPrice(new BigDecimal("100"))
.build();
PreferenceItemRequest item2 =
PreferenceItemRequest.builder()
.id("12")
.title("Produto 2")
.quantity(1)
.currencyId("BRL")
.unitPrice(new BigDecimal("100"))
.build();
items.add(item1);
items.add(item2);
PreferenceRequest request = PreferenceRequest.builder().items(items).build();
// Guardar y postear la preferencia
client.create(request);
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
# Create preference data with items
preference_data = {
items: [
{
title: 'Mi producto 1',
quantity: 1,
currency_id: 'COP',
unit_price: 75.56
},
{
title: 'Mi producto 2',
quantity: 2,
currency_id: 'COP',
unit_price: 96.56
}
]
}
preference_response = sdk.preference.create(preference_data)
preference = preference_response[:response]
// Crea el request con múltiples ítems
var request = new PreferenceRequest
{
Items = new List<PreferenceItemRequest>
{
new PreferenceItemRequest
{
Title = "Mi producto 1",
Quantity = 1,
CurrencyId = "COP",
UnitPrice = 75.56m,
},
new PreferenceItemRequest
{
Title = "Mi producto 2",
Quantity = 2,
CurrencyId = "COP",
UnitPrice = 96.56m,
},
// ...
},
};
// Crea un objeto client
var client = new PreferenceClient();
// Crea la preferencia
Preference preference = await client.CreateAsync(request);
# Crea ítems en la preferencia
preference_data = {
"items": [
{
"title": "Mi producto",
"quantity": 1,
"unit_price": 75.56
},
{
"title": "Mi producto2",
"quantity": 2,
"unit_price": 96.56
}
]
}
# Crea la preferencia
preference_response = sdk.preference().create(preference_data)
preference = preference_response["response"]
curl -X POST \
'https://api.mercadopago.com/checkout/preferences' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-H 'Authorization: Bearer PROD_ACCESS_TOKEN' \
-d '{
"items": [
{
"id_product":1,
"quantity":1,
"unit_price": 234.33,
"titulo":"Mi producto"
},
{
"id_product":2,
"quantity":2,
"unit_price": 255.33,
"titulo":"Mi producto 2"
}
]
}'
Ten en cuenta que el valor total de la preferencia será la suma del valor del precio unitario de cada ítem listado.
Muestra el monto del envío
Si ya tienes estimado el envio desde tu sitio, puedes enviar el monto y mostrarlo por separado del total al ofrecer el pago.
Para configurarlo, agrega el nodo shipments
con el valor del monto que quieras cobrar en el atributo cost
y el valor not_specified
en el atributo mode
:
json
{
"shipments":{
"cost": 1000,
"mode": "not_specified",
}
}
Redirigir al comprador a tu sitio web
Al final del proceso de pago, tienes la opción de redireccionar al comprador a tu sitio web nuevamente. Para hacer esto, agrega el atributo back_urls
y define, de acuerdo con el estado del pago, la página deseada para redireccionar a tu comprador cuando haga clic en el botón regresar al sitio.
Si quieres que la redirección sea automática para los pagos aprobados, sin mostrar un botón de retorno, también debes agregar el atributo auto_return
con el valor de approved
.
Atributo | Descripción |
auto_return | Redirige automáticamente a los compradores al sitio cuando el pago finaliza como aprobado. El valor predeterminado es approved . |
back_urls | URL deseada para retornar al sitio. Los posibles escenarios son:success : URL de retorno ante la aprobación del pago.pending : URL de retorno ante el pago pendiente.failure : URL de retorno ante el pago rechazado. |
A través de back_urls
, se devolverán los siguientes parámetros:
Parámetro | Descripción |
payment_id | ID (identificador) del pago de Mercado Pago. |
status | Estado de pago. Ej .: approved para un pago aprobado o pending para un pago pendiente. |
external_reference | Valor que hayas enviado a la hora de crear la preferencia de pago. |
comerciante_order_id | ID (identificador) de la orden de pago generada en Mercado Pago. |
Por ejemplo:
<?php
$preference = new MercadoPago\Preference();
//...
$preference->back_urls = array(
"success" => "https://www.tu-sitio/success",
"failure" => "http://www.tu-sitio/failure",
"pending" => "http://www.tu-sitio/pending"
);
$preference->auto_return = "approved";
// ...
?>
var preference = {}
preference = {
// ...
"back_urls": {
"success": "https://www.tu-sitio/success",
"failure": "http://www.tu-sitio/failure",
"pending": "http://www.tu-sitio/pending"
},
"auto_return": "approved",
// ...
}
PreferenceBackUrlsRequest backUrls =
// ...
PreferenceBackUrlsRequest.builder()
.success("https://www.seu-site/success")
.pending("https://www.seu-site/pending")
.failure("https://www.seu-site/failure")
.build();
PreferenceRequest request = PreferenceRequest.builder().backUrls(backUrls).build();
// ...
# ...
preference_data = {
# ...
back_urls = {
success: 'https://www.tu-sitio/success',
failure: 'https://www.tu-sitio/failure',
pending: 'https://www.tu-sitio/pendings'
},
auto_return: 'approved'
# ...
}
# ...
var request = new PreferenceRequest
{
// ...
BackUrls = new PreferenceBackUrlsRequest
{
Success = "https://www.tu-sitio/success",
Failure = "http://www.tu-sitio/failure",
Pending = "http://www.tu-sitio/pendings",
},
AutoReturn = "approved",
};
preference_data = {
"back_urls": {
"success": "https://www.tu-sitio/success",
"failure": "https://www.tu-sitio/failure",
"pending": "https://www.tu-sitio/pendings"
},
"auto_return": "approved"
}
La fecha usa el formato ISO 8601: yyyy-MM-dd'T'HH:mm:ssz