.. Cashin API documentation master file, created by sphinx-quickstart on Fri Apr 24 14:57:48 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. 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. .. note:: 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: * Ambiente de pruebas: https://staging.apiv2.tpaga.co * Ambiente de producción: https://production.apiv2.tpaga.co Diagramas de flujo ------------------ Referencias de depósito de único uso ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/flujo_ref_dinamica.png :alt: Diagrama de flujo. Depósito con referencia dinámica :align: center Referencias de depósito permanentes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/flujo_ref_permanente.png :alt: Diagrama de flujo. Depósito con referencia permanente :align: center 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: * https://en.wikipedia.org/wiki/Basic_access_authentication * https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication 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. .. code-block:: bash 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: .. code-block:: bash # 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. .. note:: 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. .. code-block:: bash 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. .. code-block:: bash # 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. .. note:: Si el servicio es llamado y la referencia ya existía, ésta será habilitada de nuevo, en caso de haber sido deshabilitada. .. code-block:: bash 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. .. note:: Se usará el prefijo único, escogido para su comercio, para construir la referencia permanente. .. code-block:: bash # 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. .. note:: Tenga en cuenta que este servicio solo está disponible para referencias de depósito permanentes. .. code-block:: bash 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 }' .. code-block:: bash # 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. .. note:: Este servicio está disponible tanto para referencias de único uso como para aquellas que son permanentes. .. code-block:: bash 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. .. code-block:: bash # Respuesta { "is_permanent":true, "enabled":true, "deposit_intents":[] } Notificar al comercio sobre un depósito exitoso ----------------------------------------------- .. note:: 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. .. code-block:: bash 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. .. code-block:: bash 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. 3. 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. .. code-block:: bash 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``). Swagger ====================================== .. toctree:: :maxdepth: 2 :caption: Contents: swagger Indices and tables ================== * :ref:`genindex` * :ref:`search`