Documentación de API de depósito

El siguiente documento presenta información relevante al API de depósito.

Generalidades

El API de depósito ofrece servicios REST para:

  • Crear referencias de depósito de único uso.

  • Crear referencias de depósito permanentes.

  • Habilitar/deshabilitar referencias de depósito permanentes.

  • Consultar detalles de los intentos de depósito relacionados a una referencia (bien sea de único uso o permanente).

  • Notificar al comercio que se integra al API de tpaga sobre un depósito exitoso. Esto se hace a través de un webhook que usted deberá implementar.

Nota

Es importante tener en cuenta que, dependiendo de la integración pactada con tpaga, podría no ser posible crear referencias de depósito permanentes. En consecuencia, es importante que, antes de empezar el desarrollo, conozca muy bien cuál es el modelo que se ajusta a sus necesidades.

Tpaga provee dos ambientes:

Diagramas de flujo

Referencias de depósito de único uso

Diagrama de flujo. Depósito con referencia dinámica

Referencias de depósito permanentes

Diagrama de flujo. Depósito con referencia permanente

Autenticación

Las peticiones se autentican por medio de HTTP Basic Auth. El token es otorgado por el equipo de operaciones de tpaga.

Para más información, consulte:

A continuación mostramos un ejemplo de una petición a nuestro API, enviando el token de autorización, para consultar el listado de referencias de un comercio de prueba.

curl -X GET \
https://staging.apiv2.tpaga.co/api/cashin/v1/public/reference-details/?reference=TSREYSANTANA \
-H 'Authorization: Basic YOUR_TOKEN' \
-H 'Content-Type: application/json'

Y este es un ejemplo de respuesta para dicha petición:

# Respuesta
{
  "is_permanent":true,
  "enabled":true,
  "deposit_intents":[]
}

Servicios expuestos

Crear referencias de depósito de único uso

Este servicio debe ser usado cada vez que su usuario desee hacer un depósito.

Nota

El monto (amount) es un campo opcional. Si se incluye, el valor depositado por su usario tendrá que coincidir con el notificado en este servicio.

curl -X POST \
  https://staging.apiv2.tpaga.co/api/cashin/v1/public/references \
  -H 'Authorization: Basic YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "requester_first_names": "Noa",
    "requester_last_names": "Tamayo Carreño",
    "requester_document_type": "CC",
    "requester_document_number": "111222333",
    "requester_phone_number": "+573000000000",
    "idempotency_token": "c348e1578b91e2f03db5e15a401b99",
    "description": "Referencia para documentar el API de tpaga"
  }'

En la respuesta se entregará, cada vez, una nueva referencia, lista para ser usada. También se incluye el convenio (agreement) que será necesario cuando su usuario se encuentre en el quiosco de uno de nuestros proveedores de depósito.

# Respuesta
{
  "reference":"575657589293",
  "description":"Referencia para documentar el API de tpaga",
  "amount":null,
  "agreement":"110784",
  "idempotency_token":"c348e1578b91e2f03db5e15a401b99",
  "requester_first_names":"Noa",
  "requester_last_names":"Tamayo Carreño",
  "requester_document_type":"CC",
  "requester_document_number":"111222333",
  "requester_email":"",
  "requester_phone_number":"+573000000000"
}

Crear referencias de depósito permanentes

Este servicio debe ser usado una única vez por usuario. Típicamente, ocurriría cuando ocurre un registro en su sistema, dotando a su nuevo usuario de una referencia de depósito permanente.

Nota

Si el servicio es llamado y la referencia ya existía, ésta será habilitada de nuevo, en caso de haber sido deshabilitada.

curl -X POST \
https://staging.apiv2.tpaga.co/api/cashin/v1/public/permanent_references \
-H 'Authorization: Basic YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "reference": "reysantana",
  "requester_first_names": "Mireya",
  "requester_last_names": "Rey Santana",
  "requester_email": "mrsantana@example.com",
  "requester_document_type": "CC",
  "requester_document_number": "333222111",
  "requester_phone_number": "+573000000000",
  "description": "Referencia permanente para documentar el API de tpaga"
}'

En la respuesta se entregará la referencia que su usuario empleará cada vez que desee hacer un depósito. También se incluye el convenio (agreement) que será necesario cuando su usuario se encuentre en el quiosco de uno de nuestros proveedores de depósito.

Nota

Se usará el prefijo único, escogido para su comercio, para construir la referencia permanente.

# Respuesta
{
  "reference":"TSREYSANTANA",
  "agreement":"110784",
  "enabled":true
}

Habilitar/deshabilitar referencias de depósito permanentes

Este servicio puede emplearse para habilitar o deshabilitar referencias de depósito permanentes.

Nota

Tenga en cuenta que este servicio solo está disponible para referencias de depósito permanentes.

curl -X PATCH \
https://staging.apiv2.tpaga.co/api/cashin/v1/public/permanent_references/TSREYSANTANA \
-H 'Authorization: Basic YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "enabled": false
}'

# Respuesta
{
  "reference":"TSREYSANTANA",
  "agreement":"110784",
  "enabled":true
}

Consultar detalles de los intentos de depósito relacionados a una referencia

Este servicio puede emplearse para consultar los detalles relacionados a una referencia creada previamente.

Nota

Este servicio está disponible tanto para referencias de único uso como para aquellas que son permanentes.

curl -X GET \
https://staging.apiv2.tpaga.co/api/cashin/v1/public/reference-details/?reference=TSREYSANTANA \
-H 'Authorization: Basic YOUR_TOKEN' \
-H 'Content-Type: application/json'

Cuando la consulta se hace sobre referencia de único uso, el listado de intentos de depósito en la respuesta solo contendrá un elemento, dado que dicha referencia solo se puede usar una vez. Por el contrario, cuando se suministra una referencia permanente, el listado de intentos de depósito puede contener 0 o más elementos. Una lista vacía indica que no se han hecho depósitos con la referencia suministrada.

# Respuesta
{
  "is_permanent":true,
  "enabled":true,
  "deposit_intents":[]
}

Notificar al comercio sobre un depósito exitoso

Nota

Si aún no ha definido los encabezados o la URL que recibirá los webhook tras finalizar un depósito, por favor contáctenos para hacerlo.

Todo usuario del API debe proporcionar un webhook al cual tpaga pueda notificar cada vez que se complete exitosamente un depósito.

Tpaga hará una solicitud POST a la URL definida por el comercio, dando así por terminado el proceso de depósito.

curl -X POST \
https://example-company.com/notify-me \
-H 'Authorization: Basic 1234567890' \
-H 'Content-Type: application/json' \
-d '{
  "reference": "575657589293",
  "amount": 20000,
  "idempotency_token": "c348e1578b91e2f03db5e15a401b99",
  "efecty_order_id": "999777555"
}'

Tpaga espera una respuesta con estado HTTP 200 OK. En caso contrario, tpaga intentará notificar periódicamente sobre el depósito exitoso, hasta recibir dicha respuesta.

Pruebas

Si aún no ha definido los encabezados o la URL que recibirá los webhook tras finalizar un depósito, por favor contáctenos para hacerlo.

Toda vez que quiera simular un depósito electrónico exitoso, puede seguir estos pasos:

  1. Crear una referencia (permanente o de uso único).

  2. Consutarla a través de uno de nuestros proovedores de depósito.

A través del siguiente CURL puede simular la consulta que harían nuestros proveedores de depósito cuando uno de sus usarios se encuentra en un quiosco para hacer el depósito.

curl -X GET \
  https://staging.apiv2.tpaga.co/api/efecty/payment/{reference} \
  -H 'cache-control: no-cache' \
  -H 'x-api-key: PN0S6yneJJ62TLjSPqb2N5kAi8VujZDf'

Tenga en cuenta que debe cambiar el parámetro reference por aquel que creó en el paso 1.

  1. Notificar la recepción del dinero por parte de uno de nuestros proveedores de depósito.

A través del siguiente CURL puede simular la notificación que harían nuestros proveedores de depósito cuando uno de sus usarios haya entregado el dinero en uno de los quioscos de nuestros proveedores de depósito.

curl -X POST \
  https://staging.apiv2.tpaga.co/api/efecty/payment \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: PN0S6yneJJ62TLjSPqb2N5kAi8VujZDf' \
  -d '{
    "reference": "{reference}",
    "amount": "{amount}",
    "efectyOrderId": "{random_order_id}",
    "efectyOfficeId": "001"
}'

Tenga en cuenta que debe suministrar el valor de {reference}, creado en el paso 1, así como un monto del depósito (amount) y un identificador de orden (efectyOrderId).

Indices and tables