Tpaga Wallet Payment Codes API 1.0.0 ==================================== .. toctree:: :maxdepth: 3 Base URL ~~~~~~~~ http://stag.wallet.tpaga.co/merchants/api/v1/payment_requests Security ~~~~~~~~ .. _securities_UserAuth: UserAuth (HTTP Basic Authentication) ------------------------------------ DEFAULT ~~~~~~~ GET ``/{payment_request_token}/info`` ------------------------------------- Description +++++++++++ .. raw:: html Returns information of a payment request. Parameters ++++++++++ .. csv-table:: :delim: | :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 15, 10, 10, 10, 20, 30 payment_request_token | path | Yes | string | | | Request +++++++ Responses +++++++++ **200** ^^^^^^^ Information of a payment request. Type: :ref:`PaymentRequest ` **Example:** .. code-block:: javascript { "cancelled_at": "somestring", "cost": "somestring", "expires_at": "somestring", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "status": "created", "terminal_id": "somestring", "token": "somestring", "tpaga_payment_url": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp was disabled. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **422** ^^^^^^^ Parameter is not valid. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" GET ``/users/{tpaga_user_token}/info`` -------------------------------------- Description +++++++++++ .. raw:: html Returns information from a user. Parameters ++++++++++ .. csv-table:: :delim: | :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 15, 10, 10, 10, 20, 30 tpaga_user_token | path | Yes | string | | | Request +++++++ Responses +++++++++ **200** ^^^^^^^ Basic information from a user. Type: :ref:`UserInformationResponse ` **Example:** .. code-block:: javascript { "email": "somestring", "first_name": "somestring", "identification_number": "somestring", "identification_type": "somestring", "last_name": "somestring", "phone_number": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp is disabled or forbidden. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **422** ^^^^^^^ Parameter is not valid. Type: :ref:`InputError ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" POST ``/cancel`` ---------------- Description +++++++++++ .. raw:: html Cancels a payment_request if it is in status CREATED. Request +++++++ .. _d_33a47da7bb7f8b2186f5a7abb9b80093: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 payment_request_token | No | string | | | .. code-block:: javascript { "payment_request_token": "somestring" } Responses +++++++++ **200** ^^^^^^^ Payment request was cancelled. Type: :ref:`PaymentRequest ` **Example:** .. code-block:: javascript { "cancelled_at": "somestring", "cost": "somestring", "expires_at": "somestring", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "status": "created", "terminal_id": "somestring", "token": "somestring", "tpaga_payment_url": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp was disabled. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **409** ^^^^^^^ Payment request status does not allow to cancel it. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **422** ^^^^^^^ Payload is not valid. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" POST ``/confirm_delivery`` -------------------------- Description +++++++++++ .. raw:: html Notifies that a payment request was delivered successfully. Request +++++++ .. _d_33a47da7bb7f8b2186f5a7abb9b80093: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 payment_request_token | No | string | | | .. code-block:: javascript { "payment_request_token": "somestring" } Responses +++++++++ **200** ^^^^^^^ Payment request was marked as delivered. Type: :ref:`PaymentRequest ` **Example:** .. code-block:: javascript { "cancelled_at": "somestring", "cost": "somestring", "expires_at": "somestring", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "status": "created", "terminal_id": "somestring", "token": "somestring", "tpaga_payment_url": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp was disabled. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **422** ^^^^^^^ Parameter is not valid. Type: :ref:`InputError ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" POST ``/create`` ---------------- Description +++++++++++ .. raw:: html Creates payment request. Request +++++++ .. _d_e84266285544be557cda3b61e8dd5414: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 cost | Yes | integer | | | Payment request cost. expires_at | Yes | string | date-time | | Payment request expiration date in ISO8601 format. idempotency_token | Yes | string | | | Unique payment identifier offered by the miniapp. merchant_user_id | No | string | | | Offered by the miniapp. miniapp_user_token | Yes | string | | | Identifies the miniapp in calls from the mobile client and wallet. order_id | Yes | string | | | Order identifier offered by the miniapp. purchase_description | Yes | string | | | Payment description that will be shown to the user by the mobile app. purchase_details_url | Yes | string | | | URL that the user will be redirected to once the payment is done. purchase_items | No | :ref:`purchase_items ` | | | Optional detail of the items that belong to this transaction. terminal_id | Yes | string | | | Offered by the miniapp to identify the product/service or device involved. user_ip_address | Yes | string | | | IP of the user that created the payment request. voucher_url | No | string | | | URL that holds the voucher of a transaction. .. _i_87a81752b0b61234d6f7a46e5c35247d: **Purchase_items schema:** Optional detail of the items that belong to this transaction. .. code-block:: javascript { "cost": 1, "expires_at": "2015-01-01T15:00:00.000Z", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "terminal_id": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } Responses +++++++++ **201** ^^^^^^^ Payment request was created Type: :ref:`PaymentRequest ` **Example:** .. code-block:: javascript { "cancelled_at": "somestring", "cost": "somestring", "expires_at": "somestring", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "status": "created", "terminal_id": "somestring", "token": "somestring", "tpaga_payment_url": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp was disabled. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **409** ^^^^^^^ Payment request already exists Type: :ref:`BusinessError ` **Example:** .. code-block:: javascript { "data": {}, "error_code": 1, "error_message": "somestring" } **422** ^^^^^^^ Payload is not valid. Type: :ref:`InputError ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" POST ``/{payment_request_token}/confirm_delivery`` -------------------------------------------------- Description +++++++++++ .. raw:: html Notifies that a payment request was delivered successfully. Parameters ++++++++++ .. csv-table:: :delim: | :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 15, 10, 10, 10, 20, 30 payment_request_token | path | Yes | string | | | Request +++++++ Responses +++++++++ **200** ^^^^^^^ Payment request was marked as delivered. Type: :ref:`PaymentRequest ` **Example:** .. code-block:: javascript { "cancelled_at": "somestring", "cost": "somestring", "expires_at": "somestring", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "status": "created", "terminal_id": "somestring", "token": "somestring", "tpaga_payment_url": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp was disabled. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **422** ^^^^^^^ Parameter is not valid. Type: :ref:`InputError ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" POST ``/refund`` ---------------- Description +++++++++++ .. raw:: html Reverts a payment and notifies to the buyer via Tpaga wallet about the payment has been reverted Request +++++++ .. _d_33a47da7bb7f8b2186f5a7abb9b80093: Body ^^^^ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 payment_request_token | No | string | | | .. code-block:: javascript { "payment_request_token": "somestring" } Responses +++++++++ **200** ^^^^^^^ Payment request was reverted, the status should be 'reverted'. Type: :ref:`PaymentRequest ` **Example:** .. code-block:: javascript { "cancelled_at": "somestring", "cost": "somestring", "expires_at": "somestring", "idempotency_token": "somestring", "merchant_user_id": "somestring", "miniapp_user_token": "somestring", "order_id": "somestring", "purchase_description": "somestring", "purchase_details_url": "somestring", "purchase_items": {}, "status": "created", "terminal_id": "somestring", "token": "somestring", "tpaga_payment_url": "somestring", "user_ip_address": "somestring", "voucher_url": "somestring" } **401** ^^^^^^^ Unauthorized **403** ^^^^^^^ The product/service related to the miniapp was disabled. Please contact Tpaga support. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **409** ^^^^^^^ Payment request status does not allow to revert it. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } **422** ^^^^^^^ Payload is not valid. Type: :ref:`DataErrorModel ` **Example:** .. code-block:: javascript { "error_code": 1, "error_message": "somestring", "field_name": "somestring", "rejected_value": "somestring" } Security ++++++++ .. csv-table:: :header: "Security Schema", "Scopes" :widths: 15, 45 :ref:`UserAuth `, "" Data Structures ~~~~~~~~~~~~~~~ .. _d_02f8c168cf2845096217308cce6695bd: BusinessError Model Structure ----------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 data | No | :ref:`data ` | | | Business entity related to the error. error_code | No | integer | | | error_message | No | string | | | Human-friendly description of the business error .. _i_7e6bae6a3c98963d00b2bbd37a6bdde8: **Data schema:** Business entity related to the error. .. _d_cb7a7478c214bab50ae536676e256a1a: DataErrorModel Model Structure ------------------------------ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 error_code | No | integer | | | error_message | No | string | | | human-friendly description of the validation error field_name | No | string | | | name of the field whose validation failed rejected_value | No | string | | | string representation of the rejected value .. _d_2a3b02e182adfa6252468733348a9e64: InputError Model Structure -------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 error_code | No | integer | | | error_message | No | string | | | Human-friendly description of the validation error field_name | No | string | | | Name of the field whose validation failed rejected_value | No | string | | | String representation of the rejected value .. _d_e84266285544be557cda3b61e8dd5414: PaymentCreationRequest Model Structure -------------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 cost | Yes | integer | | | Payment request cost. expires_at | Yes | string | date-time | | Payment request expiration date in ISO8601 format. idempotency_token | Yes | string | | | Unique payment identifier offered by the miniapp. merchant_user_id | No | string | | | Offered by the miniapp. miniapp_user_token | Yes | string | | | Identifies the miniapp in calls from the mobile client and wallet. order_id | Yes | string | | | Order identifier offered by the miniapp. purchase_description | Yes | string | | | Payment description that will be shown to the user by the mobile app. purchase_details_url | Yes | string | | | URL that the user will be redirected to once the payment is done. purchase_items | No | :ref:`purchase_items ` | | | Optional detail of the items that belong to this transaction. terminal_id | Yes | string | | | Offered by the miniapp to identify the product/service or device involved. user_ip_address | Yes | string | | | IP of the user that created the payment request. voucher_url | No | string | | | URL that holds the voucher of a transaction. .. _i_87a81752b0b61234d6f7a46e5c35247d: **Purchase_items schema:** Optional detail of the items that belong to this transaction. .. _d_98197a5f98a4a9fd7827a1c710ecf0c5: PaymentRequest Model Structure ------------------------------ .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 cancelled_at | No | string | | | Date when the payment_request was cancelled. cost | No | string | | | Payment request cost. expires_at | No | string | | | Date when the payment_request will expire. idempotency_token | No | string | | | Unique payment identifier offered by the miniapp. merchant_user_id | No | string | | | Offered by the miniapp. miniapp_user_token | No | string | | | Identifies the miniapp in calls from the mobile client and wallet. order_id | No | string | | | Order identifier offered by the miniapp. purchase_description | No | string | | | Payment description that will be shown to the user by the mobile app. purchase_details_url | No | string | | | URL that will be shown to the user in the pyos once the payment is done. purchase_items | No | :ref:`purchase_items ` | | | Optional detail of the items that belong to this transaction. status | No | string | | {'enum': ['created', 'charge_in_progress', 'paid', 'charge_failed', 'reverted', 'delivered', 'expired', 'cancelled']} | terminal_id | No | string | | | Offered by the miniapp to identify the product/service or device involved. token | No | string | | | Unique payment request token generated by Tpaga. tpaga_payment_url | No | string | | | Payment link used to open the payment widget in Tpaga app. user_ip_address | No | string | | | IP of the user that created the payment request. voucher_url | No | string | | | URL that holds the voucher url of the miniapp. .. _i_87a81752b0b61234d6f7a46e5c35247d: **Purchase_items schema:** Optional detail of the items that belong to this transaction. .. _d_33a47da7bb7f8b2186f5a7abb9b80093: PaymentRequestToken Model Structure ----------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 payment_request_token | No | string | | | .. _d_eb2188fa059ac0ddd9cef1cae4747d90: UserInformationResponse Model Structure --------------------------------------- .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 email | No | string | | | Email of the user. first_name | No | string | | | First name of the user. identification_number | No | string | | | Identification number of the user. identification_type | No | string | | | Identification type of the user. last_name | No | string | | | Last name of the user. phone_number | No | string | | | Phone number of the user.