TRtrytoku
Payments

Registrar Payments

Changed on

Registra pagos ya realizados sobre Invoices.

Se usa para informar pagos que ocurrieron fuera de Toku —transferencias, caja, efectivo— y para mantener sincronizados los pagos que Toku ya procesó. Acepta varios Payments en una sola llamada.

Cada Payment se referencia por el Invoice que salda, no por un identificador propio: envía invoice_external_id, o bien product_id y due_date para que Toku lo construya como {product_id}-{due_date}.

Si el Invoice ya tiene un pago registrado, la llamada lo actualiza con los datos nuevos en vez de agregar otro.

Cada Payment enviado se resuelve en uno de estos resultados:

  • success: el pago quedó registrado, o el Invoice ya estaba pagado a través de Toku y no hubo nada que registrar.
  • duplicates: el Payment repite la combinación product_id + due_date + invoice_external_id de otro elemento del mismo lote. Solo se procesa el primero.
  • not_found: no existe un Invoice que coincida con los identificadores enviados, o está anulado.
  • error: el Invoice tiene un cobro en curso a través de Toku, ya fue pagado por Toku, o el id_payment_intent enviado no corresponde a un cobro autorizado.

Los Payments no procesados se detallan en errors_detail, agrupados por motivo, con los identificadores que enviaste.

Que algunos elementos del lote fallen no convierte la respuesta en un error: se devuelve 200 con el recuento por resultado. Revisa esos contadores para saber qué pasó con cada Payment enviado.

post/payments

Request

  • Base URL
    https://api.trytoku.com
  • URL
    https://api.trytoku.com/payments
  • 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

Example request

{
  "payments": [
    {
      "due_date": "202101",
      "id_payment_intent": "pi_1YPKc-NZPwxBYf6hnLsstaqG9JAZKxX9",
      "invoice_external_id": "9897af7987d9245d-202101",
      "payment_amount": 1000,
      "product_id": "9897af7987d9245d"
    }
  ]
}

Response

Recuento por resultado del lote.

duplicatesinteger

Payments repetidos dentro del mismo lote. Se procesa la primera aparición y las siguientes se descartan.

errorinteger

Payments que no pudieron procesarse por un error de negocio.

format_errorinteger

Payments rechazados por el formato de los datos enviados.

not_foundinteger

Payments cuyo Invoice no existe o no está disponible.

successinteger

Payments procesados correctamente.

Changes

  • a6ef070075b1Revision changes
    • breaking

      request body became required

    • breaking

      the // request property's minLength was increased from 0 to 1

    • breaking

      the // request property type changed from string to no type, and format from date-time to no format

    • warning

      the // request property's maxLength was set to 32

    • warning

      the // request property's maxLength was set to 64

    • warning

      the // request property's maxLength was set to 256

    • warning

      the // request property's min was set to 0.00

    • warning

      removed the optional property from the response with the status

    • info

      api operation id crear-o-modificar-payment removed and replaced with create_update_payment

    • info

      api tag Payments added

    • info

      endpoint deprecated

    • 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

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added subschema #1 subschema #2 to the // request property anyOf list

    • info

      the // request property type was generalized from integer to number, and format from int32 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

      removed the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status