Pagos 2.0 - Documentación de API

Introducción

El presente documento describe los endpoints de la API de TotalCoin para la registración de pagos desde sistemas externos.

Autenticación

El control de acceso a la API se realiza a través del estándar OAuth 2.0 con Bearer Tokens.

Endpoint

POST api/auth/login

Request

{
    "company": "",
    "username": "",
    "password": ""
}

Campo	Tipo	Descripción	Requerido
company	String	Nombre de la empresa	Sí
username	String	Nombre de usuario	Sí
password	String	Contraseña	Sí

Response (HTTP 200)

{
    "token": "",
    "expires_in": 3600
}

Campo	Tipo	Descripción
token	String	Token de autenticación
expires_in	Number	Validez del token en segundos

Errores Comunes

Código	Descripción
401	Credenciales incorrectas o inexistentes
403	No se cuenta con permisos para acceder a la API

Realizar Pago

Realizar una transacción de pago a la cuenta de un cliente.

Endpoint

POST api/payments/transactions

Request

{
    "cbucvu": "",
    "cuitcuil": "",
    "amount": 0,
    "reference": "",
    "notificationUrl": ""
}

Campo	Tipo	Descripción	Requerido
cbucvu	String	Número de CBU / CVU del destinatario de la transacción (22 caracteres)	Sí
cuitcuil	String	Número de CUIT / CUIL del destinatario de la transacción (11 caracteres)	Sí
amount	Number	Importe de la transacción	Sí
reference	String	Número o código de referencia del sistema que origina la transacción	Sí
notificationUrl	String	URL a la cual se notificará el resultado de la transacción	Sí

Response (HTTP 200)

{
    "id": ""
}

Campo	Tipo	Descripción
id	String	Identificador de la transacción recibida correctamente

Errores Comunes

Código	Descripción
400	Datos no válidos para procesar la transacción. Con detalle de la validación
401	No autorizado a realizar la transacción
409	Duplicada. Ya existe una transacción con el mismo número o código de referencia
500	Error al procesar la transacción

Notificación de Resultado (Callback)

Invocación a endpoint informado en el request de Realizar Pago. Contiene el estado de la transacción procesada.

Headers

Clave	Valor
Authorization	SHA256 Hash

Body

{
  "body": {
    "id": "",
    "status": ""
  },
  "securityKey": ""
}

Campo	Tipo	Descripción
body	Object	Objeto con los datos de la transacción
id	String	Identificador de la transacción
status	String	Descripción del estado actual de la transacción
securityKey	String	Campo vacío que deberá completarse con la clave privada proporcionada

ACLARACIÓN SOBRE EL ESTADO INFORMADO
En algunos casos el estado informado no corresponderá a un estado final, esto se debe a demoras en el procesamiento por parte de BIND. Por lo qué deberá ser consultado el estado con el endpoint Consultar Pago.

Cálculo del Hash

Para calcular el hash, enviado en la clave Authorization de Headers, proceder de la siguiente forma:

Al JSON recibido, agregar al campo securityKey la clave privada proporcionada por un canal seguro
Convertir el JSON completo a minúsculas
Calcular el hash con SHA256

Ejemplo:

JSON recibido:
{"Body":{"Id":"E6451028-84CE-4FA4-B3BC-335972BEBF0A","Status":"Failed"},"Securitykey":""}

Clave privada: 09B4ET8C4EB24S8ABTA8B8A

JSON con el campo SecurityKey:
{"Body":{"Id":"E6451028-84CE-4FA4-B3BC-335972BEBF0A","Status":"Failed"},"Securitykey":"09B4ET8C4EB24S8ABTA8B8A"}

JSON convertido a minúsculas:
{"body":{"id":"e6451028-84ce-4fa4-b3bc-335972bebf0a","status":"failed"},"securitykey":"09b4et8c4eb24s8abta8b8a"}

Hash:
4e36de37b87010d301e4b3a9046befe24ef253a98746f1d43998f29c31e188d4

Consultar Pago

Consultar el estado de un pago específico.

Endpoint

GET api/payments/transactions/{id}

Request

api/payments/transactions/00000000-0000-0000-0000-000000000000

Campo	Tipo	Descripción	Requerido
id	String	Identificador de la transacción	Sí

Response (HTTP 200)

{
    id: "",
    status: "",
    amount: 0.00,
    date: "",
    reference: ""
}

Campo	Tipo	Descripción
id	String	Identificador de la transacción recibida correctamente
status	String	Descripción del estado actual de la transacción
amount	decimal	Importe de la transacción
date	String	Fecha de la transacción
reference	String	Número o código de referencia del sistema que origina la transacción

Errores Comunes

Código	Descripción
400	Datos no válidos para procesar la consulta
401	No autorizado a realizar la consulta
404	Transacción no encontrada
500	Error al procesar la consulta

Estados de la Transacción

Estado	Descripción
Processed	Transacción procesada correctamente. Estado Final.
Failed	Transacción rechazada. Estado Final.
Processing	Transacción validada y en proceso. Deberá consultarse nuevamente.
Pending	Transacción recibida y pendiente de procesamiento. Deberá consultarse nuevamente.

Consultar Pago por Id Externo

Consultar el estado de un pago específico a partir del identificador externo.

Endpoint

GET api/payments/transactions/{id}/external

Request

api/payments/transactions/0000000/external

Campo	Tipo	Descripción	Requerido
id	String	Identificador de la transacción	Sí

Response (HTTP 200)

{
    id: "",
    status: "",
    amount: 0.00,
    date: "",
    reference: ""
}

Campo	Tipo	Descripción
id	String	Identificador de la transacción recibida correctamente
status	String	Descripción del estado actual de la transacción
amount	decimal	Importe de la transacción
date	String	Fecha de la transacción
reference	String	Número o código de referencia del sistema que origina la transacción

Errores Comunes

Código	Descripción
400	Datos no válidos para procesar la consulta
401	No autorizado a realizar la consulta
404	Transacción no encontrada
500	Error al procesar la consulta