Developers

Referencia técnicaTechnical reference

Tranzmit Payers API

Generada directamente del archivo OpenAPI oficial. Cada campo, tipo y valor que aparece acá sale del spec, no de una transcripción. Incluye además los dos flujos de procesamiento, el ciclo de vida de la transacción y los métodos de entrega. Generated straight from the official OpenAPI file. Every field, type and value here comes from the spec, not from a transcription. It also covers the two processing flows, the transaction lifecycle and the delivery methods.

Servidor y versiónServer and version

Staging

https://payers-api.stg.tranzmit.net

VersiónVersion

api-version: 1.0

OpenAPI

3.0.4

Dentro de la versión mayor solo habrá cambios aditivos: endpoints nuevos, parámetros opcionales, campos en las respuestas y códigos nuevos de error o de rechazo. El cliente debe tolerarlos sin romperse. Within the major version only additive changes will happen: new endpoints, optional parameters, extra response fields and new error or rejection codes. The client must tolerate them without breaking.

AutenticaciónAuthentication

OAuth 2.0 con el flujo de credenciales de cliente. Se pide un token y se manda en cada llamada. OAuth 2.0 with the client credentials flow. Request a token and send it on every call.

curl
curl -X POST 'https://sso.stg.tranzmit.net/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=$CLIENT_ID' \
  -d 'client_secret=$CLIENT_SECRET'

Los dos flujos de integraciónThe two integration flows

Cuál de los dos usas depende de cómo pagas, no de un ajuste en la API.Which one you use depends on how you pay, not on a setting in the API.

Flujo de ventanillaOffice pickup flow

El beneficiario llega con su número de referencia. Buscas la transacción, la asignas, pagas y confirmas. Es el flujo natural para OFFICE-PICKUP.The recipient arrives with their reference number. You find the transaction, assign it, pay and confirm. It is the natural flow for OFFICE-PICKUP.

Opcional · repetibleOptional · repeatable Escenario positivoPositive scenario Escenario negativoNegative scenario Tu sistemaYour system Payers APIPayers API GET /transactions/referenceNumber={refNum} Transaction POST /transactions/{id}/payout-assignment Transaction + PayoutToken Pasa a READY-FOR-PAYOUTMoves to READY-FOR-PAYOUT POST /transactions/{id}/payout-updates El estado no cambiaStatus does not change Transaction POST /transactions/{id}/payout-confirmation Pasa a PAIDMoves to PAID Transaction POST /transactions/{id}/payout-rejection Pasa a REJECTEDMoves to REJECTED Transaction
Flujo de ventanilla: el beneficiario llega con su número de referencia.Office pickup flow: the recipient arrives with a reference number.

Flujo por lotesBatch flow

Tu sistema le pregunta a la API qué hay pendiente, reconoce cada transacción para que nadie más la tome y las procesa una por una. Es el flujo para depósito a cuenta, billetera móvil y todo lo que no sea ventanilla.Your system asks the API what is pending, acknowledges each transaction so nobody else takes it, and processes them one by one. It is the flow for bank deposit, mobile wallet and anything that is not office pickup.

Opcional · repetibleOptional · repeatable Escenario positivoPositive scenario Escenario negativoNegative scenario Tu sistemaYour system Payers APIPayers API GET /transactions/query-available?limit=&delivery_method= Batch of Transactions POST /transactions/{id}/acknowledgement Sale del lote disponibleLeaves the available pool Transaction POST /transactions/{id}/payout-assignment Transaction + PayoutToken Pasa a READY-FOR-PAYOUTMoves to READY-FOR-PAYOUT POST /transactions/{id}/payout-updates El estado no cambiaStatus does not change Transaction POST /transactions/{id}/payout-confirmation Pasa a PAIDMoves to PAID Transaction POST /transactions/{id}/payout-rejection Pasa a REJECTEDMoves to REJECTED Transaction
Flujo por lotes: tu sistema jala las transacciones y las procesa una por una.Batch flow: your system pulls transactions and processes them one by one.

Ciclo de vida de una transacciónTransaction lifecycle

Cinco estados. Saber en cuál está una transacción te dice exactamente qué puedes hacer con ella.Five states. Knowing which one a transaction is in tells you exactly what you can do with it.

payout-assignmentpayout-assignment se libera o expiraunassigned or expired payout-confirmationpayout-confirmation reversa del pago, dentro de 24 hpayout reversal, within 24 h payout-rejectionpayout-rejection el remitente cancelasender cancels PENDING READY-FOR-PAYOUT PAID CANCELLED REJECTED
Los cinco estados. Solo PENDING y READY-FOR-PAYOUT aceptan acciones tuyas; PAID, REJECTED y CANCELLED cierran la transacción.The five states. Only PENDING and READY-FOR-PAYOUT accept your actions; PAID, REJECTED and CANCELLED close the transaction.
EstadoStatusQué significaWhat it means
PENDINGDisponible para que la tomes y la proceses.Available to be picked up and processed by you.
READY-FOR-PAYOUTYa está asignada a ti. Es el único estado desde el que puedes confirmar o rechazar.Already assigned to you. It is the only state from which you can confirm or reject.
PAIDProcesada. Los fondos se entregaron al beneficiario.Processed. Funds were delivered to the recipient.
REJECTEDNo se pudo procesar. La rechazaste con un ReasonCode.Could not be processed. You rejected it with a ReasonCode.
CANCELLEDEl remitente la cancelo. Ya no se puede procesar.The sender cancelled it. It can no longer be processed.
DatoNote

La asignación al pago caduca, y el tiempo depende del método de entrega. El objeto de la transacción trae su fecha de expiración. Si vence, la transacción vuelve sola a PENDING y queda disponible para cualquiera. Lo mismo pasa si la liberas tú con DELETE /payout-assignment.The payout assignment expires, and the time depends on the delivery method. The transaction object carries its expiry. On expiry the transaction returns to PENDING on its own and becomes available to anyone. The same happens if you release it yourself with DELETE /payout-assignment.

Métodos de entregaDelivery methods

El método viene en la transacción y define cómo le haces llegar el dinero al beneficiario.The method comes with the transaction and defines how you get the money to the recipient.

CódigoCodeMétodoMethodCómo se entregaHow it is delivered
BANK-DEPOSITDepósito a cuentaBank depositLos fondos van directo a la cuenta bancaria del beneficiario.Funds go straight into the recipient's bank account.
OFFICE-PICKUPRetiro en ventanillaOffice pickupEl beneficiario recoge el efectivo en tu sucursal u oficina.The recipient picks up cash at your branch or office.
MOBILE-WALLETBilletera móvilMobile walletLos fondos llegan directo a la billetera móvil del beneficiario.Funds are delivered directly to the recipient's mobile wallet.
HOME-DELIVERYEntrega a domicilioHome deliveryLos fondos se entregan en la dirección del beneficiario.Funds are delivered at the recipient's location.
ATM-PICKUPRetiro en cajeroATM pickupEl beneficiario retira los fondos en un cajero automático.The recipient withdraws the funds at an ATM.

EndpointsEndpoints

GET/api/transactions/{id}

Buscar por identificadorFind transaction

Consulta una transacción por su identificador primario. Sirve para refrescar el estado en cualquier momento del proceso.Finds transaction by its primary id

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
curl
curl -X GET 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0'
GET/api/transactions/referenceNumber={refNum}

Buscar por número de referenciaFind transaction by reference number

El beneficiario llega a tu ventanilla con el número que le dio el remitente. Este es el punto de entrada del flujo de ventanilla.Finds transaction by reference number provided by the recipient. Usually the endpoint is used for transactions with OFFICE-PICKUP delivery method.

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
refNumpathTipoTypetextotextobligatoriorequiredNúmero de referencia que trae el beneficiario.Reference number the recipient brings.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
curl
curl -X GET 'https://payers-api.stg.tranzmit.net/api/transactions/referenceNumber=8451207733' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0'
GET/api/transactions/query-available

Consultar lote disponibleQuery available transactions

Devuelve un lote de transacciones disponibles. Una transacción está disponible cuando sigue en PENDING y nadie la ha reconocido todavía. Es el punto de entrada del flujo por lotes.Finds a batch of available transactions according to provided parameters. Transaction is available when it is in PENDING status and has not been acknowledged before. Usually the endpoint is used for transactions where batch processing is possible (BANK-DEPOSIT, HOME-DELIVERY, MOBILE-WALLET) together with /{id}/acknowledgement API.

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
delivery_methodqueryTipoTypetextotext
BANK-DEPOSIT HOME-DELIVERY MOBILE-WALLET
opcionaloptionalMétodo de entrega por el que se filtra el lote. OFFICE-PICKUP no aplica: ese flujo entra por número de referencia.Delivery method the batch is filtered by. OFFICE-PICKUP does not apply: that flow enters by reference number.
limitqueryTipoTypeenterointegeropcionaloptionalCuántas transacciones traer en el lote. Hasta 100; si no se manda, 10.limit, not more than 100, default 10 (máx. 100)
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionsTipoTypearreglo dearray of TransactionLas transacciones del lote.transactions
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
curl
curl -X GET 'https://payers-api.stg.tranzmit.net/api/transactions/query-available?limit=50&delivery_method=BANK-DEPOSIT' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0'
POST/api/transactions/{id}/acknowledgement

Reconocer la transacciónAcknowledge transaction

Saca la transacción del lote disponible para que ningún otro proceso la tome. No cambia el estado: sigue en PENDING. Va siempre de la mano de query-available.Acknowledges the transaction. Acknowledgement removes transactions from the list of "available" transactions. Acknowledgement does not change transaction status, leaving it in PENDING status. Usually the endpoint is used for transactions with non OFFICE-PICKUP delivery method (where batch processing is possible) together with /query-available API.

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.CONFLICT — La transacción ya fue reconocida.transaction is already acknowledged.
curl
curl -X POST 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/acknowledgement' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0'
POST/api/transactions/{id}/payout-assignment

Asignar al pagoAssign transaction to payout

El paso que reserva la transacción para vos. La respuesta trae el PayoutToken: guardalo, porque sin él no podés confirmar, rechazar ni comentar. Mientras la tengás asignada, nadie más puede tocarla. La asignación vence, y al vencer la transacción regresa a PENDING.Assigns transaction in PENDING status to payout. Transaction transitions from PENDING to READY-FOR-PAYOUT status. Assignment operation generates transaction PayoutToken. The client is supposed to record PayoutToken which is returned in response, that value is mandatory for further transaction processing toward end status. Transactions assigned to payout cannot be changed by anyone except the client holding PayoutToken. Assignment is time-limited (depends on delivery method), transaction object contains info about its expiry. Assignment expiration transitions transaction back to PENDING status.

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
Cuerpo de la peticiónRequest body
CampoFieldTipoTypeDescripciónDescription
clientTokenTipoTypetextotextopcionaloptionalToken del cliente. Opcional, texto libre, hasta 64 caracteres. Permite reintentar la petición cuando hay un problema momentáneo de comunicación: llamar varias veces con el mismo clientToken devuelve siempre la misma respuesta.client token (optional), free text, max length 64 characters token allowing request to be retried multiple times to overcome transient communication errors, calling current endpoint multiple times with the same clientToken results in identical response
versionTipoTypeenterointegerobligatoriorequiredVersión de la transacción que conoce el cliente. Tiene que coincidir con la versión actual para que la asignación se haga.transaction version client is aware of. Provided version should match with current transaction version for successful assignment
agentTipoTypetextotextopcionaloptionalAgente del pagador. Opcional, texto libre, hasta 60 caracteres.payer agent (optional), free text, max length 60 characters
additionalInfoTipoTypeAdditionalInfoRequestopcionaloptionalInformación adicional. Opcional, hasta 5 pares de clave y valor; la clave admite 60 caracteres y el valor 500.additional info (optional), up to 5 key-value pairs key max length 60 characters value max length 500 characters
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
payoutTokenTipoTypetextotextToken de pago. Es obligatorio para todas las operaciones siguientes sobre la transacción, y es lo que te da acceso exclusivo a ella. Se entrega una sola vez, acá en esta respuesta: si se cae la red justo en ese momento, el valor se pierde y no hay forma de recuperarlo. Para cubrirte, mandá el parámetro clientToken en la petición; llamando varias veces con el mismo clientToken recibís siempre la misma respuesta, con el mismo payoutToken.payout token. Token is mandatory to perform all subsequent transaction update operations. payout token authorizes caller for exclusive access to transaction, thus is exposed only once here in response. Therefore in case of transient error (due to network glitch) payoutToken value might get lost with no possibility to retrieve it. In order to gracefully handle transient errors with retry use clientToken request parameter, calling current endpoint multiple times with the same clientToken results in identical response, containing payoutToken
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.CONFLICT — Ya está asignada al pago, o la versión que mandaste no coincide con la versión real de la transacción.transaction is already assigned to payout or transaction version in request does not match actual transaction version.
curl
curl -X POST 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/payout-assignment' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  -d '{
      "version": 1
  }'
DELETE/api/transactions/{id}/payout-assignment

Liberar la asignaciónUnassign transaction from payout

Devuelve la transacción a PENDING para que otro la tome. Usalo cuando el beneficiario se fue sin cobrar o no vas a poder procesarla ahorita. Requiere el PayoutToken.Unassigns transaction in READY-FOR-PAYOUT status from payout. Transaction returns to PENDING state. Unassigning transaction from payout requires PayoutToken generated before to be passed (see POST {id}/payout-assignment).

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
Cuerpo de la peticiónRequest body
CampoFieldTipoTypeDescripciónDescription
payoutTokenTipoTypetextotextobligatoriorequiredToken de pago.payout token (no vacío)(not empty)
reasonTipoTypetextotextopcionaloptionalMotivo por el que liberás la asignación. Opcional, hasta 500 caracteres.unassignment reason (optional), free text, max length 500 characters
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.PAYOUT-TOKEN-MISMATCH — El PayoutToken que mandaste no es válido.specified in request PayoutToken is invalid.
  • 409PAYERS-API.CONFLICT — El estado de la transacción no es READY-FOR-PAYOUT.transaction status is not READY-FOR-PAYOUT.
curl
curl -X DELETE 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/payout-assignment' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  -d '{
      "payoutToken": "$PAYOUT_TOKEN"
  }'
POST/api/transactions/{id}/payout-updates

Enviar actualizacionesCreate transaction payout update

Comparte información sin mover el estado. Dos tipos: COMPLIANCE para la verificación de cumplimiento que corrás sobre esa transacción, y COMMENT para texto libre que consideres útil. Podés mandar las que necesités.Creates additional updates about transaction processing of two types: COMPLIANCE - about compliance check that takes place for current transaction COMMENT - free form comment that the client considers reasonable to share Creating additional updates does not cause transaction status changes. Creating additional updates requires PayoutToken generated before to be passed (see POST {id}/payout-assignment).

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
Cuerpo de la peticiónRequest body
CampoFieldTipoTypeDescripciónDescription
payoutTokenTipoTypetextotextobligatoriorequiredToken de pago.payout token (no vacío)(not empty)
typeTipoTypetextotext
COMPLIANCE COMMENT
obligatoriorequiredTipo de actualización. COMPLIANCE para el resultado de la verificación de cumplimiento que corrás sobre la transacción; COMMENT para texto libre.Update type. COMPLIANCE for the result of the compliance check you run on the transaction; COMMENT for free text. (no vacío)(not empty)
noteTipoTypetextotextobligatoriorequiredNota en texto libre, hasta 500 caracteres.note, free text, max length 500 characters (máx. 500, no vacío)(max 500, not empty)
additionalInfoTipoTypeAdditionalInfoRequestopcionaloptionalInformación adicional. Opcional, hasta 5 pares de clave y valor; la clave admite 60 caracteres y el valor 500.additional info (optional), up to 5 key-value pairs key max length 60 characters value max length 500 characters
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.PAYOUT-TOKEN-MISMATCH — El PayoutToken que mandaste no es válido.specified in request PayoutToken is invalid.
  • 409PAYERS-API.CONFLICT — La transacción no está asignada al pago.transaction is not assigned to payout.
curl
curl -X POST 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/payout-updates' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  -d '{
      "note": "Verificacion de cumplimiento aprobada",
      "payoutToken": "$PAYOUT_TOKEN",
      "type": "COMPLIANCE"
  }'
POST/api/transactions/{id}/payout-confirmation

Confirmar el pagoConfirm transaction payout

Le decís a Tranzmit que el beneficiario ya tiene su dinero. Es el cierre feliz del flujo y requiere el PayoutToken.Confirms payout of transaction in READY-FOR-PAYOUT status. Transaction transitions to PAID status. Confirming transaction payout requires PayoutToken generated before to be passed (see POST {id}/payout-assignment).

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
Cuerpo de la peticiónRequest body
CampoFieldTipoTypeDescripciónDescription
payoutTokenTipoTypetextotextobligatoriorequiredToken de pago.payout token (no vacío)(not empty)
clientTimestampUtcTipoTypefecha y horadate and timeobligatoriorequiredMarca de tiempo del pago en el sistema del pagador, en UTC.utc timestamp of payout event in payer/client system
additionalInfoTipoTypeAdditionalInfoRequestopcionaloptionalInformación adicional. Opcional, hasta 5 pares de clave y valor; la clave admite 60 caracteres y el valor 500.additional info (optional), up to 5 key-value pairs key max length 60 characters value max length 500 characters
recipientKycTipoTypeRecipientKycRequestopcionaloptional
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.PAYOUT-TOKEN-MISMATCH — El PayoutToken que mandaste no es válido.specified in request PayoutToken is invalid.
  • 409PAYERS-API.CONFLICT — No está asignada al pago, o su estado no es READY-FOR-PAYOUT.transaction is not assigned to payout or its status is not READY-FOR-PAYOUT.
  • 500PAYERS-API.INTERNAL-ERROR — Error inesperado; por ejemplo, no se pudo tokenizar el KYC del beneficiario. No se confirmó nada.unexpected error, e.g. RecipientKyc could not be tokenized. Nothing was confirmed.
curl
curl -X POST 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/payout-confirmation' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  -d '{
      "clientTimestampUtc": "2026-10-15T14:32:08Z",
      "payoutToken": "$PAYOUT_TOKEN"
  }'
DELETE/api/transactions/{id}/payout-confirmation

Reversar una confirmaciónReverse transaction payout confirmation

La válvula de escape: si confirmaste por error, tenés 24 horas desde la confirmación para reversar. La transacción vuelve a PENDING y el proceso arranca de cero.Reverses payout confirmation submitted before. Transaction transitions from PAID back to PENDING status (transaction processing has to be started from scratch). Payout confirmation can be reversed within 24h since payout has been confirmed.

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
Cuerpo de la peticiónRequest body
CampoFieldTipoTypeDescripciónDescription
reasonTipoTypetextotextMotivo de la reversión. Opcional, hasta 500 caracteres.payout reversal reason (optional), free text, max length 500 characters
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.CONFLICT — La confirmación del pago ya no se puede reversar.transaction payout confirmation cannot be reversed.
curl
curl -X DELETE 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/payout-confirmation' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  -d '{
      "reason": "..."
  }'
POST/api/transactions/{id}/payout-rejection

Rechazar la transacciónReject transaction payout

Cuando no podés pagar. Es obligatorio mandar un reasonCode de la lista: de ahí sale el reporte de por qué se cae una transacción. Requiere el PayoutToken.Rejects transaction in READY-FOR-PAYOUT. Transitions transaction from READY-FOR-PAYOUT to REJECTED status. Rejecting the transaction requires PayoutToken generated before to be passed (see POST {id}/payout-assignment).

ParámetrosParameters
NombreNameDóndeInTipoTypeDescripciónDescription
idpathTipoTypetextotextobligatoriorequiredIdentificador de la transacción.Transaction id.
api-versionheaderTipoTypetextotextopcionaloptionalVersión de la API. Hoy, 1.0.API version. Today, 1.0.
Cuerpo de la peticiónRequest body
CampoFieldTipoTypeDescripciónDescription
payoutTokenTipoTypetextotextobligatoriorequiredToken de pago.payout token (no vacío)(not empty)
reasonCodeTipoTypeRejectReasonCode
19 valores — ver abajo19 values — see below
obligatoriorequiredCódigo del motivo de rechazo. Es obligatorio al rechazar.rejection reason code
reasonTipoTypetextotextopcionaloptionalMotivo del rechazo en texto libre. Opcional, hasta 500 caracteres.rejection reason (optional), free text, max length 500 characters
clientTimestampUtcTipoTypefecha y horadate and timeobligatoriorequiredMarca de tiempo del rechazo en el sistema del pagador, en UTC.utc timestamp of rejection event in payer/client system
additionalInfoTipoTypeAdditionalInfoRequestopcionaloptionalInformación adicional. Opcional, hasta 5 pares de clave y valor; la clave admite 60 caracteres y el valor 500.additional info (optional), up to 5 key-value pairs key max length 60 characters value max length 500 characters
RespuestaResponse 200
CampoFieldTipoTypeDescripciónDescription
transactionTipoTypeTransaction
ErroresErrors
  • 403PAYERS-API.FORBIDDEN — El cliente no tiene permiso para usar ese servicio.client is not allowed to use that service.
  • 404PAYERS-API.NOT-FOUND — Transacción no encontrada.transaction not found.
  • 409PAYERS-API.PAYOUT-TOKEN-MISMATCH — El PayoutToken que mandaste no es válido.specified in request PayoutToken is invalid.
  • 409PAYERS-API.CONFLICT — No está asignada al pago, o su estado no es READY-FOR-PAYOUT. Además, el rechazo exige mandar un ReasonCode de la lista.transaction is not assigned to payout or its status is not READY-FOR-PAYOUT. Rejection requires ReasonCode to be specified (see RejectReasonCode).
curl
curl -X POST 'https://payers-api.stg.tranzmit.net/api/transactions/9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44/payout-rejection' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  -d '{
      "clientTimestampUtc": "2026-10-15T14:32:08Z",
      "payoutToken": "$PAYOUT_TOKEN",
      "reasonCode": "PAYERS-API.REJECT.PAYOUT-ATTEMPT-FAILED"
  }'

EsquemasSchemas

Los objetos que viajan en las respuestas y en los cuerpos de las peticiones.The objects carried in responses and request bodies.

Transaction

La transacciónThe transaction

CampoFieldTipoTypeDescripciónDescription
idTipoTypetextotextIdentificador de la transacción.transaction id (solo lectura)(read only)
referenceNumberTipoTypetextotextNúmero de referencia de la transacción. Es el identificador primario de conciliación.transaction reference number Primary reconciliation ID (solo lectura)(read only)
networkTipoTypetextotextRed por la que viaja la transacción.transaction network (solo lectura)(read only)
payerCodeTipoTypetextotextCódigo del pagador.payer code (solo lectura)(read only)
sendingAmountTipoTypeenterointegerMonto enviado, entero positivo en la unidad mínima de la moneda. Por ejemplo, 100 centavos para cobrar $1.00.sending amount, positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency) (solo lectura)(read only)
sendingCurrencyTipoTypetextotextMoneda de envío. Código ISO 4217 de tres letras, en minúsculas.sending currency, three-letter ISO 4217 currency code in lowercase (solo lectura)(read only)
sendingAmountDecimalTipoTypedecimaldecimalMonto enviado con decimales. Es la misma cifra que sendingAmount.decimal sending amount, positive decimal representation of SendingAmount (solo lectura)(read only)
receivingAmountTipoTypeenterointegerMonto a recibir, entero positivo en la unidad mínima de la moneda.receiving amount, positive integer in the smallest currency unit (solo lectura)(read only)
receivingCurrencyTipoTypetextotextMoneda de recepción. Código ISO 4217 de tres letras, en minúsculas.receiving currency, three-letter ISO 4217 currency code in lowercase (solo lectura)(read only)
receivingAmountDecimalTipoTypedecimaldecimalMonto a recibir con decimales. Es la misma cifra que receivingAmount.decimal receiving amount, positive decimal representation of ReceivingAmount (solo lectura)(read only)
settlementAmountTipoTypeenterointegerMonto de liquidación, entero positivo en la unidad mínima de la moneda.settlement amount, positive integer in the smallest currency unit (solo lectura)(read only)
settlementCurrencyTipoTypetextotextMoneda de liquidación. Código ISO 4217 de tres letras, en minúsculas.settlement currency, three-letter ISO 4217 currency code in lowercase (solo lectura)(read only)
settlementAmountDecimalTipoTypedecimaldecimalMonto de liquidación con decimales. Es la misma cifra que settlementAmount.decimal settlement amount, positive decimal representation of SettlementAmount (solo lectura)(read only)
sellRateTipoTypedecimaldecimalTipo de cambio de venta aplicado.exchange sell rate (solo lectura)(read only)
statusTipoTypetextotext
PENDING READY-FOR-PAYOUT PAID REJECTED CANCELLED
Estado de la transacción.Transaction status. (solo lectura)(read only)
senderTipoTypeSender
recipientTipoTypeRecipient
deliveryMethodTipoTypetextotext
BANK-DEPOSIT OFFICE-PICKUP HOME-DELIVERY ATM-PICKUP MOBILE-WALLET
Método de entrega de los fondos al beneficiario.How the funds are delivered to the recipient. (solo lectura)(read only)
bankDepositDetailsTipoTypeBankDepositDetails
officePickupDetailsTipoTypeOfficePickupDetails
acknowledgementTipoTypeTransactionAcknowledgement
payoutTipoTypePayout
createdTipoTypefecha y horadate and timeFecha y hora de creación, en formato ISO-8601 y en UTC.creation date-time in ISO-8601 format, utc (solo lectura)(read only)
updatedTipoTypefecha y horadate and timeFecha y hora de la última actualización, en formato ISO-8601 y en UTC.update date-time in ISO-8601 format, utc (solo lectura)(read only)
versionTipoTypeenterointegerVersión del registro. Cambia con cada modificación.version (solo lectura)(read only)
Sender

El remitenteThe sender

CampoFieldTipoTypeDescripciónDescription
firstNameTipoTypetextotextNombre.first name (solo lectura)(read only)
lastNameTipoTypetextotextApellido.last name (solo lectura)(read only)
middleNameTipoTypetextotextSegundo nombre.middle name (solo lectura)(read only)
mothersMaidenNameTipoTypetextotextApellido materno.mother's maiden name (solo lectura)(read only)
phoneTipoTypetextotextNúmero de teléfono.phone number (solo lectura)(read only)
homeAddressTipoTypeSenderAddress
SenderAddress

Dirección del remitenteSender address

CampoFieldTipoTypeDescripciónDescription
countryTipoTypetextotextPaís. Código ISO 3166 de dos letras, en mayúsculas.country, alpha-2 ISO 3166 country code in upper case (solo lectura)(read only)
stateTipoTypetextotextDepartamento, estado o provincia.state/province (solo lectura)(read only)
cityTipoTypetextotextCiudad.city (solo lectura)(read only)
line1TipoTypetextotextDirección, primera línea.street address line 1 (solo lectura)(read only)
line2TipoTypetextotextDirección, segunda línea.street address line 2 (solo lectura)(read only)
Recipient

El beneficiarioThe recipient

CampoFieldTipoTypeDescripciónDescription
firstNameTipoTypetextotextNombre.first name (solo lectura)(read only)
lastNameTipoTypetextotextApellido.last name (solo lectura)(read only)
middleNameTipoTypetextotextSegundo nombre.middle name (solo lectura)(read only)
mothersMaidenNameTipoTypetextotextApellido materno.mother's maiden name (solo lectura)(read only)
phoneTipoTypetextotextNúmero de teléfono.phone number (solo lectura)(read only)
homeAddressTipoTypeRecipientAddress
RecipientAddress

Dirección del beneficiarioRecipient address

CampoFieldTipoTypeDescripciónDescription
countryTipoTypetextotextPaís. Código ISO 3166 de dos letras, en mayúsculas.country, alpha-2 ISO 3166 country code in upper case (solo lectura)(read only)
stateTipoTypetextotextDepartamento, estado o provincia.state/province (solo lectura)(read only)
cityTipoTypetextotextCiudad.city (solo lectura)(read only)
line1TipoTypetextotextDirección, primera línea.street address line 1 (solo lectura)(read only)
line2TipoTypetextotextDirección, segunda línea.street address line 2 (solo lectura)(read only)
BankDepositDetails

Datos del depósito a cuentaBank deposit details

CampoFieldTipoTypeDescripciónDescription
accountTipoTypetextotextNúmero de cuenta del beneficiario.account number (solo lectura)(read only)
accountTypeTipoTypetextotext
CHECKING SAVINGS
Tipo de cuenta del beneficiario.Recipient account type. (solo lectura)(read only)
branchTipoTypetextotextAgencia o sucursal.branch (solo lectura)(read only)
OfficePickupDetails

Datos del retiro en ventanillaOffice pickup details

CampoFieldTipoTypeDescripciónDescription
locationIdTipoTypetextotextIdentificador del punto de pago donde retira el beneficiario.location id (solo lectura)(read only)
TransactionAcknowledgement

El reconocimientoThe acknowledgement

CampoFieldTipoTypeDescripciónDescription
payerIdTipoTypetextotextIdentificador del pagador.payer id (solo lectura)(read only)
createdTipoTypefecha y horadate and timeFecha y hora en que se reconoció la transacción, en ISO-8601 y en UTC.acknowledgement creation date-time in ISO-8601 format, utc (solo lectura)(read only)
transactionVersionTipoTypeenterointegerVersión de la transacción al momento de reconocerla.acknowledged transaction version (solo lectura)(read only)
Payout

El pagoThe payout

CampoFieldTipoTypeDescripciónDescription
payerIdTipoTypetextotextIdentificador del pagador.payer id (solo lectura)(read only)
assignmentTipoTypePayoutAssignment
confirmationTipoTypePayoutConfirmation
rejectionTipoTypePayoutRejection
expiresAfterTipoTypefecha y horadate and timeFecha y hora en que vence la asignación. Al vencer, la transacción vuelve a PENDING.payout expires after date-time in ISO-8601 format, utc (solo lectura)(read only)
PayoutAssignment

La asignación al pagoThe payout assignment

CampoFieldTipoTypeDescripciónDescription
agentTipoTypetextotextAgente que procesó la operación.agent (solo lectura)(read only)
additionalInfoTipoTypeobjetoobjectInformación adicional.additional info (solo lectura)(read only)
createdTipoTypefecha y horadate and timeFecha y hora de creación, en formato ISO-8601 y en UTC.create date-time in ISO-8601 format, utc (solo lectura)(read only)
PayoutConfirmation

La confirmación del pagoThe payout confirmation

CampoFieldTipoTypeDescripciónDescription
additionalInfoTipoTypeobjetoobjectInformación adicional.additional info (solo lectura)(read only)
clientTimestampTipoTypefecha y horadate and timeMarca de tiempo del sistema del pagador, en formato ISO-8601 y en UTC.client timestamp in ISO-8601 format, utc (solo lectura)(read only)
createdTipoTypefecha y horadate and timeFecha y hora de creación, en formato ISO-8601 y en UTC.create date-time in ISO-8601 format, utc (solo lectura)(read only)
PayoutRejection

El rechazoThe rejection

CampoFieldTipoTypeDescripciónDescription
reasonCodeTipoTypeRejectReasonCode
19 valores — ver abajo19 values — see below
Código del motivo de rechazo. Es obligatorio al rechazar.rejection reason code (solo lectura)(read only)
reasonTipoTypetextotextMotivo.reason (solo lectura)(read only)
additionalInfoTipoTypeobjetoobjectInformación adicional.additional info (solo lectura)(read only)
clientTimestampTipoTypefecha y horadate and timeMarca de tiempo del sistema del pagador, en formato ISO-8601 y en UTC.client timestamp in ISO-8601 format, utc (solo lectura)(read only)
createdTipoTypefecha y horadate and timeFecha y hora de creación, en formato ISO-8601 y en UTC.create date-time in ISO-8601 format, utc (solo lectura)(read only)
RecipientKycRequest
CampoFieldTipoTypeDescripciónDescription
lastNameTipoTypetextotextobligatoriorequired (no vacío)(not empty)
secondLastNameTipoTypetextotextopcionaloptional
firstNameTipoTypetextotextobligatoriorequired (no vacío)(not empty)
middleNameTipoTypetextotextopcionaloptional
dateOfBirthTipoTypetextotextobligatoriorequired
countryOfBirthTipoTypetextotextobligatoriorequired (no vacío)(not empty)
stateOfBirthTipoTypetextotextopcionaloptional
cityOfBirthTipoTypetextotextopcionaloptional
immigrationStatusTipoTypetextotextopcionaloptional
genderTipoTypetextotextobligatoriorequired (no vacío)(not empty)
maritalStatusTipoTypetextotextobligatoriorequired (no vacío)(not empty)
professionOrTradeTipoTypetextotextobligatoriorequired (no vacío)(not empty)
documentTipoTypeRecipientKycDocumentRequestobligatoriorequired
taxIdentificationNumberTipoTypetextotextopcionaloptional
emailAddressTipoTypetextotextopcionaloptional
addressTipoTypeRecipientKycAddressRequestobligatoriorequired
nationalityTipoTypetextotextobligatoriorequired (no vacío)(not empty)
phoneNumberTipoTypetextotextobligatoriorequired (no vacío)(not empty)
guatemalaTipoTypeGuatemalaKycRequestobligatoriorequired
RecipientKycAddressRequest
CampoFieldTipoTypeDescripciónDescription
residentialAddressTipoTypetextotext
countryOfResidenceTipoTypetextotext
stateOfResidenceTipoTypetextotext
cityOfResidenceTipoTypetextotext
RecipientKycDocumentRequest
CampoFieldTipoTypeDescripciónDescription
identificationTypeTipoTypetextotext
identificationNumberTipoTypetextotext
identificationIssuerCountryTipoTypetextotext
identificationIssueDateTipoTypetextotext
identificationExpiryDateTipoTypetextotext
GuatemalaKycRequest
CampoFieldTipoTypeDescripciónDescription
pepTipoTypePoliticallyExposedPersonRequest
apepTipoTypeAssociatedPoliticallyExposedPersonRequest
cpeTipoTypebooleanoboolean
monthlyIncomeTipoTypedecimaldecimal
monthlyExpensesTipoTypedecimaldecimal
relationshipWithSenderTipoTypetextotext
businessTradeNameTipoTypetextotext
employerNameTipoTypetextotext
otherIncomeTipoTypetextotext
incomeDescriptionTipoTypetextotext
paymentStateTipoTypetextotext
paymentCityTipoTypetextotext
AdditionalInfoRequest

Información adicional. Opcional, hasta 5 pares de clave y valor; la clave admite 60 caracteres y el valor 500.additional info (optional), up to 5 key-value pairs key max length 60 characters value max length 500 characters

ProblemDetails

El errorThe error

CampoFieldTipoTypeDescripciónDescription
typeTipoTypetextotext
titleTipoTypetextotext
statusTipoTypeenterointeger
detailTipoTypetextotext
instanceTipoTypetextotext
PoliticallyExposedPersonRequest
CampoFieldTipoTypeDescripciónDescription
publicEntityOfEmploymentTipoTypetextotext
positionHeldTipoTypetextotext
countryOfEntityTipoTypetextotext
originOrSourceOfWealthTipoTypetextotext
AssociatedPoliticallyExposedPersonRequest
CampoFieldTipoTypeDescripciónDescription
relationshipTipoTypetextotext
associationMotiveTipoTypetextotext
genderTipoTypetextotext
immigrationStatusTipoTypetextotext
firstNameTipoTypetextotext
middleNameTipoTypetextotext
lastNameTipoTypetextotext
secondLastNameTipoTypetextotext
publicEntityOfEmploymentTipoTypetextotext
positionHeldTipoTypetextotext
countryOfEntityTipoTypetextotext
originOrSourceOfWealthTipoTypetextotext

Listas de valoresValue lists

status

Estado de la transacciónTransaction status
PENDING READY-FOR-PAYOUT PAID REJECTED CANCELLED

deliveryMethod

Método de entregaDelivery method
BANK-DEPOSIT OFFICE-PICKUP HOME-DELIVERY ATM-PICKUP MOBILE-WALLET

accountType

Tipo de cuentaAccount type
CHECKING SAVINGS

Códigos de rechazoRejection codes

Los 19 valores que acepta reasonCode al rechazar una transacción.The 19 values reasonCode accepts when rejecting a transaction.

PAYERS-API.REJECT.PAYOUT-ATTEMPT-FAILED
PAYERS-API.REJECT.INVALID-OR-EXPIRED-DATA
PAYERS-API.REJECT.INVALID-FX-OR-AMOUNT-CONVERSION
PAYERS-API.REJECT.INVALID-SENDER-ADDRESS
PAYERS-API.REJECT.INVALID-SENDER-DATE-OF-BIRTH
PAYERS-API.REJECT.INVALID-RECIPIENT-ADDRESS
PAYERS-API.REJECT.INVALID-RECIPIENT-ACCOUNT
PAYERS-API.REJECT.RECIPIENT-ACCOUNT-BLOCKED-OR-CANCELLED
PAYERS-API.REJECT.RECIPIENT-ACCOUNT-UNAVAILABLE
PAYERS-API.REJECT.RECIPIENT-ACCOUNT-NOT-REGISTERED
PAYERS-API.REJECT.RECIPIENT-ACCOUNT-NAME-MISMATCH
PAYERS-API.REJECT.RECIPIENT-ACCOUNT-CURRENCY-MISMATCH
PAYERS-API.REJECT.RECIPIENT-ACCOUNT-TYPE-INVALID
PAYERS-API.REJECT.MAX-SEND-AMOUNT-EXCEEDED
PAYERS-API.REJECT.INSUFFICIENT-ACCOUNT-BALANCE
PAYERS-API.REJECT.INVALID-AMOUNT-TO-PAYER
PAYERS-API.REJECT.PAYER-LIMIT-EXCEEDED
PAYERS-API.REJECT.PAYER-COMPLIANCE-REJECTION
PAYERS-API.REJECT.UNKNOWN