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ámetro | Descripción | Tipo | Requerido |
|---|---|---|---|
| reason | Razón por la cual se genera el reembolso | String | No |
| expires_at | Fecha de expiración (Es la hora medida en número de segundos en formato UNIX) | Int | No |
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á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
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
}
]
}
}
]
}
}
| Parametro | Descripción | Tipo | Requerido |
|---|---|---|---|
| ord_XXXXXXXXXXX | Número de orden | String | Sí |
| id_devolucion | Id de la devolución que se desea realizar, se encuentra en el atributo refunds como id | String | Sí |
Updated 4 months ago