afropin 1.0.0__tar.gz

afropin-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AfroPin Software Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

afropin-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: afropin
+Version: 1.0.0
+Summary: Python library for the AfroPin gift card API: sell, top up and redeem PINs, quotes, stores and webhooks
+Author: AfroPin Software Limited
+License: MIT
+Project-URL: Homepage, https://afropin.com/developers
+Project-URL: Documentation, https://afropin.com/user/docs/introduction
+Project-URL: Source, https://github.com/afropin/afropin-python
+Keywords: afropin,gift cards,vouchers,pins,api
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AfroPin for Python
+
+The AfroPin gift card API from Python: sell, top up and redeem PINs, quotes, stores and webhooks.
+
+```
+pip install afropin
+```
+
+Python 3.8 or newer. No dependencies.
+
+## Start
+
+```python
+import os
+from afropin import Client
+
+afropin = Client(os.environ["AFROPIN_KEY_ID"], os.environ["AFROPIN_SECRET"])
+```
+
+Your API key's mode decides whether you work with test or live records; the address is the same for both. Keep the
+secret on your server, never in a browser or app.
+
+### Reseller: sell a PIN
+
+```python
+pin = afropin.reseller.pins.sell({
+    "catalog_id": catalog_id,         # from afropin.reseller.catalog.list()
+    "amount": 5000,
+    "external_reference": order_id,   # your own reference; reusing it fails safely
+    "first_name": "Ada",
+    "last_name": "Obi",
+    "email": "ada@example.com",
+})
+
+pin["pin_code"]   # the full code: returned only here, so deliver it to your customer now
+```
+
+### Brand: check and redeem a PIN
+
+```python
+check = afropin.brand.pins.check({"pin_code": code, "amount": 2500})
+if check["can_redeem"]:
+    afropin.brand.pins.redeem({"pin_code": code, "amount": 2500, "external_reference": sale_id})
+```
+
+Methods use snake_case (`top_up`, `new_code`, `wallet_links`); every call is listed in [METHODS.md](../METHODS.md).
+Parameters and response fields are the API's own, as in the developer docs.
+
+## Errors
+
+```python
+from afropin import AfroPinError
+
+try:
+    afropin.reseller.pins.top_up({"pin_id": pin_id, "amount": 1000, "external_reference": ref})
+except AfroPinError as error:
+    error.code    # for example pin_not_found, amount_too_large, duplicate_external_reference
+    error.fields  # per-field messages for input problems
+    error.status  # HTTP status, or 0 when the API wasn't reached (connection_failed)
+```
+
+Branch on `code`; the message is for people and may change.
+
+## Lists
+
+Lists return a `Page`: iterate it, and read `paging` for `page`, `pages` and `total`.
+
+```python
+page = afropin.brand.payments.list({"limit": 50})
+for payment in page:
+    ...
+if page.has_more:
+    following = afropin.brand.payments.list({"limit": 50, "page": page.paging["page"] + 1})
+```
+
+## Idempotency and retries
+
+Each request gets a new `Idempotency-Key`. To use your own: `sell(params, idempotency_key=key)`. Nothing is retried for
+you. If a sale times out, send it again with the same `external_reference`: it either goes through once, or fails with
+`duplicate_external_reference`.
+
+## Webhooks
+
+```python
+from afropin import webhooks
+
+# Flask
+event = webhooks.parse(request.get_data(), request.headers.get("webhook-secret"), WEBHOOK_SECRET)
+if event["type"] == "pin.spent":
+    ...
+```
+
+`parse` raises `invalid_signature` when the signature doesn't match. Use the raw body exactly as received.

afropin-1.0.0/README.md

@@ -0,0 +1,93 @@
+# AfroPin for Python
+
+The AfroPin gift card API from Python: sell, top up and redeem PINs, quotes, stores and webhooks.
+
+```
+pip install afropin
+```
+
+Python 3.8 or newer. No dependencies.
+
+## Start
+
+```python
+import os
+from afropin import Client
+
+afropin = Client(os.environ["AFROPIN_KEY_ID"], os.environ["AFROPIN_SECRET"])
+```
+
+Your API key's mode decides whether you work with test or live records; the address is the same for both. Keep the
+secret on your server, never in a browser or app.
+
+### Reseller: sell a PIN
+
+```python
+pin = afropin.reseller.pins.sell({
+    "catalog_id": catalog_id,         # from afropin.reseller.catalog.list()
+    "amount": 5000,
+    "external_reference": order_id,   # your own reference; reusing it fails safely
+    "first_name": "Ada",
+    "last_name": "Obi",
+    "email": "ada@example.com",
+})
+
+pin["pin_code"]   # the full code: returned only here, so deliver it to your customer now
+```
+
+### Brand: check and redeem a PIN
+
+```python
+check = afropin.brand.pins.check({"pin_code": code, "amount": 2500})
+if check["can_redeem"]:
+    afropin.brand.pins.redeem({"pin_code": code, "amount": 2500, "external_reference": sale_id})
+```
+
+Methods use snake_case (`top_up`, `new_code`, `wallet_links`); every call is listed in [METHODS.md](../METHODS.md).
+Parameters and response fields are the API's own, as in the developer docs.
+
+## Errors
+
+```python
+from afropin import AfroPinError
+
+try:
+    afropin.reseller.pins.top_up({"pin_id": pin_id, "amount": 1000, "external_reference": ref})
+except AfroPinError as error:
+    error.code    # for example pin_not_found, amount_too_large, duplicate_external_reference
+    error.fields  # per-field messages for input problems
+    error.status  # HTTP status, or 0 when the API wasn't reached (connection_failed)
+```
+
+Branch on `code`; the message is for people and may change.
+
+## Lists
+
+Lists return a `Page`: iterate it, and read `paging` for `page`, `pages` and `total`.
+
+```python
+page = afropin.brand.payments.list({"limit": 50})
+for payment in page:
+    ...
+if page.has_more:
+    following = afropin.brand.payments.list({"limit": 50, "page": page.paging["page"] + 1})
+```
+
+## Idempotency and retries
+
+Each request gets a new `Idempotency-Key`. To use your own: `sell(params, idempotency_key=key)`. Nothing is retried for
+you. If a sale times out, send it again with the same `external_reference`: it either goes through once, or fails with
+`duplicate_external_reference`.
+
+## Webhooks
+
+```python
+from afropin import webhooks
+
+# Flask
+event = webhooks.parse(request.get_data(), request.headers.get("webhook-secret"), WEBHOOK_SECRET)
+if event["type"] == "pin.spent":
+    ...
+```
+
+`parse` raises `invalid_signature` when the signature doesn't match. Use the raw body exactly as received.

afropin-1.0.0/afropin/__init__.py

@@ -0,0 +1,8 @@
+"""The AfroPin gift card API. See https://afropin.com/user/docs for every endpoint and field."""
+
+from .client import BASE_URL, VERSION, Client
+from .errors import AfroPinError
+from .page import Page
+from . import webhooks
+
+__all__ = ["Client", "AfroPinError", "Page", "webhooks", "VERSION", "BASE_URL"]

afropin-1.0.0/afropin/client.py

@@ -0,0 +1,90 @@
+"""The AfroPin API client: request signing, idempotency keys, responses and errors."""
+
+import hashlib
+import hmac
+import json
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .errors import AfroPinError
+from .page import Page
+
+VERSION = "1.0.0"
+BASE_URL = "https://afropin.com/api/v1"
+
+
+class Client:
+    """
+    Signs every request with your key (HMAC-SHA256 over "METHOD.path.timestamp.nonce.sha256(body)"), sends a fresh
+    Idempotency-Key with each one, and returns the response's data. Your key's mode (test or live) decides which records
+    you work with.
+
+        afropin = Client("key_id", "secret")
+        pin = afropin.reseller.pins.sell({"catalog_id": "...", "amount": 5000, ...})
+
+    Requests are never retried for you: a retried sale with the same external_reference fails safely with
+    duplicate_external_reference, so retry yourself with a new idempotency key when you need to.
+    """
+
+    def __init__(self, key_id, secret, base_url=BASE_URL, timeout=30, transport=None):
+        from .resources import Brand, Reseller
+
+        self._key_id = key_id
+        self._secret = secret
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        # transport(method, url, headers, body) -> (status, raw body): for tests
+        self._transport = transport
+        self.reseller = Reseller(self)
+        self.brand = Brand(self)
+
+    def request(self, method, path, params=None, idempotency_key=None, list_=False):
+        """Send one request: its data, or a Page for lists. params are the query (GET, DELETE) or the JSON body."""
+        params = params or {}
+        url = "%s/%s" % (self._base_url, path.lstrip("/"))
+        body = ""
+        if method in ("GET", "DELETE"):
+            query = {key: value for key, value in params.items() if value is not None}
+            if query:
+                url += "?" + urllib.parse.urlencode(query)
+        else:
+            body = json.dumps(params, separators=(",", ":"), ensure_ascii=False)
+
+        timestamp = str(int(time.time()))
+        nonce = str(uuid.uuid4())
+        signed_path = urllib.parse.urlparse(url).path.lstrip("/")
+        canonical = ".".join([method, signed_path, timestamp, nonce, hashlib.sha256(body.encode()).hexdigest()])
+        headers = {
+            "X-Key-Id": self._key_id,
+            "X-Timestamp": timestamp,
+            "X-Nonce": nonce,
+            "X-Signature": hmac.new(self._secret.encode(), canonical.encode(), hashlib.sha256).hexdigest(),
+            "Idempotency-Key": idempotency_key or str(uuid.uuid4()),
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": "afropin-python/%s" % VERSION,
+        }
+
+        status, raw = (self._transport or self._send)(method, url, headers, body)
+        try:
+            payload = json.loads(raw)
+        except ValueError:
+            raise AfroPinError("invalid_response", "The API sent a response that is not JSON", status=status)
+        if not payload.get("ok"):
+            error = payload.get("error") or {}
+            raise AfroPinError(error.get("code", "unknown_error"), error.get("message", "The request failed"), error.get("fields"), status)
+
+        return Page(payload.get("data") or [], payload.get("paging")) if list_ else payload.get("data")
+
+    def _send(self, method, url, headers, body):
+        request = urllib.request.Request(url, data=body.encode() if body else None, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                return response.status, response.read().decode()
+        except urllib.error.HTTPError as error:
+            return error.code, error.read().decode()
+        except (urllib.error.URLError, OSError) as error:
+            raise AfroPinError("connection_failed", "Could not reach the AfroPin API: %s" % error)

afropin-1.0.0/afropin/errors.py

@@ -0,0 +1,13 @@
+class AfroPinError(Exception):
+    """
+    A request the API refused, or one that couldn't be made. Branch on code (for example pin_balance_low or
+    duplicate_external_reference); the message is for people and may change. fields has per-field messages for input
+    problems. status is the HTTP status, or 0 when the API wasn't reached.
+    """
+
+    def __init__(self, code, message, fields=None, status=0):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.fields = fields
+        self.status = status

afropin-1.0.0/afropin/page.py

@@ -0,0 +1,19 @@
+class Page:
+    """
+    One page of a list. Iterate it for the records; paging is None when you asked for page="all". Ask for the next
+    page with {"page": page.paging["page"] + 1}.
+    """
+
+    def __init__(self, data, paging=None):
+        self.data = data
+        self.paging = paging
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __len__(self):
+        return len(self.data)
+
+    @property
+    def has_more(self):
+        return self.paging is not None and self.paging["page"] < self.paging["pages"]

afropin-1.0.0/afropin/resources.py

@@ -0,0 +1,329 @@
+# Generated from sdks/spec/endpoints.json by sdks/spec/generate.py. Don't edit by hand: change the spec and run it again.
+
+"""Every AfroPin API call, by account type and area."""
+
+
+class ResellerWallets:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Your wallets and their balances, one per currency. (GET /api/v1/reseller/wallets)"""
+        return self._client.request("GET", "reseller/wallets", params, idempotency_key, list_=True)
+
+
+class ResellerStores:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Your stores. (GET /api/v1/reseller/stores)"""
+        return self._client.request("GET", "reseller/stores", params, idempotency_key, list_=True)
+
+    def create(self, params=None, idempotency_key=None):
+        """Add a store. (POST /api/v1/reseller/stores)"""
+        return self._client.request("POST", "reseller/stores", params, idempotency_key)
+
+    def update(self, store_id, params=None, idempotency_key=None):
+        """Edit a store. (POST /api/v1/reseller/stores/{store_id})"""
+        return self._client.request("POST", "reseller/stores/%s" % (_quote(store_id),), params, idempotency_key)
+
+    def delete(self, store_id, params=None, idempotency_key=None):
+        """Remove a store. (DELETE /api/v1/reseller/stores/{store_id})"""
+        return self._client.request("DELETE", "reseller/stores/%s" % (_quote(store_id),), params, idempotency_key)
+
+
+class ResellerCards:
+    def __init__(self, client):
+        self._client = client
+
+    def lookup(self, params=None, idempotency_key=None):
+        """Look up one of your printed cards before activating it. (POST /api/v1/reseller/cards/lookup)"""
+        return self._client.request("POST", "reseller/cards/lookup", params, idempotency_key)
+
+    def activate(self, params=None, idempotency_key=None):
+        """Activate a printed card: sells a PIN for the amount loaded. (POST /api/v1/reseller/cards/activate)"""
+        return self._client.request("POST", "reseller/cards/activate", params, idempotency_key)
+
+
+class ResellerCatalog:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """The products you can sell. (GET /api/v1/reseller/catalog)"""
+        return self._client.request("GET", "reseller/catalog", params, idempotency_key, list_=True)
+
+    def get(self, catalog_id, params=None, idempotency_key=None):
+        """One product you can sell. (GET /api/v1/reseller/catalog/{catalog_id})"""
+        return self._client.request("GET", "reseller/catalog/%s" % (_quote(catalog_id),), params, idempotency_key)
+
+
+class ResellerPins:
+    def __init__(self, client):
+        self._client = client
+
+    def sell(self, params=None, idempotency_key=None):
+        """Sell a PIN. The response has its full code (pin_code), returned only here. (POST /api/v1/reseller/pins)"""
+        return self._client.request("POST", "reseller/pins", params, idempotency_key)
+
+    def get(self, pin_id, params=None, idempotency_key=None):
+        """One of your PINs: balance, status, masks, customer, family cards. (GET /api/v1/reseller/pins/{pin_id})"""
+        return self._client.request("GET", "reseller/pins/%s" % (_quote(pin_id),), params, idempotency_key)
+
+    def movements(self, pin_id, params=None, idempotency_key=None):
+        """A PIN's movements, newest first. (GET /api/v1/reseller/pins/{pin_id}/movements)"""
+        return self._client.request("GET", "reseller/pins/%s/movements" % (_quote(pin_id),), params, idempotency_key, list_=True)
+
+    def top_up(self, params=None, idempotency_key=None):
+        """Add value to a PIN. (POST /api/v1/reseller/pins/top-up)"""
+        return self._client.request("POST", "reseller/pins/top-up", params, idempotency_key)
+
+    def block(self, params=None, idempotency_key=None):
+        """Block (freeze) a PIN. Its cardholder can't undo it. (POST /api/v1/reseller/pins/block)"""
+        return self._client.request("POST", "reseller/pins/block", params, idempotency_key)
+
+    def unblock(self, params=None, idempotency_key=None):
+        """Unblock a PIN. (POST /api/v1/reseller/pins/unblock)"""
+        return self._client.request("POST", "reseller/pins/unblock", params, idempotency_key)
+
+    def new_code(self, params=None, idempotency_key=None):
+        """Give a PIN a new code; the old one stops working. (POST /api/v1/reseller/pins/new-code)"""
+        return self._client.request("POST", "reseller/pins/new-code", params, idempotency_key)
+
+    def wallet_links(self, params=None, idempotency_key=None):
+        """Links that add a PIN to Google Wallet or Apple Wallet. (POST /api/v1/reseller/pins/wallet-links)"""
+        return self._client.request("POST", "reseller/pins/wallet-links", params, idempotency_key)
+
+    def set_webhook(self, params=None, idempotency_key=None):
+        """Change a PIN's webhook. (POST /api/v1/reseller/pins/webhook)"""
+        return self._client.request("POST", "reseller/pins/webhook", params, idempotency_key)
+
+    def cashouts(self, pin_id, params=None, idempotency_key=None):
+        """A PIN's cashouts. (GET /api/v1/reseller/pins/{pin_id}/cashouts)"""
+        return self._client.request("GET", "reseller/pins/%s/cashouts" % (_quote(pin_id),), params, idempotency_key, list_=True)
+
+
+class ResellerBrandStores:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Brand stores where your customers can spend the PINs you sell. (GET /api/v1/reseller/brand-stores)"""
+        return self._client.request("GET", "reseller/brand-stores", params, idempotency_key, list_=True)
+
+
+class ResellerCashouts:
+    def __init__(self, client):
+        self._client = client
+
+    def request(self, params=None, idempotency_key=None):
+        """Request a cashout (only while cashouts are switched on). (POST /api/v1/reseller/cashouts)"""
+        return self._client.request("POST", "reseller/cashouts", params, idempotency_key)
+
+    def send_code(self, params=None, idempotency_key=None):
+        """Send the customer the confirmation code again. (POST /api/v1/reseller/cashouts/send-code)"""
+        return self._client.request("POST", "reseller/cashouts/send-code", params, idempotency_key)
+
+    def confirm(self, cashout_id, params=None, idempotency_key=None):
+        """Confirm a cashout with the customer's code. (POST /api/v1/reseller/cashouts/{cashout_id}/confirm)"""
+        return self._client.request("POST", "reseller/cashouts/%s/confirm" % (_quote(cashout_id),), params, idempotency_key)
+
+    def void(self, cashout_id, params=None, idempotency_key=None):
+        """Void an unpaid cashout. (POST /api/v1/reseller/cashouts/{cashout_id}/void)"""
+        return self._client.request("POST", "reseller/cashouts/%s/void" % (_quote(cashout_id),), params, idempotency_key)
+
+
+class Reseller:
+    """The reseller API (/api/v1/reseller): every call a reseller account can make, by area."""
+
+    def __init__(self, client):
+        self.wallets = ResellerWallets(client)
+        self.stores = ResellerStores(client)
+        self.cards = ResellerCards(client)
+        self.catalog = ResellerCatalog(client)
+        self.pins = ResellerPins(client)
+        self.brand_stores = ResellerBrandStores(client)
+        self.cashouts = ResellerCashouts(client)
+
+
+class BrandWallets:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Your wallets and their balances, one per currency. (GET /api/v1/brand/wallets)"""
+        return self._client.request("GET", "brand/wallets", params, idempotency_key, list_=True)
+
+
+class BrandStores:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Your stores. (GET /api/v1/brand/stores)"""
+        return self._client.request("GET", "brand/stores", params, idempotency_key, list_=True)
+
+    def create(self, params=None, idempotency_key=None):
+        """Add a store. (POST /api/v1/brand/stores)"""
+        return self._client.request("POST", "brand/stores", params, idempotency_key)
+
+    def update(self, store_id, params=None, idempotency_key=None):
+        """Edit a store. (POST /api/v1/brand/stores/{store_id})"""
+        return self._client.request("POST", "brand/stores/%s" % (_quote(store_id),), params, idempotency_key)
+
+    def delete(self, store_id, params=None, idempotency_key=None):
+        """Remove a store. (DELETE /api/v1/brand/stores/{store_id})"""
+        return self._client.request("DELETE", "brand/stores/%s" % (_quote(store_id),), params, idempotency_key)
+
+
+class BrandCards:
+    def __init__(self, client):
+        self._client = client
+
+    def lookup(self, params=None, idempotency_key=None):
+        """Look up one of your printed cards before activating it. (POST /api/v1/brand/cards/lookup)"""
+        return self._client.request("POST", "brand/cards/lookup", params, idempotency_key)
+
+    def activate(self, params=None, idempotency_key=None):
+        """Activate a printed card: sells a PIN for the amount loaded. (POST /api/v1/brand/cards/activate)"""
+        return self._client.request("POST", "brand/cards/activate", params, idempotency_key)
+
+
+class BrandIssuingCatalog:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """The products you can sell. (GET /api/v1/brand/issuing-catalog)"""
+        return self._client.request("GET", "brand/issuing-catalog", params, idempotency_key, list_=True)
+
+    def get(self, catalog_id, params=None, idempotency_key=None):
+        """One product you can sell. (GET /api/v1/brand/issuing-catalog/{catalog_id})"""
+        return self._client.request("GET", "brand/issuing-catalog/%s" % (_quote(catalog_id),), params, idempotency_key)
+
+
+class BrandPins:
+    def __init__(self, client):
+        self._client = client
+
+    def sell(self, params=None, idempotency_key=None):
+        """Sell a PIN. The response has its full code (pin_code), returned only here. (POST /api/v1/brand/pins)"""
+        return self._client.request("POST", "brand/pins", params, idempotency_key)
+
+    def get(self, pin_id, params=None, idempotency_key=None):
+        """One of your PINs: balance, status, masks, customer, family cards. (GET /api/v1/brand/pins/{pin_id})"""
+        return self._client.request("GET", "brand/pins/%s" % (_quote(pin_id),), params, idempotency_key)
+
+    def movements(self, pin_id, params=None, idempotency_key=None):
+        """A PIN's movements, newest first. (GET /api/v1/brand/pins/{pin_id}/movements)"""
+        return self._client.request("GET", "brand/pins/%s/movements" % (_quote(pin_id),), params, idempotency_key, list_=True)
+
+    def top_up(self, params=None, idempotency_key=None):
+        """Add value to a PIN. (POST /api/v1/brand/pins/top-up)"""
+        return self._client.request("POST", "brand/pins/top-up", params, idempotency_key)
+
+    def block(self, params=None, idempotency_key=None):
+        """Block (freeze) a PIN. Its cardholder can't undo it. (POST /api/v1/brand/pins/block)"""
+        return self._client.request("POST", "brand/pins/block", params, idempotency_key)
+
+    def unblock(self, params=None, idempotency_key=None):
+        """Unblock a PIN. (POST /api/v1/brand/pins/unblock)"""
+        return self._client.request("POST", "brand/pins/unblock", params, idempotency_key)
+
+    def new_code(self, params=None, idempotency_key=None):
+        """Give a PIN a new code; the old one stops working. (POST /api/v1/brand/pins/new-code)"""
+        return self._client.request("POST", "brand/pins/new-code", params, idempotency_key)
+
+    def wallet_links(self, params=None, idempotency_key=None):
+        """Links that add a PIN to Google Wallet or Apple Wallet. (POST /api/v1/brand/pins/wallet-links)"""
+        return self._client.request("POST", "brand/pins/wallet-links", params, idempotency_key)
+
+    def set_webhook(self, params=None, idempotency_key=None):
+        """Change a PIN's webhook. (POST /api/v1/brand/pins/webhook)"""
+        return self._client.request("POST", "brand/pins/webhook", params, idempotency_key)
+
+    def check(self, params=None, idempotency_key=None):
+        """Check a PIN before redeeming it; nothing changes. (POST /api/v1/brand/pins/check)"""
+        return self._client.request("POST", "brand/pins/check", params, idempotency_key)
+
+    def redeem(self, params=None, idempotency_key=None):
+        """Redeem a PIN: take an amount off it and credit your wallet. (POST /api/v1/brand/pins/redeem)"""
+        return self._client.request("POST", "brand/pins/redeem", params, idempotency_key)
+
+
+class BrandCatalog:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """The products you accept. (GET /api/v1/brand/catalog)"""
+        return self._client.request("GET", "brand/catalog", params, idempotency_key, list_=True)
+
+    def get(self, catalog_id, params=None, idempotency_key=None):
+        """One product you accept. (GET /api/v1/brand/catalog/{catalog_id})"""
+        return self._client.request("GET", "brand/catalog/%s" % (_quote(catalog_id),), params, idempotency_key)
+
+
+class BrandResellerStores:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Reseller stores that sell PINs you accept. (GET /api/v1/brand/reseller-stores)"""
+        return self._client.request("GET", "brand/reseller-stores", params, idempotency_key, list_=True)
+
+
+class BrandPayments:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """The redemptions credited to you, newest first. (GET /api/v1/brand/payments)"""
+        return self._client.request("GET", "brand/payments", params, idempotency_key, list_=True)
+
+    def get(self, transaction_ref, params=None, idempotency_key=None):
+        """One redemption. (GET /api/v1/brand/payments/{transaction_ref})"""
+        return self._client.request("GET", "brand/payments/%s" % (_quote(transaction_ref),), params, idempotency_key)
+
+
+class BrandQuotes:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, params=None, idempotency_key=None):
+        """Your quotes, newest first. (GET /api/v1/brand/quotes)"""
+        return self._client.request("GET", "brand/quotes", params, idempotency_key, list_=True)
+
+    def create(self, params=None, idempotency_key=None):
+        """Quote a business for your gift cards in bulk; returns a pay_url. (POST /api/v1/brand/quotes)"""
+        return self._client.request("POST", "brand/quotes", params, idempotency_key)
+
+    def get(self, quote_id, params=None, idempotency_key=None):
+        """One quote, by id or QTE- reference. (GET /api/v1/brand/quotes/{quote_id})"""
+        return self._client.request("GET", "brand/quotes/%s" % (_quote(quote_id),), params, idempotency_key)
+
+    def cancel(self, quote_id, params=None, idempotency_key=None):
+        """Withdraw an unpaid quote. (POST /api/v1/brand/quotes/{quote_id}/cancel)"""
+        return self._client.request("POST", "brand/quotes/%s/cancel" % (_quote(quote_id),), params, idempotency_key)
+
+
+class Brand:
+    """The brand API (/api/v1/brand): every call a brand account can make, by area."""
+
+    def __init__(self, client):
+        self.wallets = BrandWallets(client)
+        self.stores = BrandStores(client)
+        self.cards = BrandCards(client)
+        self.issuing_catalog = BrandIssuingCatalog(client)
+        self.pins = BrandPins(client)
+        self.catalog = BrandCatalog(client)
+        self.reseller_stores = BrandResellerStores(client)
+        self.payments = BrandPayments(client)
+        self.quotes = BrandQuotes(client)
+
+
+def _quote(value):
+    from urllib.parse import quote
+
+    return quote(str(value), safe="")

afropin-1.0.0/afropin/webhooks.py

@@ -0,0 +1,29 @@
+"""
+Checking a webhook AfroPin sent you. Each one is signed with the webhook's secret: the webhook-secret header holds the
+HMAC-SHA256 of the raw body. Check it against the body exactly as received (request.get_data() in Flask, request.body in
+Django), before parsing it.
+"""
+
+import hashlib
+import hmac
+import json
+
+from .errors import AfroPinError
+
+
+def verify(raw_body, signature, secret):
+    if not signature:
+        return False
+    body = raw_body if isinstance(raw_body, bytes) else raw_body.encode()
+    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+
+def parse(raw_body, signature, secret):
+    """The event, {"type": "pin.sold", "data": {...}}, once its signature checks out."""
+    if not verify(raw_body, signature, secret):
+        raise AfroPinError("invalid_signature", "The webhook signature does not match its body")
+    event = json.loads(raw_body)
+    if not isinstance(event, dict) or "type" not in event:
+        raise AfroPinError("invalid_response", "The webhook body is not an AfroPin event")
+    return event

afropin-1.0.0/afropin.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: afropin
+Version: 1.0.0
+Summary: Python library for the AfroPin gift card API: sell, top up and redeem PINs, quotes, stores and webhooks
+Author: AfroPin Software Limited
+License: MIT
+Project-URL: Homepage, https://afropin.com/developers
+Project-URL: Documentation, https://afropin.com/user/docs/introduction
+Project-URL: Source, https://github.com/afropin/afropin-python
+Keywords: afropin,gift cards,vouchers,pins,api
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AfroPin for Python
+
+The AfroPin gift card API from Python: sell, top up and redeem PINs, quotes, stores and webhooks.
+
+```
+pip install afropin
+```
+
+Python 3.8 or newer. No dependencies.
+
+## Start
+
+```python
+import os
+from afropin import Client
+
+afropin = Client(os.environ["AFROPIN_KEY_ID"], os.environ["AFROPIN_SECRET"])
+```
+
+Your API key's mode decides whether you work with test or live records; the address is the same for both. Keep the
+secret on your server, never in a browser or app.
+
+### Reseller: sell a PIN
+
+```python
+pin = afropin.reseller.pins.sell({
+    "catalog_id": catalog_id,         # from afropin.reseller.catalog.list()
+    "amount": 5000,
+    "external_reference": order_id,   # your own reference; reusing it fails safely
+    "first_name": "Ada",
+    "last_name": "Obi",
+    "email": "ada@example.com",
+})
+
+pin["pin_code"]   # the full code: returned only here, so deliver it to your customer now
+```
+
+### Brand: check and redeem a PIN
+
+```python
+check = afropin.brand.pins.check({"pin_code": code, "amount": 2500})
+if check["can_redeem"]:
+    afropin.brand.pins.redeem({"pin_code": code, "amount": 2500, "external_reference": sale_id})
+```
+
+Methods use snake_case (`top_up`, `new_code`, `wallet_links`); every call is listed in [METHODS.md](../METHODS.md).
+Parameters and response fields are the API's own, as in the developer docs.
+
+## Errors
+
+```python
+from afropin import AfroPinError
+
+try:
+    afropin.reseller.pins.top_up({"pin_id": pin_id, "amount": 1000, "external_reference": ref})
+except AfroPinError as error:
+    error.code    # for example pin_not_found, amount_too_large, duplicate_external_reference
+    error.fields  # per-field messages for input problems
+    error.status  # HTTP status, or 0 when the API wasn't reached (connection_failed)
+```
+
+Branch on `code`; the message is for people and may change.
+
+## Lists
+
+Lists return a `Page`: iterate it, and read `paging` for `page`, `pages` and `total`.
+
+```python
+page = afropin.brand.payments.list({"limit": 50})
+for payment in page:
+    ...
+if page.has_more:
+    following = afropin.brand.payments.list({"limit": 50, "page": page.paging["page"] + 1})
+```
+
+## Idempotency and retries
+
+Each request gets a new `Idempotency-Key`. To use your own: `sell(params, idempotency_key=key)`. Nothing is retried for
+you. If a sale times out, send it again with the same `external_reference`: it either goes through once, or fails with
+`duplicate_external_reference`.
+
+## Webhooks
+
+```python
+from afropin import webhooks
+
+# Flask
+event = webhooks.parse(request.get_data(), request.headers.get("webhook-secret"), WEBHOOK_SECRET)
+if event["type"] == "pin.spent":
+    ...
+```
+
+`parse` raises `invalid_signature` when the signature doesn't match. Use the raw body exactly as received.

afropin-1.0.0/afropin.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+afropin/__init__.py
+afropin/client.py
+afropin/errors.py
+afropin/page.py
+afropin/resources.py
+afropin/webhooks.py
+afropin.egg-info/PKG-INFO
+afropin.egg-info/SOURCES.txt
+afropin.egg-info/dependency_links.txt
+afropin.egg-info/top_level.txt
+tests/test_sdk.py

afropin-1.0.0/afropin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

afropin-1.0.0/afropin.egg-info/top_level.txt

@@ -0,0 +1 @@
+afropin

afropin-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "afropin"
+version = "1.0.0"
+description = "Python library for the AfroPin gift card API: sell, top up and redeem PINs, quotes, stores and webhooks"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = []
+authors = [{ name = "AfroPin Software Limited" }]
+keywords = ["afropin", "gift cards", "vouchers", "pins", "api"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://afropin.com/developers"
+Documentation = "https://afropin.com/user/docs/introduction"
+Source = "https://github.com/afropin/afropin-python"
+
+[tool.setuptools]
+packages = ["afropin"]

afropin-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

afropin-1.0.0/tests/test_sdk.py

@@ -0,0 +1,70 @@
+"""
+The Python SDK's checks: signing and webhooks offline, then (with AFROPIN_TEST_ENV pointing at a JSON file of test keys,
+base_url, catalog_id and test_pin) a real round trip against an AfroPin API in test mode.
+    python3 -m unittest discover -s tests
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from afropin import AfroPinError, Client, Page, webhooks  # noqa: E402
+
+
+class Offline(unittest.TestCase):
+    def test_signs_requests_and_returns_data(self):
+        sent = {}
+
+        def transport(method, url, headers, body):
+            sent.update(method=method, url=url, headers=headers, body=body)
+            return 200, '{"ok":true,"data":{"pin_id":"p1"}}'
+
+        client = Client("key_1", "secret_1", base_url="https://example.test/api/v1", transport=transport)
+        data = client.reseller.pins.top_up({"pin_id": "p1", "amount": 500}, idempotency_key="idem-1")
+        h = sent["headers"]
+        canonical = ".".join(["POST", "api/v1/reseller/pins/top-up", h["X-Timestamp"], h["X-Nonce"], hashlib.sha256(sent["body"].encode()).hexdigest()])
+        self.assertEqual(h["X-Signature"], hmac.new(b"secret_1", canonical.encode(), hashlib.sha256).hexdigest())
+        self.assertEqual(h["Idempotency-Key"], "idem-1")
+        self.assertEqual(data, {"pin_id": "p1"})
+        client.reseller.pins.get("a/b")
+        self.assertTrue(sent["url"].endswith("/reseller/pins/a%2Fb"))
+        self.assertEqual(sent["body"], "")
+
+    def test_verifies_webhooks(self):
+        body = '{"type":"pin.sold","data":{"pin_id":"p1"}}'
+        self.assertTrue(webhooks.verify(body, hmac.new(b"whsec", body.encode(), hashlib.sha256).hexdigest(), "whsec"))
+        self.assertFalse(webhooks.verify(body, hmac.new(b"other", body.encode(), hashlib.sha256).hexdigest(), "whsec"))
+
+
+@unittest.skipUnless(os.environ.get("AFROPIN_TEST_ENV"), "set AFROPIN_TEST_ENV to run against an API")
+class Live(unittest.TestCase):
+    def test_round_trip_in_test_mode(self):
+        env = json.load(open(os.environ["AFROPIN_TEST_ENV"]))
+        reseller = Client(env["reseller"]["key_id"], env["reseller"]["secret"], base_url=env["base_url"])
+        brand = Client(env["brand"]["key_id"], env["brand"]["secret"], base_url=env["base_url"])
+
+        self.assertTrue(len(reseller.reseller.wallets.list()) > 0)
+        catalog = reseller.reseller.catalog.list({"limit": 5})
+        self.assertIsInstance(catalog, Page)
+        self.assertTrue(len(catalog) > 0 and catalog.paging["total"] > 0)
+        product = reseller.reseller.catalog.get(env["catalog_id"])
+        amount = float((product.get("denominations") or [product["min"]])[0])
+        sold = reseller.reseller.pins.sell({
+            "catalog_id": env["catalog_id"], "amount": amount, "external_reference": "sdk-py-" + secrets.token_hex(6),
+            "first_name": "Sdk", "last_name": "Test", "email": "sdk.test@gmail.com",
+        })
+        self.assertTrue(sold["pin_code"] and sold["pin_id"])
+        self.assertEqual(float(reseller.reseller.pins.get(sold["pin_id"])["balance"]), amount)
+        with self.assertRaises(AfroPinError) as caught:
+            reseller.reseller.pins.get("00000000-0000-4000-8000-000000000000")
+        self.assertEqual((caught.exception.code, caught.exception.status), ("pin_not_found", 404))
+        self.assertIn("can_redeem", brand.brand.pins.check({"pin_code": env["test_pin"]}))
+
+
+if __name__ == "__main__":
+    unittest.main()