TRtrytoku
Refunds

Crear Refund de Transaction

Changed on

Devuelve el dinero de un pago, total o parcialmente.

Se usa para reversar un pago ya cobrado. Toku registra la devolución como una Transaction propia de tipo REVERSED, ligada al pago original, y la aplica sobre las Invoices que ese pago había saldado.

Si se omite refund_amount, se devuelve el monto total del pago. Para devolver solo una parte, indica el monto; y si el pago saldó varias Invoices, usa invoice_refund_details para precisar cuánto corresponde a cada una.

Sin idempotency_key, cada llamada crea una devolución nueva y las parciales se acumulan sobre el mismo pago, así que reenviar la misma petición vuelve a devolver el monto mientras quede saldo; cuando ya no queda, la petición es rechazada con estado 400. Reenviar la petición con la misma idempotency_key devuelve la respuesta original, con el header Idempotent-Replayed, sin crear otra devolución.

Cuando la devolución se envía al gateway en línea, la respuesta ya trae el desenlace y el comprobante. En los productos que se devuelven por lote o de forma asíncrona, success llega en false con error en null: la devolución quedó iniciada y el gateway la confirma después.

Un pago con tarjeta de un solo cobro (payment_orchestration_onetime) o con wallet (wallet_mx) más antiguo que su plazo de devolución es rechazado con estado 400 antes de contactar al gateway.

post/refund/transaction

Request

  • Base URL
    https://api.trytoku.com
  • URL
    https://api.trytoku.com/refund/transaction
  • Auth
    API key in header x-api-key

Headers

x-account-keystring

Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

Request body

disable_automatic_paymentsboolean

Indica si se deshabilita el cobro automático de las Invoices asociadas a la Transaction.

id_transactionstring required

Identificador de la Transaction a devolver.

idempotency_keystring

Llave para reintentar la devolución sin duplicarla; usa una distinta por cada devolución. Si se repite, se devuelve la respuesta original sin crear otra devolución, aunque cambie el cuerpo; si la petición original falló, el reintento responde con error sin volver a procesarla. La respuesta se conserva 24 horas.

mark_invoices_as_unpaidboolean

Indica si las Invoices quedan marcadas como no pagadas tras la devolución. Se envía en false al devolver un pago duplicado, para que la deuda no vuelva a quedar pendiente.

reasonstring required

Motivo de la devolución.

refund_amountnumber

Monto a devolver. Si se omite, se devuelve el monto total de la Transaction; cuando viene invoice_refund_details, se devuelve la suma de los montos indicados ahí.

void_invoicesboolean

Indica si las Invoices asociadas a la Transaction quedan anuladas tras la devolución.

Example request

{
  "id_transaction": "trs_pBf2NL0d0gvBM7Ei_1E3HIWnTN4W93_O",
  "idempotency_key": "5f1c2e0a-8d3b-4c1e-9a7f-2b6d4e8c1a90",
  "invoice_refund_details": [
    {
      "id_invoice": "in_pBf2NL0d0gvBM7Ei_1E3HIWnTN4W93_O"
    }
  ]
}

Response

Successful Response

additional_dataobject

Datos que devolvió el gateway. En las devoluciones que se envían al gateway en línea trae el detalle de su respuesta; en los flujos por lote y asíncronos llega vacío.

errorstring

Motivo por el que la devolución no pudo cerrarse. Llega en null cuando no hubo error.

idstring required

Identificador de la Transaction REVERSED creada para esta devolución.

receipt_urlstring

URL del comprobante de la devolución. Se emite en las devoluciones que se envían al gateway en línea y quedaron exitosas; en los flujos por lote y asíncronos llega en null.

successboolean required

Indica si la devolución quedó cerrada correctamente. En los productos de devolución asíncrona llega en false con error en null, porque la confirmación del gateway se recibe más tarde.

Example response

{
  "id": "trs_pBf2NL0d0gvBM7Ei_1E3HIWnTN4W93_O"
}

Changes

  • a6ef070075b1Revision changes
    • breaking

      request body became required

    • breaking

      the request property // became required

    • breaking

      removed the media type application/json for the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      api operation id ejecutar-una-devolución removed and replaced with refund_transaction_public

    • info

      api tag Refunds added

    • info

      added the new optional header request parameter x-account-key

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the // request property format was generalized from float to no format

    • info

      the request property format was generalized from float to no format

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response's property default value true was removed for the status