Development

LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

guides/advanced-payments/binary_mode.es.md

@@ -0,0 +1,11 @@
+## Pagos binarios
+
+Se puede definir el pago para que la respuesta sea instantánea o no.
+
+En caso de que sea instantánea, la respuesta del pago será `approved` o `rejected` (sin estados intermedios). Por el contrario, el pago puede quedar en estado pendiente esperando por ejemplo la acreditación del pago en el caso de Medios Offline o pagos con tarjeta de crédito de montos elevados donde el Comprador debe llamar a la entidad de la tarjeta para autorizar el pago.
+
+Esta lógica se puede manejar seteando, en la raíz del Advanced Payment, el campo `binary_mode` en `true` para que devuelva la respuesta inmediata y `false` para lo contrario.
+
+```json
+  "binary_mode": true
+```

guides/advanced-payments/cancel_advanced_payment.es.md

@@ -0,0 +1,19 @@
+## Cancelar un Advanced Payment
+
+Se podrá cancelar un Advanced Payment que haya quedado en estado `pending`. Estos casos se pueden dar para los pagos con Medios offline o algún pago con tarjeta de crédito que haya entrado en el flujo de revisión manual.
+
+###### Request
+```curl
+curl -X PUT \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/ID?access_token=MKT_ACCESS_TOKEN' \
+    -d '{...}'
+```
+
+###### Body
+```json
+{
+  "status": "cancelled"
+}
+```  

guides/advanced-payments/capture_advanced_payment.es.md

@@ -0,0 +1,21 @@
+## Capturar un Advanced Payment
+
+La API de Advanced Payment permite realizar pagos del tipo [Autorización y Captura](https://www.mercadopago.com.ar/developers/es/guides/payments/api/authorization-and-capture). Para estos casos se debe crear un Advanced Payment con el campo `capture` en `FALSE`, el cual reservará el monto hasta que se capture.
+
+Para capturarlo debes hacerlo de la siguente forma:
+
+###### Request
+```curl
+curl -X PUT \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/ID?access_token=MKT_ACCESS_TOKEN' \
+    -d '{...}'
+```
+
+###### Body
+```json
+{
+  "capture": true
+}
+```  

guides/advanced-payments/customers-and-cards.es.md

@@ -0,0 +1,19 @@
+## Pagos con Customers
+
+La API de Advanced Payments permite realizar pagos con Clientes y tarjetas guardadas para integradores que trabajen con este modelo de negocio.
+
+> NOTE
+>
+> Ver referencia de [Customers & Cards](https://www.mercadopago.com.ar/developers/es/guides/payments/api/customers-and-cards) para mayor información.
+
+Para crear un pago usando `Customers`, se setea el ID del usuario y el tipo con el valor `customer`.
+
+```json
+{
+  "payer": {
+    "id": "213693707-b2i8UYRe5h9NQv",
+    "type": "customer"
+  },
+  ...
+}
+```

guides/advanced-payments/idempotency.es.md

@@ -0,0 +1,18 @@
+## Idempotencia
+
+En ocasiones se pueden presentar problemas de conexión, caídas de servicios, etc. que podrían interrumpir la comunicación al enviar o recibir los datos para crear un Advanced Payment.
+
+Para asegurar la creación del mismo, se puede reintentar el envío de los mismos datos, pero es posible que el Advanced Payment ya se haya creado y debido a la interrupción no se recibió la respuesta correcta, ocasionando que, al realizar el reintento, se genere un nuevo Advanced Payment.
+
+Para evitar el duplicado, se puede enviar de una clave única en el header `X-Idempotency-Key` que identifique la creación de un único Advanced Payment no importa cuantas veces se envíen los mismos datos.
+
+De esta manera, cuando se haga el reintento, se puede enviar la misma clave para indicar que es el mismo proceso. Si el Advanced Payment ya fué creado, se devuelve la información del mismo sin crear uno nuevo.
+
+```curl
+curl -X POST \
+     -H 'X-Idempotency-Key: faDF8323asd298' \
+     -H 'accept: application/json' \
+     -H 'content-type: application/json' \
+     'https://api.mercadopago.com/v1/advanced_payments?access_token=MKT_ACCESS_TOKEN' \
+     -d '{...}'
+```

guides/advanced-payments/index.es.md

@@ -0,0 +1,16 @@
+# Índice
+
+* [Introducción](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/introduction)
+* [Inicio rápido split de pagos](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/split-quick-start)
+* [Liberación flexible](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/split-flexible_release)
+* [Obtención de permisos de vendedores](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/sellers-permissions)
+* [Clientes y tarjetas](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/customers-and-cards)
+* [Medios offline](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/offline_methods)
+* [Reembolsos](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/refund_advanced_payment)
+* [Autorización y captura](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/capture_advanced_payment)
+* [Cancelación de pagos](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/cancel_advanced_payment)
+* [Modo binario](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/binary_mode)
+* [Búsquedas y conciliación](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/search_and_conciliation)
+* [Mapa de estados y Webhooks](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/status-map-and-webhooks)
+* [Idempotencia](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/idempotency)
+* [Métodos de pago soportados](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/supported-payment-methods)

guides/advanced-payments/introduction.es.md

@@ -0,0 +1,32 @@
+# Advanced Payments
+
+## Introducción
+
+Advanced Payments es una API que permite procesar pagos con funcionalidades adicionales a la [API de Payments](https://www.mercadopago.com.ar/developers/es/guides/payments/api/introduction/) regular. Actualmente permite realizar pagos de Marketplace con split.
+
+#### Pagos de Marketplace con split
+
+La funcionalidad de Split de Pagos brinda una solución para los pagos de Marketplace donde el modelo de negocio requiere dividir el dinero entre múltiples Vendedores.
+
+> NOTE
+>
+> Para más información dirigirse a la documentación de [Marketplaces](https://www.mercadopago.com.ar/developers/es/guides/marketplace/api/introduction/).
+
+##### División de pagos
+
+* Un pago efectuado por un Comprador que corresponde a un Marketplace, se divide entre múltiples Vendedores.
+* La división se realiza al momento de la aprobación del pago.
+* No hay un límite de Vendedores para dividir el dinero y el Marketplace obtiene una comisión por cada venta efectuada.
+* Se puede configurar quién paga la comisión de Mercado Pago.
+
+##### Flexibilidad para aplicar comisión
+
+* El Marketplace retiene una parte del monto de la venta en concepto de comisión.
+* La comisión que cobra el Marketplace se aplica pago a pago.
+* Esto permite tener distintas comisiones para distintos Vendedores y a su vez distintas comisiones según el tipo o categoría del producto que ofrezca un Vendedor.
+
+##### Liberación flexible de dinero de Vendedores
+
+* Al momento de la integración se configura un rango de días en el cual se podrá liberar el dinero de los Vendedores.
+* La liberación se setea en cada pago y puede modificarse posteriormente.
+

guides/advanced-payments/offline_methods.es.md

@@ -0,0 +1,39 @@
+## Pagos con Medios Offline
+
+Se pueden realizar pagos con medios de pago offline o efectivo además de tarjetas de crédito o débito.
+
+> NOTE
+>
+> Puedes consultar los [medios de pago offline](https://www.mercadopago.com.ar/developers/es/guides/payments/api/other-payment-ways) para más información.
+> También puedes ver los [medios de pago soportados](https://www.mercadopago.com.ar/developers/es/guides/advanced-payments/supported-payment-methods) por la API de Advanced Payments.
+
+###### Request
+En el `body` del request debes definir el tipo de pago como `ticket` y el método según el país.
+```json
+{
+  ...
+  "payments": [
+    {
+      "payment_method_id": "bolbradesco",
+      "payment_type_id": "ticket",
+      ...
+    }
+  ]
+}
+```
+
+###### Response
+En la respuesta, encontrarás el campo "external_resource_url" con la url que contiene las instrucciones para que el Comprador pueda pagar.
+```json
+{
+  "payments": [
+    {
+      "payment_method_id": "bolbradesco",
+      "payment_type_id": "ticket",
+      ...
+      "external_resource_url": "http://www.mercadopago.com/mla/payments/ticket/helperpayment_id=4265666119&payment_method_reference_id=3575111597&caller_id=121212&hash=87069857reydfhgjhkjliouy7t6rd",
+      ...
+    }
+  ]
+}
+```

guides/advanced-payments/refund_advanced_payment.es.md

@@ -0,0 +1,35 @@
+## Reembolso de un Advanced Payment
+
+Se puede hacer el reembolso del Advanced Payment completo o de un `disbursement` individual.
+
+Si se reembolsa el Advanced Payment completo, este quedará con el estado `refunded`. En caso de realizar un reembolso parcial, el Advanced Payment quedará en estado `partially_refunded.
+
+> WARNING
+>
+> Hay que tener en cuenta que este proceso no es inmediato. Cuando se realiza el reembolso, se dispara un proceso asincrónico para reembolsar todos los pagos generados. El cambio de estado del Advanced Payment se informará mediante Webhooks.
+
+###### Reembolso de un Advanced Payment completo
+```curl
+curl -X POST \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/ID/refunds?access_token=MKT_ACCESS_TOKEN' \
+    -d '{...}'
+```
+
+###### Reembolso de un Disbursement individual
+```curl
+curl -X POST \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/ID/disbursements/DISBURSEMENT_ID/refunds?access_token=MKT_ACCESS_TOKEN' \
+    -d '{...}'
+```
+
+También es posible hacer el reembolso por un monto menor al capturado en un `disbursement` individual. Solo hay que enviar en el `body` el parámetro `amount` con el monto deseado.
+
+```json
+{
+  "amount": 10.2
+}
+```  

guides/advanced-payments/search_and_conciliation.es.md

@@ -0,0 +1,67 @@
+## Búsqueda y Conciliación
+
+Una parte importante de la generación de pagos es la conciliación. La API permite realizar búsquedas de tus `advanced payments` para poder conciliar todas las operaciones que se hicieron a través de tu Marketplace.
+
+Se puede buscar a través de la API de Advanced Payments.
+
+###### Request
+```curl
+curl -X POST \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/search?access_token=MKT_ACCESS_TOKEN&limit=10&offset=0'
+```
+
+###### Response
+Lo cual retorna los resultados en una estructura que muestra además la cantidad de resultados e información para la paginación de los mismos.
+```json
+{
+  "paging": {
+    "total": 3,
+    "limit": 10,
+    "offset": 0
+  },
+  "results": [
+    {
+      "id": 11111111,
+      "status": "approved",
+      ...
+    },
+    {
+      "id": 22222222,
+      "status": "rejected",
+      ...
+    },
+    {
+      "id": 33333333,
+      "status": "pending",
+      ...
+    }
+  ]
+}
+```
+
+##### Filtros de búsqueda
+
+Estado                      |Descripción                                                        |
+----------------------------|-------------------------------------------------------------------|
+date_created                |Fecha de creación del Advanced Payment.                            |
+status                      |Estado del Advanced Payment.                                       |
+payment.id                  |ID del pago del comprador.                                         |
+payment.payment_method_id   |Método del pago.                                                   |
+payment.external_reference  |ID generado para este pago de entrada en particular.               |
+payment.transaction_amount  |Monto del pago.                                                    |
+payer.id                    |ID del comprador.                                                  |
+payer.email                 |Email del comprador.                                               |
+disbursement.collector_id   |ID del vendedor.                                                   |
+external_reference          |ID generado por el marketplace que identifica el Advanced Payment. |
+
+### Exportar Activities
+
+Además está la posibilidad de exportar las activities desde el listado de tu cuenta de Mercado Pago con el link `Exportar`.
+
+![export_activities](/images/advanced-payments/export_activities.png)
+
+Puedes seleccionar los filtros que necesites y elegir el formato CSV o XLS para realizar la conciliación de forma manual.
+
+![export_activities_2](/images/advanced-payments/export_activities_2.png)

guides/advanced-payments/sellers-permissions.es.md

@@ -0,0 +1,5 @@
+## Obtención de permisos y datos del Merchant
+
+El Marketplace que desee integrarse, debe solicitar permisos a sus Merchants para poder operar y realizar pagos en su nombre. Para ello, debe seguir los pasos de [Mercado Pago Connect](https://www.mercadopago.com.ar/developers/es/guides/marketplace/api/create-marketplace).
+
+Al seguir estos pasos, el Marketplace podrá obtener el `user_id` que lo debe utilizar como `collector_id` en cada `disbursement` que desee crear en el Advanced Payment. Es importante guardar el user_id del merchant para poder identificar el propietario de la cuenta de Mercado Pago en caso que haga falta.

guides/advanced-payments/split-flexible_release.es.md

@@ -0,0 +1,60 @@
+## Liberación flexible
+
+Al momento de la integración se configura un rango de días en el cual se podrá liberar el dinero de los Vendedores.
+
+Esta liberación se setea en cada pago con el campo `money_release_days` y puede modificarse posteriormente.
+
+> NOTE
+>
+> Si no se manda este campo, se setea por defecto el máximo número de días del rango de liberación configurado en el Marketplace.
+
+```json
+{
+  ...
+  "disbursements": [
+    {
+      ...
+      "money_release_days": 15
+    },
+    {
+      ...
+      "money_release_days": 30
+    }
+  ],
+  ...
+}
+```
+
+Una vez creado, se puede cambiar la fecha de liberación tanto del Advanced Payment completo o de un `disbursement` individual.
+
+> NOTE
+>
+> Esta fecha debe estar dentro del rango de liberaciones definida anteriormente.
+
+###### Cambio de fecha para un Advanced Payment completo
+
+```curl
+curl -X POST \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/ID/disburses?access_token=MKT_ACCESS_TOKEN' \
+    -d '{...}'
+```
+
+###### Cambio de fecha para un Disbursement individual
+
+```curl
+curl -X POST \
+    -H 'Accept":"application/json' \
+    -H 'Content-Type: application/json' \
+    'https://api.mercadopago.com/v1/advanced_payments/ID/disbursements/DISBURSEMENT_ID/disburses?access_token=MKT_ACCESS_TOKEN' \
+    -d '{...}'
+```
+
+En el `body` debemos definir la nueva fecha de liberación.
+
+```json
+{
+  "money_release_date": "2018-07-10T10:23:18.000-04:00"
+}
+```