Skip to Content
Transferencias BancariasPayments API

Payments API

Crea un pago único por transferencia bancaria y obtén un CVU/alias exclusivo para esa orden.

Crear un pago

Prod

POST https://api.talo.com.ar/payments/

Sandbox

POST https://sandbox-api.talo.com.ar/payments/

Este endpoint es público y no requiere Authorization header. El campo user_id en el body identifica al comercio.

Campos requeridos

CampoTipoDescripción
user_idstringID de tu cuenta Talo (sandbox o producción)
price.amountnumberMonto del pago (positivo)
price.currencystringMoneda. Valores soportados: "ARS", "BNB", "USDT", "BRL"
payment_optionsstring[]Métodos de pago: "transfer", "crypto", "pix"

Campos opcionales

CampoTipoDescripción
external_idstringID único de tu orden en tu sistema
webhook_urlstringURL donde recibirás notificaciones de cambios de estado
redirect_urlstringURL a donde redirigir al cliente al terminar el pago
motivestringMotivo del pago
client_dataobjectDatos del cliente (ver detalle abajo)
team_idstringID del equipo (para usuarios con múltiples equipos)
tagsstring[]Etiquetas para categorizar el pago
partner_idstringID del partner que origina el pago (ver nota abajo)

Partners: si estás creando pagos en nombre de un comercio como partner, incluí el campo partner_id con tu identificador de partner. Esto permite distinguir qué pagos de una cuenta fueron originados por el comercio y cuáles fueron atribuidos al partner.

Campos de client_data

Todos los campos dentro de client_data son opcionales:

CampoTipoDescripción
first_namestringNombre del cliente
last_namestringApellido del cliente
phonestringTeléfono del cliente
emailstringE-mail del cliente
dnistringDNI del cliente
cuitstringCUIT/CUIL del cliente

Ejemplo de solicitud

curl -X POST https://sandbox-api.talo.com.ar/payments/ \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "f61876b0-10a5-4e39-8e2c-17343b3fa1b6",
    "price": { "amount": 30000, "currency": "ARS" },
    "payment_options": ["transfer"],
    "external_id": "ORDER_123",
    "webhook_url": "https://tu-sitio.com/webhooks/talo",
    "client_data": {
      "first_name": "Juan",
      "last_name": "Pérez",
      "email": "juan@example.com",
      "dni": "12345678"
    }
  }'

Respuesta

{
	data: {
		id: "VAR-f61876b0-FDF_124", // ID interno de Talo
		payment_status: "PENDING",
		quotes: [
			{
				cvu: "0000630500000060195375",
				alias: "talo.ago.1468",
			},
		],
		payment_url: "https://talo.com.ar/payments/VAR-f618...",
		expiration_timestamp: "2024-09-02T14:00:15.411Z",
	},
}

Muestra al cliente el cvu o alias, o simplemente redirígelo a payment_url.

Estados del pago

EstadoDescripción
PENDINGEsperando transferencia
SUCCESSSe acreditó el monto exacto
OVERPAIDSe recibió más de lo solicitado
UNDERPAIDSe recibió menos de lo solicitado
EXPIREDEl CVU venció (~5 días)

Para OVERPAID y UNDERPAID, decide si aceptas la orden o emites reembolso manual.

Simular pago en sandbox

POST https://sandbox-api.talo.com.ar/cvu/{cvu}/faucet

Parámetros del path

CampoTipoDescripción
cvustringCVU donde recibir el pago

Parámetros del body

CampoTipoRequeridoDescripción
amountnumberSíMonto a simular en pesos
cuitstringNoCUIT del emisor simulado

Ejemplo de simulación

curl -X POST \
  "https://sandbox-api.talo.com.ar/cvu/0000630500000060195375/faucet" \
  -H "Authorization: Bearer $TALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 30000 }'

Payload del webhook:

{
	"message": "Pago Actualizado",
	"paymentId": "VAR-f61876b0-FDF_124",
	"externalId": "ORDER_123"
}

Consultar un pago

GET https://sandbox-api.talo.com.ar/payments/{paymentId}

Parámetros del path

CampoTipoDescripción
paymentIdstringID interno de Talo del pago

Campos de la respuesta

CampoTipoDescripción
payment_statusstringEstado del pago
payment_urlstringURL para completar el pago
expiration_timestampstringFecha de vencimiento (ISO 8601)
quotes[0].addressstringCVU para transferir
quotes[0].aliasstringAlias de la cuenta
price.amountnumberMonto del pago
price.currencystringMoneda
payment_optionsstring[]Métodos de pago
external_idstringID de la orden
webhook_urlstringURL de webhook
redirect_urlstringURL de redirección
motivestringMotivo del pago
transaction_fieldsobjectCampos de la transacción. Presente una vez que se haya realizado el pago.
transactionsobject[]Transacciones. Presente una vez que se haya recibido alguna transferencia para el pago.

Ejemplo de consulta

curl -H "Authorization: Bearer $TALO_TOKEN" \
  https://sandbox-api.talo.com.ar/payments/VAR-f61876b0-FDF_124

Ejemplo de respuesta

{
	"message": "ok",
	"error": false,
	"code": 200,
	"data": {
		"price": {
			"amount": 30000,
			"currency": "ARS"
		},
		"creation_timestamp": "2024-08-28T14:00:15.411Z",
		"last_modified_timestamp": "2024-08-28T14:00:15.411Z",
		"user_id": "f61876b0-10a5-4e39-8e2c-17343b3fa1b6",
		"external_id": "FDF_124",
		"redirect_url": "https://example.com/payment/123",
		"webhook_url": "https://example.com/webhooks/payments",
		"quotes": [
			{
				"currency": "ARS",
				"network": "POLLUX",
				"amount": "30000",
				"amountReadable": "30000",
				"address": "0000630500000060195375",
				"alias": "talo.ago.1468"
			}
		],
		"is_deleted": false,
		"payment_status": "SUCCESS",
		"id": "VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-FDF_124",
		"user_info": {
			"email": "example@example.com",
			"fiat_payments_enabled": false,
			"payment_notifications": false,
			"user_id": "f61876b0-10a5-4e39-8e2c-17343b3fa1b6",
			"payment_url": "https://d3e9ln1d0tu6ol.cloudfront.net/payments/VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-FDF_124",
			"payment_options": ["transfer"],
			"provider": "email",
			"expiration_timestamp": "2024-09-02T14:00:15.411Z",
			"transactions": [
				{
					"address": "0000630500000060195375",
					"amount": "30000",
					"commission": 0.605,
					"commission_amount": "1053.51",
					"commission_taxes": [
						{
							"tax_amount": 6.32,
							"tax_rate": 0.6,
							"tax_type": "DEBIT"
						}
					],
					"commission_tax_amount": "6.32",
					"creation_timestamp": "2025-03-12T03:35:32.405Z",
					"credited_amount": "172029.37",
					"currency": "ARS",
					"network": "POLLUX",
					"sender_address": "00000031123456789",
					"taxes": [
						{
							"tax_amount": 1044.80,
							"tax_rate": 0.6,
							"tax_type": "CREDIT"
						}
					],
					"tax_amount": "1044.80",
					"transaction_data": {
						"PROCESSED": {
							"amount": 30000,
							"currency": "ARS",
							"recipient": "0000630500000060195375",
							"recipientCuit": "30123456789",
							"recipientTitular": "EXAMPLE SA",
							"sender": "00000031123456789",
							"senderCuit": "20997654321",
							"senderTitular": "Carolina Perez",
							"trxId": "1b5a952a-8a79-4003-b06a-e4043d453456"
						}
					}
				}
			]
		},
		"transaction_fields": {
			"amount": "30000",
			"amountReadable": "30000",
			"commission_amount": "1053.51",
			"credited_amount": "172029.37",
			"currency": "ARS",
			"network": "POLLUX",
			"total_paid": {
				"amount": "30000",
				"currency": "ARS"
			}
		}
	}
}

Listar pagos

GET https://sandbox-api.talo.com.ar/payments/

Requiere Authorization: Bearer header.

Query parameters

CampoTipoRequeridoDescripción
user_idstringSíID del usuario cuyos pagos se quieren consultar
team_idstringNoFiltrar por equipo
start_datestringNoFecha de inicio (ISO 8601)
end_datestringNoFecha de fin (ISO 8601)

Ejemplo

curl -H "Authorization: Bearer $TALO_TOKEN" \
  "https://sandbox-api.talo.com.ar/payments/?user_id=f61876b0-10a5-4e39-8e2c-17343b3fa1b6&start_date=2026-07-01T00:00:00.000Z&end_date=2026-07-31T23:59:59.000Z"

Ejemplo de respuesta (real, sandbox)

{
	message: "ok",
	error: false,
	code: 200,
	data: {
		payments: [
			{
				id: "VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-DOCFIX-1784132231",
				external_id: "DOCFIX-1784132231",
				payment_status: "SUCCESS",
				price: { amount: 1200, currency: "ARS" },
				quotes: [
					{
						currency: "ARS",
						network: "POLLUX",
						amount: "1200",
						amountReadable: "1200",
						address: "0000716149000693369021",
						alias: "jul.807995.talo",
					},
				],
				payment_options: ["transfer"],
				payment_url: "https://sandbox.talo.com.ar/payments/VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-DOCFIX-1784132231",
				creation_timestamp: "2026-07-15T16:17:15.863Z",
				last_modified_timestamp: "2026-07-15T16:19:02.380Z",
				is_deleted: false,
			},
		],
		// No hay campo "cursor" ni "lastEvaluatedKey" en este endpoint hoy.
	},
}

Consultar pago público

GET https://sandbox-api.talo.com.ar/payments/{paymentId}/public

Este endpoint es público y no requiere autenticación. Retorna un subconjunto de la información del pago.

Parámetros del path

CampoTipoDescripción
paymentIdstringID interno de Talo del pago

Actualizar expiración del pago

PUT https://sandbox-api.talo.com.ar/payments/{payment_id}/expiration

Permite extender la fecha de expiración de un pago en estado PENDING.

Parámetros del path

CampoTipoDescripción
payment_idstringID interno de Talo del pago

Campos requeridos

CampoTipoDescripción
expiration_timestampstringNueva fecha de expiración (ISO 8601)

Ejemplo

curl -X PUT https://sandbox-api.talo.com.ar/payments/VAR-f61876b0-FDF_124/expiration \
  -H "Authorization: Bearer $TALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_timestamp": "2024-09-10T14:00:00.000Z"
  }'

Respuesta real (verificado en sandbox): este endpoint no usa el envelope {message, error, code, data} del resto de la API — devuelve directamente el objeto payment actualizado, con HTTP 200.

Ejemplo de respuesta (real, sandbox)

{
	id: "VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-DOCFIX-1784132231",
	external_id: "DOCFIX-1784132231",
	payment_status: "PENDING",
	price: { amount: 1000, currency: "ARS" },
	quotes: [
		{
			alias: "jul.807995.talo",
			currency: "ARS",
			amount: "1000",
			amountReadable: "1000",
			address: "0000716149000693369021",
			network: "POLLUX",
		},
	],
	payment_options: ["transfer"],
	payment_url: "https://sandbox.talo.com.ar/payments/VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-DOCFIX-1784132231",
	creation_timestamp: "2026-07-15T16:17:15.863Z",
	last_modified_timestamp: "2026-07-15T16:17:36.719Z",
	expiration_timestamp: "2026-07-25T14:00:00.000Z", // <- actualizado
	is_deleted: false,
}

Actualizar precio del pago

PUT https://sandbox-api.talo.com.ar/payments/{paymentId}/price

Permite actualizar el precio de un pago. Si el pago está en estado SUCCESS, OVERPAID o UNDERPAID, se recalculará el estado basado en el nuevo precio y se enviará una notificación al webhook configurado.

Parámetros del path

CampoTipoDescripción
paymentIdstringID interno de Talo del pago

Campos requeridos

CampoTipoDescripción
currencystringCódigo de moneda ("ARS")
amountnumberNuevo monto del pago

No se puede actualizar el precio de un pago en estado EXPIRED.

Ejemplo

curl -X PUT https://sandbox-api.talo.com.ar/payments/VAR-f61876b0-FDF_124/price \
  -H "Authorization: Bearer $TALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "ARS",
    "amount": 35000
  }'

Respuesta real (verificado en sandbox): al igual que PUT .../expiration, este endpoint no usa el envelope {message, error, code, data} — devuelve directamente el objeto payment actualizado, con HTTP 200.

Ejemplo de respuesta (real, sandbox)

{
	id: "VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-DOCFIX-1784132231",
	external_id: "DOCFIX-1784132231",
	payment_status: "PENDING",
	price: { currency: "ARS", amount: 1200 }, // <- actualizado
	quotes: [
		{
			alias: "jul.807995.talo",
			currency: "ARS",
			amount: "1200", // <- el monto del quote también se actualiza
			amountReadable: "1200",
			address: "0000716149000693369021",
			network: "POLLUX",
		},
	],
	payment_options: ["transfer"],
	payment_url: "https://sandbox.talo.com.ar/payments/VAR-f61876b0-10a5-4e39-8e2c-17343b3fa1b6-DOCFIX-1784132231",
	creation_timestamp: "2026-07-15T16:17:15.863Z",
	last_modified_timestamp: "2026-07-15T16:17:40.353Z",
	expiration_timestamp: "2026-07-25T14:00:00.000Z",
	is_deleted: false,
}

Actualizar metadatos del pago

Permite modificar campos específicos del pago con seguimiento de historial.

Prod

PUT https://api.talo.com.ar/payments/{paymentId}/metadata

Sandbox

PUT https://sandbox-api.talo.com.ar/payments/{paymentId}/metadata

Parámetros del path

CampoTipoDescripción
paymentIdstringID interno de Talo del pago

Campos requeridos

CampoTipoDescripción
motivestringMotivo del pago

Ejemplo de solicitud

curl -X PUT https://sandbox-api.talo.com.ar/payments/VAR-f61876b0-FDF_124/metadata \
  -H "Authorization: Bearer $TALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "motive": "Compra de productos - actualizado"
  }'

Respuesta real (verificado en sandbox)

Comportamiento real verificado (sandbox, 2026-07-15): la respuesta es HTTP 200 con body null, no el envelope {message, error, code, data} de abajo. El cambio sí se aplica (confirmado con un GET /payments/{paymentId} inmediatamente después — el motive y el historial en metadata.motive[] quedan actualizados), pero la respuesta del PUT no lo confirma. Recomendación: no confíes en el body de este PUT — hacé un GET /payments/{paymentId} después para confirmar que el cambio se aplicó.

null

HTTP status: 200

El shape de abajo ({message, error, code, data}) es el que la API está diseñada para devolver, y podría volver a funcionar si se corrige el bug de backend — pero hoy no es lo que se recibe:

{
	"message": "Metadata updated successfully",
	"error": false,
	"code": 200,
	"data": {
		"motive": "Compra de productos - actualizado",
		"metadata": {
			"motive": [
				{
					"value": "Compra de productos - actualizado",
					"previous": "Compra de productos",
					"modified_by": "user@example.com",
					"modification_timestamp": "2024-09-02T15:30:45.123Z"
				}
			]
		}
	}
}

Funcionalidad

  • Historial de cambios: Cada modificación se registra con el valor anterior, nuevo valor, usuario que realizó el cambio y timestamp
  • Validación de permisos: Solo el propietario del pago puede modificar los metadatos
  • Campos disponibles: Actualmente solo se permite modificar el campo motive
  • Confirmá con un GET: dado que el PUT no devuelve confirmación fiable, hacé GET /payments/{paymentId} después de cada actualización de metadata para verificar que se aplicó

Los cambios de metadatos quedan registrados permanentemente en el historial del pago.

UX recomendado

  • Temporizador: muestra cuenta regresiva hasta expiration_timestamp.
  • Copy‑to‑clipboard: botón para copiar CVU y alias.
  • Botón “Abrir Home Banking” (link a apps comunes) para acelerar la transferencia.

Lista para pasar a cuentas permanentes? Lee Customers API →

Last updated on
Customers API (Clientes fijos)Crear reembolso para un pago