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 por devolución

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",
  "expires_at": 1681854666
}'
{
    "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ámetroDescripciónTipoRequerido
reasonRazón por la cual se genera el reembolsoStringNo
expires_atFecha de expiración (Es la hora medida en número de segundos en formato UNIX)IntNo

📘

expires_at

  • Al generar una referencia puedes elegir la expiración deseada de cada referencia. La vigencia puede estar dentro del rango de 1 día a 365 días.
  • Si no eliges ninguna expiración, se asignará el valor por default de 7 días

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ámetroDescripciónTipoRequerido
amountMonto con el que se crea el reembolsoStringNo
reasonRazón por la cual se genera el reembolsoStringNo

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

773

Reenviar notificación

En esta sección se podrá comprender cómo reenviar una notificación de devolución previamente generada.

🚧

Consideraciones para el reenvío

Sólo se podrán reenviar aquellas notificaciones que contengan una referencia pendiente de ser cobrada. Para aquellas ya retiradas, canceladas o expiradas no aplicará este servicio.

La siguiente solicitud muestra cómo enviar nuevamente la notificación de devolución. Necesitarás contar con tu llave privada para poder realizar las solicitudes. Si aún no cuentas con ella, puedes obtenerla en tu Panel Conekta.

curl --location --request PUT 'https://api.conekta.io/orders/ord_XXXXXXXXXXX/refund/id_devolucion/notification' \
--header 'Accept: application/vnd.conekta-v2.0.0+json' \
--header 'Accept-Language: en' \
--header 'Content-type: application/json' \
--header 'Authorization: Basic YOUR_PRIVATE_API_KEY'
{
    "livemode": true,
    "amount": 50000,
    "currency": "MXN",
    "payment_status": "paid",
    "amount_refunded": 0,
    "customer_info": {
        "email": "[email protected]",
        "phone": "5555555555",
        "name": "User",
        "object": "customer_info"
    },
    "object": "order",
    "id": "ord_2tV3dPk9GgaNB9xT8",
    "metadata": {},
    "is_refundable": true,
    "created_at": 1678220457,
    "updated_at": 1678220631,
    "line_items": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "name": "Box of Cohiba S1s",
                "unit_price": 50000,
                "quantity": 1,
                "object": "line_item",
                "id": "line_item_2tV3dPk9GgaNB9xT6",
                "parent_id": "ord_2tV3dPk9GgaNB9xT8",
                "metadata": {},
                "antifraud_info": {}
            }
        ]
    },
    "charges": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "id": "64079ca9d6014f0001bff56c",
                "livemode": true,
                "created_at": 1678220457,
                "currency": "MXN",
                "device_fingerprint": "bQ1LRyesr68DTLXqED6PM6R43zzHxu5A",
                "payment_method": {
                    "service_name": "OxxoPay",
                    "barcode_url": "https://pt-common-s3-stg.s3.amazonaws.com/b82841dcf44ae5065f8cd0085e61269317a6bf02.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA3UN6375MM6EA7VM7%2F20230307%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230307T202057Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEH0aCXVzLWVhc3QtMSJIMEYCIQCv3Fsz63Um%2B0Vn38NocHbSYpEzsX9VNykWzHoK4F1dBwIhAJLVN3Er61cXAnKlq0Y0jfjEw0t3Sr6OjZFt47EeSnJsKocECDUQAhoMNzk5ODAxMDgxNjg4Igwt0ywP6dVtDG3JpD4q5ANPD4vHJt6zBAwgEgHcccJ3rGJtsLWjGQlRjwO0Ay25REL9VY6LGBvOrHYej1ff2yhER2U80uL8IQ4ye6fo%2FG4v2APZDqT%2FEMkztQQvPJGvH%2FG7LG0vGCZ7B%2B9%2Brg8t%2FUsd2nEA4TDW53bkWj8n7szwx3qu0pguVVkT4gUb6NDpsP81LUVQ2JxRTdk%2BRxkXOZ45A77Xlz2RmZYC9BZD2KCAUomVdZT0h4AaDLkbBMvxpn0JmGBeo6BwzKq4xiAn5qX0Ook%2Bda3ZqIgpcXEZAQABuqjgxtiyORCGEm9DyoNIaMu%2FoQ0ypFpAMCbuGRT%2BcLlsomJK4NuZzB35mr405bAxMO4wsLSa8OnWYMOhesw0q2ImStr8CYG8hI9L%2BwlT5D4UhRIAERCwBz1SentQKIGMjinSidYSRgUj8LT9vIM6txYTkvWXjG1zMoPoIB0KGkGjPeLIQRVG7pRwoEUyzvseeSva%2BKfyzNT1dW33c1aZcfNU%2FPDI%2FwRDPWu6Zl7pOAd1GmIVngJVLpxQ%2BW88EnAw974GmMQ4Su7QUX%2Bre4r3BQWqDfMf1Rm1HM2bWZbtoEd6IDTV%2B7GLfz0s4cuodL4Z3j25%2BMAgROTw1JOnCiR1GBpD6wDqxfq7TLMCS%2BG%2FxpD91nS1MNW1nqAGOqQBWzQ49dZhFndmOPBHzy202Tg6GOVBGG%2B%2BCte7JS4SGWRJyJwY88rlFHLWa475emCKovJrFB9afj9HM77Z1XSi4sUgxLsqTzWCYy22Muvc3ezezssNVKGXWWSKvysBlyw90zx3C6m6v%2Fge%2FLi54d63yFIviHbJnGJYc5AmHZdO8%2Fqx9Goci4qiBRyCEbdCKKFyDenaPjs3hzxrD%2F04%2FD%2Fs%2FL0Qbjc%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=aebed155ad9c2abbc44546fc92363d77f8dfb8f79e893db8ced76ae89bf6c2eb",
                    "store": "10MON50EDI",
                    "auth_code": 991466079,
                    "object": "cash_payment",
                    "type": "oxxo",
                    "expires_at": 1680825600,
                    "store_name": "OXXO",
                    "reference": "93000262280777"
                },
                "object": "charge",
                "description": "Payment from order",
                "status": "paid",
                "amount": 50000,
                "paid_at": 1678220631,
                "fee": 1160,
                "customer_id": "cus_2tV3frEGmADZsH31P",
                "order_id": "ord_2tV3dPk9GgaNB9xT8",
                "refunds": {
                    "object": "list",
                    "has_more": false,
                    "total": 1,
                    "data": [
                        {
                            "object": "cash_refund",
                            "amount": -50000,
                            "id": "64079d6bd6014f0001bff582",
                            "created_at": 1678220651,
                            "reference": "1021466226004832",
                            "payout_id": "74c81ffd-07f3-47c6-9b0a-ff7a0330afac",
                            "status": "cancelled",
                            "expires_at": 1678393450
                        }
                    ]
                }
            }
        ]
    }
}
ParametroDescripciónTipoRequerido
ord_XXXXXXXXXXXNúmero de ordenString
id_devolucionId de la devolución que se desea realizar, se encuentra en el atributo refunds como idString