Generar Devolución de Efectivo
Cómo crear devoluciones con Direct API
Para hacer una Devolución de Efectivo es necesario que la orden de compra tenga los siguientes requisitos:
- El estado de la orden tiene que ser pagado dentro de los últimos 90 días.
- El método de pago de la orden tiene que ser oxxo_cash .
- El monto total de la orden tiene que ser superior a $30.00 MXN, no se aceptan decimales distintos de cero en la devolución.
- La compañía tiene un giro de negocio permitido para devoluciones
Diagrama de Secuencia
Consultar orden
Para saber si una orden puede ser reembolsable puede consultarse.
curl --location --request GET 'https://api.conekta.io/orders/ord_XXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.conekta-v2.0.0+json' \
--header 'Authorization: Basic YOUR_PRIVATE_API_KEY'
{
"livemode": true,
"amount": 300000,
"currency": "MXN",
"payment_status": "paid",
"amount_refunded": 0,
"customer_info": {
"email": "[email protected]",
"phone": "5555555555",
"name": "User",
"object": "customer_info"
},
"object": "order",
"id": "ord_XXXXXXXXXXX",
"metadata": {},
"is_refundable": true,
"created_at": 1675282824,
"updated_at": 1675282921,
"line_items": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"name": "Item 1",
"unit_price": 300000,
"quantity": 1,
"object": "line_item",
"id": "line_item_2tHvw9yFvBGxhXXXX",
"parent_id": "ord_2tHvw9yFvBGxXXXX",
"metadata": {},
"antifraud_info": {}
}
]
},
"charges": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"id": "63dac9880e46770001f42096",
"livemode": true,
"created_at": 1675282824,
"currency": "MXN",
"device_fingerprint": "funBRv12pKj38EDq3JMbwz6UuGRiZagC",
"payment_method": {
"service_name": "OxxoPay",
"barcode_url": "https://barcodes.conekta.com/mybarcode.png",
"store": "10MON50EDI",
"auth_code": 16428704,
"object": "cash_payment",
"type": "oxxo",
"expires_at": 1677628800,
"store_name": "OXXO",
"reference": "840002622XXXXX"
},
"object": "charge",
"description": "Payment from order",
"status": "paid",
"amount": 300000,
"paid_at": 1675282921,
"fee": 22620,
"customer_id": "",
"order_id": "ord_XXXXXXXXXXX"
}
]
}
}
En la respuesta el campo llamado is_refundable nos ayudará a identificar si la orden es reembolsable.
Crear devolución total
Monto máximo $3,000.00 MXN.
El monto máximo para una devolución total es $3,000.00 MXN. En caso de necesitar reembolsar una orden con monto superior será necesario hacerlo a través de devoluciones parciales generando tantas referencias como sean necesarias. No se aceptan decimales distintos de cero.
curl --location --request POST 'https://api.conekta.io/orders/ord_XXXXXXXXXXX/refund' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.conekta-v2.0.0+json' \
--header 'Authorization: Basic YOUR_PRIVATE_API_KEY' \
--data-raw '{
"reason": "requested by client"
}'
{
"livemode": true,
"amount": 30000,
"currency": "MXN",
"payment_status": "paid",
"amount_refunded": 0,
"customer_info": {
"email": "[email protected]",
"phone": "5555555555",
"name": "User",
"object": "customer_info"
},
"object": "order",
"id": "ord_2tJFoTfEbpLvUGfxv",
"metadata": {},
"is_refundable": true,
"created_at": 1675368795,
"updated_at": 1675369020,
"line_items": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"name": "Item 1",
"unit_price": 30000,
"quantity": 1,
"object": "line_item",
"id": "line_item_2tJFoTfEbpLvUGfxt",
"parent_id": "ord_2tJFoTfEbpLvUGfxv",
"metadata": {},
"antifraud_info": {}
}
]
},
"charges": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"id": "63dc195b920de10001d18371",
"livemode": true,
"created_at": 1675368795,
"currency": "MXN",
"device_fingerprint": "Uu1dXHssJK7XFVKHP4hqvVgkeeqXXXX",
"payment_method": {
"service_name": "OxxoPay",
"barcode_url": "https://barcodes.conekta.com/mybarcode.png",
"store": "10MON50EDI",
"auth_code": 25209103,
"object": "cash_payment",
"type": "oxxo",
"expires_at": 1677715200,
"store_name": "OXXO",
"reference": "8400026227XXXX"
},
"object": "charge",
"description": "Payment from order",
"status": "paid",
"amount": 30000,
"paid_at": 1675369020,
"fee": 226,
"customer_id": "cus_2tJFrR5iWkVqXXXX",
"order_id": "ord_2tJFoTfEbpLvUXXXX",
"refunds": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"object": "cash_refund",
"amount": -30000,
"id": "63dc1a44c4440b000194b0de",
"created_at": 1675369028,
"reference": "************0334",
"payout_id": "7650bb15-ee34-4586-99ad-40e80f6258df",
"status": "pending",
"expires_at": 1675541827
}
]
}
}
]
}
}
Parámetros
| Parámetro | Descripción | Tipo | Requerido |
|---|---|---|---|
| reason | Razón por la cual se genera el reembolso | String | No |
La respuesta incluye el atributo refunds que contiene una lista de todas las referencias de devolución creadas para el cargo. Cada elemento de la lista contiene los siguientes atributos:
- id: identificador del cash_refund dentro de la lista
- amount: importe correspondiente al cash_refund
- reference: número de referencia con el cual el cliente cobra el efectivo en OXXO. Por motivos de seguridad sólo visible en su totalidad para referencias cobradas, expiradas y canceladas.
- payout_id: identificador interno de la referencia
- status: estado de la referencia. Posibles valores: pending, withdrawn, expired y cancelled
- created_at: timestamp de creación de la referencia de devolución
- expired_at: timestamp de expiración de la referencia de devolución
El estado del cargo cambiará a refunded una vez que se haya cobrado la referencia en tiendas OXXO.
Crear devolución parcial
curl --location --request POST 'https://api.conekta.io/orders/ord_XXXXXXXXXXX/refund' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.conekta-v2.0.0+json' \
--header 'Authorization: Basic YOUR_PRIVATE_API_KEY' \
--data-raw '{
"amount": "3000"
}'
Parámetros
| Parámetro | Descripción | Tipo | Requerido |
|---|---|---|---|
| amount | Monto con el que se crea el reembolso | String | No |
| reason | Razón por la cual se genera el reembolso | String | No |
El estado del cargo irá cambiando de valor a medida que se vayan cobrando las referencias de devolución desde paid, pasando por partially_refund hasta quedar en refunded una vez cobradas todas las referencias que cubran el total del cargo.
Notificación
Una vez generado el reembolso se enviará a través del webhook configurado el evento cash_refund.created y se enviará el siguiente correo al usuario para que pueda cobrar su devolución en OXXO.
{
"object": {
"id":"63dd1adfaf43b2a604ce0d63",
"object":"cash_refund",
"amount":-5000,
"currency":"MXN",
"status":"pending",
"reason":"test",
"reference":"*****6789",
"payout_order_id":"ec22c58c-ad54-4123-a53d-d2bcc80649ca",
"created_at":1675434719
},
"previous_attributes":{}
}
Ejemplo de notificación
Generación de la referencia
Updated 3 days ago