Tpaga Cashin API 0.0.1 ====================== .. toctree:: :maxdepth: 3 Description ~~~~~~~~~~~ Tpaga Cashin API [Learn about tpaga](https://tpaga.co) Contact Information ~~~~~~~~~~~~~~~~~~~ TPaga S.A.S. info@tpaga.co https://tpaga.co License ~~~~~~~ `Apache 2.0 `_ Base URL ~~~~~~~~ https://staging.apiv2.tpaga.co/api/cashin/v1/public/ Security ~~~~~~~~ .. _securities_api_key: api_key (HTTP Basic Authentication) ----------------------------------- *Authentication using tpaga's account API key* CREATE REFERENCES ~~~~~~~~~~~~~~~~~ POST ``/permanent_references`` ------------------------------ Summary +++++++ Create a permanent reference which can be used several times. Description +++++++++++ .. raw:: html This service should be requested only once per user. Typically, you will use this endpoint when the user is created in your system, giving them a lifelong deposit reference. If the given `reference` already existed when calling this service, it will be marked as enabled, regardless its previous state. Request +++++++ .. _d_9fffe09a5784feee8982796c19c1ee34: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 agreement | No | string | | | The agreement (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider each time that they want to make a deposit. description | Yes | string | | | Some details about the permanent deposit reference. enabled | No | boolean | | | Tells whether the permanent reference can be used (enabled) or not (disabled). reference | No | string | | | The reference (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider each time that they want to make a deposit. When making a request, send a 10-chars long string, which may contain both numbers and letters. The output value will be prefixed with a two-chars string which identifies you in **tpaga**'s system. Therefore, in the provided example, the output will be `TSREYSANTANA`, where `TS` is the prefix which represents the (T)e(S)t API user who makes the request. You will have to provide the prefixed reference whenever you want to get details from it or whenever you want to enable/disable it. requester_document_number | Yes | string | | | Document number of the user who owns the permanent deposit reference. requester_document_type | Yes | string | | {'enum': ['CC', 'CE']} | Document type of the user who owns the permanent deposit reference. requester_email | Yes | string | | | Email of the user who owns the permanent deposit reference. requester_first_names | Yes | string | | | First names of the user who owns the permanent deposit reference. requester_last_names | Yes | string | | | Last names of the user who owns the permanent deposit reference. requester_phone_number | Yes | string | | | Phone number of the user who owns the permanent deposit reference. .. code-block:: javascript { "agreement": "somestring", "description": "somestring", "enabled": true, "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring" } Responses +++++++++ **200** ^^^^^^^ The permanent deposit reference was created successfully. Type: :ref:`PermanentDepositReference ` **Example:** .. code-block:: javascript { "agreement": "somestring", "description": "somestring", "enabled": true, "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring" } **401** ^^^^^^^ Unauthorized **422** ^^^^^^^ Client errors when making the request. The payload will have enough info about how to solve the problem in order to re-try the request. Type: :ref:`ValidationError ` **Example:** .. code-block:: javascript { "error_message": "somestring", "field": "somestring", "value": "somestring" } POST ``/references`` -------------------- Summary +++++++ Create a reference which can be used only once. Description +++++++++++ .. raw:: html This service must be requested each time that your user wants to make a deposit. When providing the `amount`, it must be the same as the amount that your user will deposit at one of the kiosks of the **tpaga**'s Cashin Providers. The response of this service includes the `reference` and the `agreement` codes. Both of them will have to be provided by your user at the kiosk. Request +++++++ .. _d_d11e649831822c70c1622a93c49f534a: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 agreement | No | string | | | The agreement (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider whenever they want to make a deposit amount | No | integer | | | Amount that the user creating the deposit reference wants to deposit. When this property is provided, the user will have to give that amount of money to the agent of the **tpaga**'s Cashin Provider. description | Yes | string | | | Some details about the deposit intent. idempotency_token | Yes | string | | | Idempotency token which identifies the deposit reference uniquely in order not to process the same request twice. reference | No | string | | | The reference (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider whenever they want to make a deposit. It is a 12-chars string and may contain both number and letters. requester_document_number | Yes | string | | | Document number of the user creating the deposit reference. requester_document_type | Yes | string | | {'enum': ['CC', 'CE']} | Document type of the user creating the deposit reference. requester_email | Yes | string | | | Email of the user creating the deposit reference. requester_first_names | Yes | string | | | First names of the user creating the deposit reference. requester_last_names | Yes | string | | | Last names of the user creating the deposit reference. requester_phone_number | Yes | string | | | Phone number of the user creating the deposit reference. .. code-block:: javascript { "agreement": "somestring", "amount": 1, "description": "somestring", "idempotency_token": "somestring", "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring" } Responses +++++++++ **200** ^^^^^^^ The deposit reference was created successfully. Type: :ref:`DepositReference ` **Example:** .. code-block:: javascript { "agreement": "somestring", "amount": 1, "description": "somestring", "idempotency_token": "somestring", "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring" } **401** ^^^^^^^ Unauthorized **422** ^^^^^^^ Client errors when making the request. The payload will have enough info about how to solve the problem in order to re-try the request. Type: :ref:`ValidationError ` **Example:** .. code-block:: javascript { "error_message": "somestring", "field": "somestring", "value": "somestring" } GET REFERENCES ~~~~~~~~~~~~~~ GET ``/reference-details/`` --------------------------- Summary +++++++ Get details from the deposit intent(s) related to a reference code. Description +++++++++++ .. raw:: html This service works for both permanent references and those that are meant to be used only once. When requesting this service with a reference code of unique use, the `deposit_intents` array will have only one item, because of the fact that the reference cannot be used anymore. On the other hand, when you are requesting this service with a permanent reference, then the `deposit_intents` array may contain 0 or more items. 0 means that your user has not made any deposits yet. We will give you a maximum of 20 deposit intents. At least one of `reference` or `idempotency_token` query parameters has to be provided. We want that all of the deposit intents from your users end up with a `paid` status. If they don't, please contact us in order to check what happened. Parameters ++++++++++ .. csv-table:: :delim: | :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 15, 10, 10, 10, 20, 30 reference | query | No | string | | | The reference code that you want get details from. Take into account that at least one of `reference` or `idempotency_token` has to be provided. idempotency_token | query | No | string | | | The idempotency token of the reference that you want get details from. Take into account that at least one of `reference` or `idempotency_token` has to be provided. Request +++++++ Responses +++++++++ **200** ^^^^^^^ Successful operation Type: :ref:`DepositReferenceDetails ` **Example:** .. code-block:: javascript { "deposit_intents": [ { "agreement": "somestring", "amount": 1, "description": "somestring", "idempotency_token": "somestring", "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring", "status": "paid" }, { "agreement": "somestring", "amount": 1, "description": "somestring", "idempotency_token": "somestring", "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring", "status": "paid" } ], "enabled": true, "is_permanent": true } **401** ^^^^^^^ Unauthorized **422** ^^^^^^^ Client errors when making the request. The payload will have enough info about how to solve the problem in order to re-try the request. Type: :ref:`ValidationError ` **Example:** .. code-block:: javascript { "error_message": "somestring", "field": "somestring", "value": "somestring" } UPDATE REFERENCES ~~~~~~~~~~~~~~~~~ PATCH ``/permanent_references/{reference}`` ------------------------------------------- Summary +++++++ Enable / disable the permanent reference. Description +++++++++++ .. raw:: html This service enables or disables a permanent reference. Please note that it is **only** available for permanent references. Parameters ++++++++++ .. csv-table:: :delim: | :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 15, 10, 10, 10, 20, 30 reference | path | Yes | string | | | The 12-chars long reference code of the object that you want to enable/disable. Take into account that you must provide the prefixed reference that you receive when creating it. Request +++++++ .. _i_c90ca1181729c295c2349fd44435e9d1: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 enabled | No | boolean | | {'enum': [True, False]} | Provide `false` for disabling the reference and `true` for enabling it. .. code-block:: javascript { "enabled": true } Responses +++++++++ **200** ^^^^^^^ The permanent deposit reference was updated successfully. Type: :ref:`PermanentDepositReference ` **Example:** .. code-block:: javascript { "agreement": "somestring", "description": "somestring", "enabled": true, "reference": "somestring", "requester_document_number": "somestring", "requester_document_type": "CC", "requester_email": "somestring", "requester_first_names": "somestring", "requester_last_names": "somestring", "requester_phone_number": "somestring" } **401** ^^^^^^^ Unauthorized **422** ^^^^^^^ Client errors when making the request. The payload will have enough info about how to solve the problem in order to re-try the request. Type: :ref:`ValidationError ` **Example:** .. code-block:: javascript { "error_message": "somestring", "field": "somestring", "value": "somestring" } Data Structures ~~~~~~~~~~~~~~~ .. _d_58540ca75b1016b3f83f7223949d05a9: DepositIntent Model Structure ----------------------------- :ref:`DepositReference ` extended :ref:`inline ` .. _i_6f671c1a5e025cb71ed32184719e322f: **Inline schema:** .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 agreement | No | string | | | The agreement (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider whenever they want to make a deposit amount | No | integer | | | Amount that the user creating the deposit reference wants to deposit. When this property is provided, the user will have to give that amount of money to the agent of the **tpaga**'s Cashin Provider. description | Yes | string | | | Some details about the deposit intent. idempotency_token | Yes | string | | | Idempotency token which identifies the deposit reference uniquely in order not to process the same request twice. reference | No | string | | | The reference (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider whenever they want to make a deposit. It is a 12-chars string and may contain both number and letters. requester_document_number | Yes | string | | | Document number of the user creating the deposit reference. requester_document_type | Yes | string | | {'enum': ['CC', 'CE']} | Document type of the user creating the deposit reference. requester_email | Yes | string | | | Email of the user creating the deposit reference. requester_first_names | Yes | string | | | First names of the user creating the deposit reference. requester_last_names | Yes | string | | | Last names of the user creating the deposit reference. requester_phone_number | Yes | string | | | Phone number of the user creating the deposit reference. status | Yes | string | | {'enum': ['paid', 'pending']} | The status of the deposit intent from the given reference, after the user has deposited some money in of the kiosks from the **tpaga**'s Cashin Providers. .. _d_d11e649831822c70c1622a93c49f534a: DepositReference Model Structure -------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 agreement | No | string | | | The agreement (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider whenever they want to make a deposit amount | No | integer | | | Amount that the user creating the deposit reference wants to deposit. When this property is provided, the user will have to give that amount of money to the agent of the **tpaga**'s Cashin Provider. description | Yes | string | | | Some details about the deposit intent. idempotency_token | Yes | string | | | Idempotency token which identifies the deposit reference uniquely in order not to process the same request twice. reference | No | string | | | The reference (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider whenever they want to make a deposit. It is a 12-chars string and may contain both number and letters. requester_document_number | Yes | string | | | Document number of the user creating the deposit reference. requester_document_type | Yes | string | | {'enum': ['CC', 'CE']} | Document type of the user creating the deposit reference. requester_email | Yes | string | | | Email of the user creating the deposit reference. requester_first_names | Yes | string | | | First names of the user creating the deposit reference. requester_last_names | Yes | string | | | Last names of the user creating the deposit reference. requester_phone_number | Yes | string | | | Phone number of the user creating the deposit reference. .. _d_a37163e03b9d0db2be643237d2254635: DepositReferenceDetails Model Structure --------------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 deposit_intents | No | array of :ref:`DepositReference ` extended :ref:`inline ` | | | List of deposit intents related to the given reference. enabled | No | boolean | | {'enum': [True, False]} | Tells whether the reference is enabled or not. Take into account that only permanent refereces can be enabled/disabled. is_permanent | No | boolean | | {'enum': [True, False]} | Tells whether the reference is permanent or not. .. _d_9fffe09a5784feee8982796c19c1ee34: PermanentDepositReference Model Structure ----------------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 agreement | No | string | | | The agreement (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider each time that they want to make a deposit. description | Yes | string | | | Some details about the permanent deposit reference. enabled | No | boolean | | | Tells whether the permanent reference can be used (enabled) or not (disabled). reference | No | string | | | The reference (code) that the user will have to show to the agent of the **tpaga**'s Cashin Provider each time that they want to make a deposit. When making a request, send a 10-chars long string, which may contain both numbers and letters. The output value will be prefixed with a two-chars string which identifies you in **tpaga**'s system. Therefore, in the provided example, the output will be `TSREYSANTANA`, where `TS` is the prefix which represents the (T)e(S)t API user who makes the request. You will have to provide the prefixed reference whenever you want to get details from it or whenever you want to enable/disable it. requester_document_number | Yes | string | | | Document number of the user who owns the permanent deposit reference. requester_document_type | Yes | string | | {'enum': ['CC', 'CE']} | Document type of the user who owns the permanent deposit reference. requester_email | Yes | string | | | Email of the user who owns the permanent deposit reference. requester_first_names | Yes | string | | | First names of the user who owns the permanent deposit reference. requester_last_names | Yes | string | | | Last names of the user who owns the permanent deposit reference. requester_phone_number | Yes | string | | | Phone number of the user who owns the permanent deposit reference. .. _d_e9795eeb02f3ec6623a540289fed71c6: ValidationError Model Structure ------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 error_message | Yes | string | | | Human-friendly description of the error. field | No | string | | | Name of the field with the wrong piece of data, if it applies. value | No | string | | | value that caused the validation error in the specified field, if it applies