| Name | fintoc JSON |
| Version |
2.10.0
JSON |
| download |
| home_page | None |
| Summary | The official Python client for the Fintoc API. |
| upload_time | 2025-07-11 20:36:13 |
| maintainer | Daniel Leal |
| docs_url | None |
| author | Daniel Leal |
| requires_python | <4.0,>=3.7 |
| license | BSD-3-Clause |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
<h1 align="center">Fintoc meets Python 🐍</h1>
<p align="center">
<em>
You have just found the Python-flavored client of <a href="https://fintoc.com/" target="_blank">Fintoc</a>.
</em>
</p>
<p align="center">
<a href="https://pypi.org/project/fintoc" target="_blank">
<img src="https://img.shields.io/pypi/v/fintoc?label=version&logo=python&logoColor=%23fff&color=306998" alt="PyPI - Version">
</a>
<a href="https://github.com/fintoc-com/fintoc-python/actions?query=workflow%3Atests" target="_blank">
<img src="https://img.shields.io/github/workflow/status/fintoc-com/fintoc-python/tests?label=tests&logo=python&logoColor=%23fff" alt="Tests">
</a>
<a href="https://codecov.io/gh/fintoc-com/fintoc-python" target="_blank">
<img src="https://img.shields.io/codecov/c/gh/fintoc-com/fintoc-python?label=coverage&logo=codecov&logoColor=ffffff" alt="Coverage">
</a>
<a href="https://github.com/fintoc-com/fintoc-python/actions?query=workflow%3Alinters" target="_blank">
<img src="https://img.shields.io/github/workflow/status/fintoc-com/fintoc-python/linters?label=linters&logo=github" alt="Linters">
</a>
</p>
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Quickstart](#quickstart)
- [Calling endpoints](#calling-endpoints)
- [list](#list)
- [get](#get)
- [create](#create)
- [update](#update)
- [delete](#delete)
- [V2 Endpoints](#v2-endpoints)
- [Nested actions or resources](#nested-actions-or-resources)
- [Webhook Signature Validation](#webhook-signature-validation)
- [Idempotency Keys](#idempotency-keys)
- [Generate the JWS Signature](#gnerate-the-jws-signature)
- [Serialization](#serialization)
- [Acknowledgements](#acknowledgements)
## Installation
Install using pip!
```sh
pip install fintoc
```
**Note:** This SDK requires [**Python 3.6+**](https://docs.python.org/3/whatsnew/3.6.html).
## Usage
The idea behind this SDK is to stick to the API design as much as possible, so that it feels ridiculously natural to use even while only reading the raw API documentation.
### Quickstart
To be able to use this SDK, you first need to get your secret API Key from the [Fintoc Dashboard](https://dashboard.fintoc.com/login). Once you have your API key, all you need to do is initialize a `Fintoc` object with it and you're ready to start enjoying Fintoc!
```python
from fintoc import Fintoc
client = Fintoc("your_api_key")
# list all succeeded payment intents since the beginning of 2025
payment_intents = client.payment_intents.list(since="2025-01-01", status="succeeded")
for pi in payment_intents:
print(pi.created_at, pi.amount, pi.customer_email)
# Get a specific payment intent
payment_intent = client.payment_intents.get("pi_12345235412")
print(payment_intent.customer_email)
```
### Calling endpoints
The SDK provides direct access to Fintoc API resources following the API structure. Simply use the resource name and follow it by the appropriate action you want.
Notice that **not every resource has all of the methods**, as they correspond to the API capabilities.
#### `list`
You can use the `list` method to list all the instances of the resource:
```python
webhook_endpoints = client.webhook_endpoints.list()
```
The `list` method returns **a generator** with all the instances of the resource. This method can also receive the arguments that the API receives for that specific resource. For example, the `PaymentIntent` resource can be filtered using `since` and `until`, so if you wanted to get a range of `payment intents`, all you need to do is to pass the parameters to the method:
```python
payment_intents = client.payment_intents.list(since="2025-01-01", until="2025-02-01")
```
You can also pass the `lazy=False` parameter to the method to force the SDK to return a list of all the instances of the resource instead of the generator. **Beware**: this could take **very long**, depending on the amount of instances that exist of said resource:
```python
payment_intents = client.payment_intents.list(since="2025-01-01", until="2025-02-01", lazy=False)
isinstance(payment_intents, list) # True
```
#### `get`
You can use the `get` method to get a specific instance of the resource:
```python
payment_intent = client.payment_intents.get("pi_8anqVLlBC8ROodem")
```
#### `create`
You can use the `create` method to create an instance of the resource:
```python
webhook_endpoint = client.webhook_endpoints.create(
url="https://webhook.site/58gfb429-c33c-20c7-584b-d5ew3y3202a0",
enabled_events=["link.credentials_changed"],
description="Fantasting webhook endpoint",
)
```
The `create` method of the managers creates and returns a new instance of the resource. The attributes used for creating the object are passed as `kwargs`, and correspond to the parameters specified by the API documentation for the creation of said resource.
#### `update`
You can use the `update` method to update an instance of the resource:
```python
webhook_endpoint = client.webhook_endpoints.update(
"we_8anqVLlBC8ROodem",
enabled_events=["account.refresh_intent.succeeded"],
disabled=True,
)
```
The `update` method updates and returns an existing instance of the resource using its identifier to find it. The first parameter of the method corresponds to the identifier being used to find the existing instance of the resource. The attributes to be modified are passed as `kwargs`, and correspond to the parameters specified by the API documentation for the update action of said resource.
#### `delete`
You can use the `delete` method to delete an instance of the resource:
```python
deleted_identifier = client.webhook_endpoints.delete("we_8anqVLlBC8ROodem")
```
The `delete` method deletes an existing instance of the resource using its identifier to find it and returns the identifier.
#### v2 Endpoints
To call v2 API endpoints, like the [Transfers API](https://docs.fintoc.com/reference/transfers), you need to prepend the resource name with the `v2` namespace, the same as the API does it:
```python
transfer = client.v2.transfers.create(
amount=49523,
currency="mxn",
account_id="acc_123545",
counterparty={"account_number": "014180655091438298"},
metadata={"factura": "14814"},
)
```
#### Nested actions or resources
To call nested actions just call the method as it appears in the API. For example to [simulate receiving a transfer for the Transfers](https://docs.fintoc.com/reference/receive-an-inbound-transfer) product you can do:
```python
transfer = client.v2.simulate.receive_transfer(
amount=9912400,
currency="mxn",
account_number_id="acno_2vF18OHZdXXxPJTLJ5qghpo1pdU",
)
```
### Webhook Signature Validation
To ensure the authenticity of incoming webhooks from Fintoc, you should always validate the signature. The SDK provides a `WebhookSignature` class to verify the `Fintoc-Signature` header
```python
WebhookSignature.verify_header(
payload=request.get_data().decode('utf-8'),
header=request.headers.get('Fintoc-Signature'),
secret='your_webhook_secret'
)
```
The `verify_header` method takes the following parameters:
- `payload`: The raw request body as a string
- `header`: The Fintoc-Signature header value
- `secret`: Your webhook secret key (found in your Fintoc dashboard)
- `tolerance`: (Optional) Number of seconds to tolerate when checking timestamp (default: 300)
If the signature is invalid or the timestamp is outside the tolerance window, a `WebhookSignatureError` will be raised with a descriptive message.
For a complete example of handling webhooks, see [examples/webhook.py](examples/webhook.py).
### Idempotency Keys
You can provide an [Idempotency Key](https://docs.fintoc.com/reference/idempotent-requests) using the `idempotency_key` argument. For example:
```python
transfer = client.v2.transfers.create(
idempotency_key="12345678910"
amount=49523,
currency="mxn",
account_id="acc_123545",
counterparty={"account_number": "014180655091438298"},
metadata={"factura": "14814"},
)
```
### Generate the JWS Signature
Some endpoints need a [JWS Signature](https://docs.fintoc.com/docs/setting-up-jws-keys), in addition to your API Key, to verify the integrity and authenticity of API requests. To generate the signature, initialize the Fintoc client with the `jws_private_key` argument, and the SDK will handle the rest:
```python
import os
from fintoc import Fintoc
# Provide a path to your PEM file
client = Fintoc("your_api_key", jws_private_key="private_key.pem")
# Or pass the PEM key directly as a string
client = Fintoc("your_api_key", jws_private_key=os.environ.get('JWS_PRIVATE_KEY'))
# You can now create transfers securely
```
### Serialization
Any resource of the SDK can be serialized! To get the serialized resource, just call the `serialize` method!
```python
payment_intent = client.payment_intents.list(lazy=False)[0]
serialization = payment_intent.serialize()
```
The serialization corresponds to a dictionary with only simple types, that can be JSON-serialized.
## Acknowledgements
The first version of this SDK was originally designed and handcrafted by [**@nebil**](https://github.com/nebil),
[ad](https://en.wikipedia.org/wiki/Ad_honorem) [piscolem](https://en.wiktionary.org/wiki/piscola).
He built it with the help of Gianni Roberto's [Picchi 2](https://www.youtube.com/watch?v=WqjUlmkYr2g).
Raw data
{
"_id": null,
"home_page": null,
"name": "fintoc",
"maintainer": "Daniel Leal",
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": "daniel@fintoc.com",
"keywords": null,
"author": "Daniel Leal",
"author_email": "daniel@fintoc.com",
"download_url": "https://files.pythonhosted.org/packages/52/e7/ba3aed8f96ae730e7ffab2bd817cda239ff9757a96d1d51b95443abbca30/fintoc-2.10.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">Fintoc meets Python \ud83d\udc0d</h1>\n\n<p align=\"center\">\n <em>\n You have just found the Python-flavored client of <a href=\"https://fintoc.com/\" target=\"_blank\">Fintoc</a>.\n </em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://pypi.org/project/fintoc\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/fintoc?label=version&logo=python&logoColor=%23fff&color=306998\" alt=\"PyPI - Version\">\n</a>\n\n<a href=\"https://github.com/fintoc-com/fintoc-python/actions?query=workflow%3Atests\" target=\"_blank\">\n <img src=\"https://img.shields.io/github/workflow/status/fintoc-com/fintoc-python/tests?label=tests&logo=python&logoColor=%23fff\" alt=\"Tests\">\n</a>\n\n<a href=\"https://codecov.io/gh/fintoc-com/fintoc-python\" target=\"_blank\">\n <img src=\"https://img.shields.io/codecov/c/gh/fintoc-com/fintoc-python?label=coverage&logo=codecov&logoColor=ffffff\" alt=\"Coverage\">\n</a>\n\n<a href=\"https://github.com/fintoc-com/fintoc-python/actions?query=workflow%3Alinters\" target=\"_blank\">\n <img src=\"https://img.shields.io/github/workflow/status/fintoc-com/fintoc-python/linters?label=linters&logo=github\" alt=\"Linters\">\n</a>\n</p>\n\n## Table of Contents\n- [Installation](#installation)\n- [Usage](#usage)\n - [Quickstart](#quickstart)\n - [Calling endpoints](#calling-endpoints)\n - [list](#list)\n - [get](#get)\n - [create](#create)\n - [update](#update)\n - [delete](#delete)\n - [V2 Endpoints](#v2-endpoints)\n - [Nested actions or resources](#nested-actions-or-resources)\n - [Webhook Signature Validation](#webhook-signature-validation)\n - [Idempotency Keys](#idempotency-keys)\n - [Generate the JWS Signature](#gnerate-the-jws-signature)\n - [Serialization](#serialization)\n- [Acknowledgements](#acknowledgements)\n\n## Installation\n\nInstall using pip!\n\n```sh\npip install fintoc\n```\n\n**Note:** This SDK requires [**Python 3.6+**](https://docs.python.org/3/whatsnew/3.6.html).\n\n## Usage\n\nThe idea behind this SDK is to stick to the API design as much as possible, so that it feels ridiculously natural to use even while only reading the raw API documentation.\n\n### Quickstart\n\nTo be able to use this SDK, you first need to get your secret API Key from the [Fintoc Dashboard](https://dashboard.fintoc.com/login). Once you have your API key, all you need to do is initialize a `Fintoc` object with it and you're ready to start enjoying Fintoc!\n\n```python\nfrom fintoc import Fintoc\n\nclient = Fintoc(\"your_api_key\")\n\n# list all succeeded payment intents since the beginning of 2025\npayment_intents = client.payment_intents.list(since=\"2025-01-01\", status=\"succeeded\")\nfor pi in payment_intents:\n print(pi.created_at, pi.amount, pi.customer_email)\n\n# Get a specific payment intent\npayment_intent = client.payment_intents.get(\"pi_12345235412\")\nprint(payment_intent.customer_email)\n```\n\n### Calling endpoints\n\nThe SDK provides direct access to Fintoc API resources following the API structure. Simply use the resource name and follow it by the appropriate action you want.\n\nNotice that **not every resource has all of the methods**, as they correspond to the API capabilities.\n\n#### `list`\n\nYou can use the `list` method to list all the instances of the resource:\n\n```python\nwebhook_endpoints = client.webhook_endpoints.list()\n```\n\nThe `list` method returns **a generator** with all the instances of the resource. This method can also receive the arguments that the API receives for that specific resource. For example, the `PaymentIntent` resource can be filtered using `since` and `until`, so if you wanted to get a range of `payment intents`, all you need to do is to pass the parameters to the method:\n\n```python\npayment_intents = client.payment_intents.list(since=\"2025-01-01\", until=\"2025-02-01\")\n```\n\nYou can also pass the `lazy=False` parameter to the method to force the SDK to return a list of all the instances of the resource instead of the generator. **Beware**: this could take **very long**, depending on the amount of instances that exist of said resource:\n\n```python\npayment_intents = client.payment_intents.list(since=\"2025-01-01\", until=\"2025-02-01\", lazy=False)\n\nisinstance(payment_intents, list) # True\n```\n\n#### `get`\n\nYou can use the `get` method to get a specific instance of the resource:\n\n```python\npayment_intent = client.payment_intents.get(\"pi_8anqVLlBC8ROodem\")\n```\n\n#### `create`\n\nYou can use the `create` method to create an instance of the resource:\n\n```python\nwebhook_endpoint = client.webhook_endpoints.create(\n url=\"https://webhook.site/58gfb429-c33c-20c7-584b-d5ew3y3202a0\",\n enabled_events=[\"link.credentials_changed\"],\n description=\"Fantasting webhook endpoint\",\n)\n```\n\nThe `create` method of the managers creates and returns a new instance of the resource. The attributes used for creating the object are passed as `kwargs`, and correspond to the parameters specified by the API documentation for the creation of said resource.\n\n#### `update`\n\nYou can use the `update` method to update an instance of the resource:\n\n```python\nwebhook_endpoint = client.webhook_endpoints.update(\n \"we_8anqVLlBC8ROodem\",\n enabled_events=[\"account.refresh_intent.succeeded\"],\n disabled=True,\n)\n```\n\nThe `update` method updates and returns an existing instance of the resource using its identifier to find it. The first parameter of the method corresponds to the identifier being used to find the existing instance of the resource. The attributes to be modified are passed as `kwargs`, and correspond to the parameters specified by the API documentation for the update action of said resource.\n\n#### `delete`\n\nYou can use the `delete` method to delete an instance of the resource:\n\n```python\ndeleted_identifier = client.webhook_endpoints.delete(\"we_8anqVLlBC8ROodem\")\n```\n\nThe `delete` method deletes an existing instance of the resource using its identifier to find it and returns the identifier.\n\n#### v2 Endpoints\n\nTo call v2 API endpoints, like the [Transfers API](https://docs.fintoc.com/reference/transfers), you need to prepend the resource name with the `v2` namespace, the same as the API does it:\n\n```python\ntransfer = client.v2.transfers.create(\n amount=49523,\n currency=\"mxn\",\n account_id=\"acc_123545\",\n counterparty={\"account_number\": \"014180655091438298\"},\n metadata={\"factura\": \"14814\"},\n)\n```\n\n#### Nested actions or resources\n\nTo call nested actions just call the method as it appears in the API. For example to [simulate receiving a transfer for the Transfers](https://docs.fintoc.com/reference/receive-an-inbound-transfer) product you can do:\n\n```python\ntransfer = client.v2.simulate.receive_transfer(\n amount=9912400,\n currency=\"mxn\",\n account_number_id=\"acno_2vF18OHZdXXxPJTLJ5qghpo1pdU\",\n)\n```\n\n### Webhook Signature Validation\n\nTo ensure the authenticity of incoming webhooks from Fintoc, you should always validate the signature. The SDK provides a `WebhookSignature` class to verify the `Fintoc-Signature` header\n\n```python\nWebhookSignature.verify_header(\n payload=request.get_data().decode('utf-8'),\n header=request.headers.get('Fintoc-Signature'),\n secret='your_webhook_secret'\n)\n```\n\nThe `verify_header` method takes the following parameters:\n- `payload`: The raw request body as a string\n- `header`: The Fintoc-Signature header value\n- `secret`: Your webhook secret key (found in your Fintoc dashboard)\n- `tolerance`: (Optional) Number of seconds to tolerate when checking timestamp (default: 300)\n\nIf the signature is invalid or the timestamp is outside the tolerance window, a `WebhookSignatureError` will be raised with a descriptive message.\n\nFor a complete example of handling webhooks, see [examples/webhook.py](examples/webhook.py).\n\n### Idempotency Keys\n\nYou can provide an [Idempotency Key](https://docs.fintoc.com/reference/idempotent-requests) using the `idempotency_key` argument. For example:\n\n```python\ntransfer = client.v2.transfers.create(\n idempotency_key=\"12345678910\"\n amount=49523,\n currency=\"mxn\",\n account_id=\"acc_123545\",\n counterparty={\"account_number\": \"014180655091438298\"},\n metadata={\"factura\": \"14814\"},\n)\n```\n\n### Generate the JWS Signature\n\nSome endpoints need a [JWS Signature](https://docs.fintoc.com/docs/setting-up-jws-keys), in addition to your API Key, to verify the integrity and authenticity of API requests. To generate the signature, initialize the Fintoc client with the `jws_private_key` argument, and the SDK will handle the rest:\n\n```python\nimport os\n\nfrom fintoc import Fintoc\n\n# Provide a path to your PEM file\nclient = Fintoc(\"your_api_key\", jws_private_key=\"private_key.pem\")\n\n# Or pass the PEM key directly as a string\nclient = Fintoc(\"your_api_key\", jws_private_key=os.environ.get('JWS_PRIVATE_KEY'))\n\n# You can now create transfers securely\n```\n\n\n### Serialization\n\nAny resource of the SDK can be serialized! To get the serialized resource, just call the `serialize` method!\n\n```python\npayment_intent = client.payment_intents.list(lazy=False)[0]\n\nserialization = payment_intent.serialize()\n```\n\nThe serialization corresponds to a dictionary with only simple types, that can be JSON-serialized.\n\n## Acknowledgements\n\nThe first version of this SDK was originally designed and handcrafted by [**@nebil**](https://github.com/nebil),\n[ad](https://en.wikipedia.org/wiki/Ad_honorem) [piscolem](https://en.wiktionary.org/wiki/piscola).\nHe built it with the help of Gianni Roberto's [Picchi 2](https://www.youtube.com/watch?v=WqjUlmkYr2g).\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "The official Python client for the Fintoc API.",
"version": "2.10.0",
"project_urls": {
"Homepage": "https://fintoc.com/",
"Issue Tracker": "https://github.com/fintoc-com/fintoc-python/issues",
"Repository": "https://github.com/fintoc-com/fintoc-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "57a4788ff520962b59f243f248020ef53f09110d65a715584c376e2be4f00285",
"md5": "55f28c47a6eb4d27335ced85dc7b4eb4",
"sha256": "a8f4cc9c6ec304575c2de109ddc6e2d642871b4988fb1eecc99f144a964047f8"
},
"downloads": -1,
"filename": "fintoc-2.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "55f28c47a6eb4d27335ced85dc7b4eb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 35694,
"upload_time": "2025-07-11T20:36:12",
"upload_time_iso_8601": "2025-07-11T20:36:12.216844Z",
"url": "https://files.pythonhosted.org/packages/57/a4/788ff520962b59f243f248020ef53f09110d65a715584c376e2be4f00285/fintoc-2.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "52e7ba3aed8f96ae730e7ffab2bd817cda239ff9757a96d1d51b95443abbca30",
"md5": "5f63db4db6cb2a9d3bf6e41d61cb16ff",
"sha256": "1bcd42cb75699f69d270d7b021b91bd7173bdb0ce29d02d0f233b33383963831"
},
"downloads": -1,
"filename": "fintoc-2.10.0.tar.gz",
"has_sig": false,
"md5_digest": "5f63db4db6cb2a9d3bf6e41d61cb16ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 20070,
"upload_time": "2025-07-11T20:36:13",
"upload_time_iso_8601": "2025-07-11T20:36:13.357497Z",
"url": "https://files.pythonhosted.org/packages/52/e7/ba3aed8f96ae730e7ffab2bd817cda239ff9757a96d1d51b95443abbca30/fintoc-2.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 20:36:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fintoc-com",
"github_project": "fintoc-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "fintoc"
}
