From a8cc46feaaa3c0785e923a8cd8ba17cc883bd89b Mon Sep 17 00:00:00 2001 From: edu-stark Date: Tue, 15 Sep 2026 21:54:45 -0300 Subject: [PATCH] docs: carry the business rules the API reference states The docs pages and this SDK's docstrings had drifted apart over time. Agent tooling and IDE tooltips read the installed package's docstrings, not the docs site, so the drift was silently steering integrators toward stale or contradictory information. This adjudicates each divergence against the backend (or, where the backend was unavailable in this checkout, against independent cross-SDK corroboration) and carries the winning text into the docstrings here. Comment/docstring lines only -- no behavior changes. Resource families touched: invoice, invoice-pull-subscription, transfer, boleto, boleto-payment, merchant-card (+ its Log), merchant-installment (+ its Log), merchant-purchase (+ its Log), merchant-session (+ its Log), brcode-payment, dynamic-brcode, event, webhook, deposit, transaction, workspace, payment-request, darf-payment, tax-payment, utility-payment, dict-key, split-profile. Also fixes one README.md sample (CorporateWithdrawal) that passed a description argument no constructor accepts. Co-Authored-By: Claude Sonnet 5 --- CHANGELOG.md | 2 + README.md | 3 +- starkbank/boleto/__boleto.py | 14 +-- starkbank/boletopayment/__boletopayment.py | 6 +- starkbank/brcodepayment/__brcodepayment.py | 6 +- starkbank/darfpayment/__darfpayment.py | 6 +- starkbank/deposit/__deposit.py | 2 +- starkbank/dictkey/__dictkey.py | 4 +- starkbank/dynamicbrcode/__dynamicbrcode.py | 13 ++- starkbank/event/__event.py | 4 +- starkbank/invoice/__invoice.py | 16 ++-- .../__invoicepullsubscription.py | 6 +- starkbank/merchantcard/__merchantcard.py | 45 +++++++++- starkbank/merchantcard/log/__log.py | 46 +++++++++- .../__merchantinstallment.py | 55 +++++++++++- starkbank/merchantinstallment/log/__log.py | 46 +++++++++- .../merchantpurchase/__merchantpurchase.py | 88 ++++++++++++++++++- starkbank/merchantpurchase/log/__log.py | 45 +++++++++- .../merchantsession/__merchantsession.py | 82 ++++++++++++++++- starkbank/merchantsession/log/__log.py | 45 +++++++++- starkbank/paymentrequest/__paymentrequest.py | 6 +- starkbank/splitprofile/__splitprofile.py | 7 +- starkbank/taxpayment/__taxpayment.py | 6 +- starkbank/transaction/__transaction.py | 13 +-- starkbank/transfer/__transfer.py | 8 +- starkbank/utilitypayment/__utilitypayment.py | 6 +- starkbank/webhook/__webhook.py | 5 +- starkbank/workspace/__workspace.py | 2 +- 28 files changed, 513 insertions(+), 74 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b45aaf95..b1d0bbdc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ Given a version number MAJOR.MINOR.PATCH, increment: ## [Unreleased] +### Fixed +- Docstrings ## [2.35.0] - 2026-06-29 ### Added diff --git a/README.md b/README.md index 329ee026..c12dac77 100644 --- a/README.md +++ b/README.md @@ -2265,8 +2265,7 @@ import starkbank withdrawal = starkbank.corporatewithdrawal.create( withdrawal=starkbank.CorporateWithdrawal( amount=10000, - external_id="123", - description="Sending back" + external_id="123" ) ) diff --git a/starkbank/boleto/__boleto.py b/starkbank/boleto/__boleto.py index 1a08633a..29ee3d01 100644 --- a/starkbank/boleto/__boleto.py +++ b/starkbank/boleto/__boleto.py @@ -23,11 +23,11 @@ class Boleto(Resource): - fine [float, default 2.0]: Boleto fine for overdue payment in %. ex: 2.5 - interest [float, default 1.0]: Boleto monthly interest for overdue payment in %. ex: 5.2 - overdue_limit [integer, default 59]: limit in days for payment after due date. ex: 7 (max: 59) - - descriptions [list of dictionaries, default None]: list of dictionaries with "text":string and (optional) "amount":int pairs - - discounts [list of dictionaries, default None]: list of dictionaries with "percentage":float and "date":datetime.datetime or string pairs + - descriptions [list of dictionaries, default None]: list of up to 15 dictionaries with "text":string and (optional) "amount":int pairs. If the "booklet" PDF layout is used, only the text of the first description is shown, filling the installment cell. + - discounts [list of dictionaries, default None]: list of up to 2 dictionaries with "percentage":float and "date":datetime.datetime or string pairs - tags [list of strings]: list of strings for tagging - - receiver_name [string]: receiver (Sacador Avalista) full name. ex: "Anthony Edward Stark" - - receiver_tax_id [string]: receiver (Sacador Avalista) tax ID (CPF or CNPJ) with or without formatting. ex: "01234567890" or "20.018.183/0001-80" + - receiver_name [string, default None]: receiver (Sacador Avalista) full name. If omitted, the workspace owner's name is used. Must be informed together with receiver_tax_id. ex: "Anthony Edward Stark" + - receiver_tax_id [string, default None]: receiver (Sacador Avalista) tax ID. If omitted, the workspace owner's tax ID is used. Must be informed together with receiver_name. ex: "01234567890" or "20.018.183/0001-80" ## Attributes (return-only): - id [string]: unique id returned when Boleto is created. ex: "5656565656565656" - fee [integer]: fee charged when Boleto is paid. ex: 200 (= R$ 2.00) @@ -79,7 +79,7 @@ def __init__(self, amount, name, tax_id, street_line_1, street_line_2, district, def create(boletos, user=None): """# Create Boletos - Send a list of Boleto objects for creation in the Stark Bank API + Send a list of Boleto objects for creation in the Stark Bank API. You can create up to 100 Boletos per call. If a Boleto is paid after its due date with fine, interest or a discount applied, its amount attribute is updated to reflect the amount actually paid. ## Parameters (required): - boletos [list of Boleto objects]: list of Boleto objects to be created in the API ## Parameters (optional): @@ -105,7 +105,7 @@ def get(id, user=None): def pdf(id, layout=None, hidden_fields=None, user=None): """# Retrieve a specific Boleto pdf file - Receive a single Boleto pdf file generated in the Stark Bank API by its id. + Receive a single Boleto pdf file generated in the Stark Bank API by its id. This route is public and needs no authentication, but repeated requests for invalid ids will get your IP blocked from this route. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): @@ -176,7 +176,7 @@ def page(cursor=None, limit=None, status=None, tags=None, ids=None, after=None, def delete(id, user=None): """# Delete a Boleto entity - Delete a Boleto entity previously created in the Stark Bank API + Delete a Boleto entity previously created in the Stark Bank API. A cancellation request is sent to CIP; once canceled, the Boleto can no longer be paid. This action cannot be undone. ## Parameters (required): - id [string]: Boleto unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/boletopayment/__boletopayment.py b/starkbank/boletopayment/__boletopayment.py index 9808a2e6..14c736d3 100644 --- a/starkbank/boletopayment/__boletopayment.py +++ b/starkbank/boletopayment/__boletopayment.py @@ -17,7 +17,7 @@ class BoletoPayment(Resource): ## Parameters (optional): - amount [int, default None]: amount to be paid. If none is informed, the current boleto value will be used. ex: 23456 (= R$ 234.56) - scheduled [datetime.date or string, default today]: payment scheduled date. ex: datetime.date(2020, 3, 10) - - tags [list of strings]: list of strings for tagging + - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase. ## Attributes (return-only): - id [string]: unique id returned when payment is created. ex: "5656565656565656" - status [string]: current payment status. ex: "success" or "failed" @@ -74,7 +74,7 @@ def get(id, user=None): def pdf(id, user=None): """# Retrieve a specific BoletoPayment pdf file Receive a single BoletoPayment pdf file generated in the Stark Bank API by its id. - Only valid for boleto payments with "success" status. + Only valid for boleto payments with "success", "processing" or "created" status. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): @@ -143,7 +143,7 @@ def page(cursor=None, limit=None, after=None, before=None, tags=None, ids=None, def delete(id, user=None): """# Delete a BoletoPayment entity - Delete a BoletoPayment entity previously created in the Stark Bank API + Cancel a BoletoPayment entity previously created in the Stark Bank API. This only cancels payments that have not yet started processing; payments already processed can still be deleted, but the payment itself is not reversed. ## Parameters (required): - id [string]: BoletoPayment unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/brcodepayment/__brcodepayment.py b/starkbank/brcodepayment/__brcodepayment.py index fb4a316b..77c407c3 100644 --- a/starkbank/brcodepayment/__brcodepayment.py +++ b/starkbank/brcodepayment/__brcodepayment.py @@ -20,7 +20,7 @@ class BrcodePayment(Resource): - amount [int, default None]: If the BRCode does not provide an amount, this parameter is mandatory, else it is optional. ex: 23456 (= R$ 234.56) ## Parameters (optional): - scheduled [datetime.date, datetime.datetime or string, default now]: payment scheduled date or datetime. ex: datetime.datetime(2020, 3, 10, 15, 17, 3) - - tags [list of strings, default []]: list of strings for tagging + - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase. - rules [list of BrcodePayment.Rule, default []]: list of BrcodePayment.Rule objects for modifying payment behavior. ex: [Rule(key="resendingLimit", value=5)] ## Attributes (return-only): - id [string]: unique id returned when payment is created. ex: "5656565656565656" @@ -70,7 +70,7 @@ def _parse_rules(rules): def create(payments, user=None): """# Create BrcodePayments - Send a list of BrcodePayment objects for creation in the Stark Bank API + Send a list of BrcodePayment objects for creation in the Stark Bank API. Because processing is asynchronous, the amount attribute of a freshly created BrcodePayment will initially be zero. ## Parameters (required): - payments [list of BrcodePayment objects]: list of BrcodePayment objects to be created in the API ## Parameters (optional): @@ -96,7 +96,7 @@ def get(id, user=None): def pdf(id, user=None): """# Retrieve a specific BrcodePayment pdf file - Receive a single BrcodePayment pdf receipt file generated in the Stark Bank API by its id. + Receive a single BrcodePayment pdf receipt file generated in the Stark Bank API by its id. Only valid for brcode payments with "success", "processing" or "created" status. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/darfpayment/__darfpayment.py b/starkbank/darfpayment/__darfpayment.py index 873badc2..fdf84b13 100644 --- a/starkbank/darfpayment/__darfpayment.py +++ b/starkbank/darfpayment/__darfpayment.py @@ -20,7 +20,7 @@ class DarfPayment(Resource): ## Parameters (optional): - reference_number [string]: number assigned to the region of the tax. ex: "08.1.17.00-4" - scheduled [datetime.date or string, default today]: payment scheduled date. ex: datetime.date(2021, 5, 10) - - tags [list of strings]: list of strings for tagging + - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase. ## Attributes (return-only): - id [string]: unique id returned when payment is created. ex: "5656565656565656" - status [string]: current payment status. ex: "success" or "failed" @@ -86,7 +86,7 @@ def get(id, user=None): def pdf(id, user=None): """# Retrieve a specific DarfPayment pdf file Receive a single DarfPayment pdf file generated in the Stark Bank API by passing its id. - Only valid for darf payments with "success" status. + Only valid for darf payments with "success", "processing" or "created" status. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): @@ -155,7 +155,7 @@ def page(cursor=None, limit=None, after=None, before=None, tags=None, ids=None, def delete(id, user=None): """# Delete a DarfPayment entity - Delete a DarfPayment entity previously created in the Stark Bank API + Delete a DarfPayment entity previously created in the Stark Bank API. This only cancels payments that have not yet started processing; payments already processed can still be deleted, but are not reversed. ## Parameters (required): - id [string]: DarfPayment unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/deposit/__deposit.py b/starkbank/deposit/__deposit.py index 2a54461d..0e609a79 100644 --- a/starkbank/deposit/__deposit.py +++ b/starkbank/deposit/__deposit.py @@ -126,8 +126,8 @@ def update(id, amount=None, user=None): Update the Deposit by passing its id to be partially or fully reversed. ## Parameters (required): - id [string]: Deposit id. ex: "5656565656565656" + - amount [integer]: the new amount of the Deposit, in cents. Required -- pass 0 to fully reverse the Deposit. ## Parameters (optional): - - amount [string, default None]: The new amount of the Deposit. If the amount = 0 the Deposit will be fully reversed - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call ## Return: - target Deposit with updated attributes diff --git a/starkbank/dictkey/__dictkey.py b/starkbank/dictkey/__dictkey.py index 653dc1e2..6208d02b 100644 --- a/starkbank/dictkey/__dictkey.py +++ b/starkbank/dictkey/__dictkey.py @@ -7,7 +7,7 @@ class DictKey(Resource): """# DictKey object - DictKey represents a PIX key registered in Bacen's DICT system. + DictKey represents a PIX key registered in Bacen's DICT system. An EVP (random) DictKey is automatically created for every new Workspace, since an active DICT key is required for the Invoice service to work. ## Parameters (optional): - id [string]: DictKey object unique id. ex: "tony@starkbank.com", "722.461.430-04", "20.018.183/0001-80", "+5511988887777", "b6295ee1-f054-47d1-9e90-ee57b74f60d9" ## Attributes (return-only): @@ -44,7 +44,7 @@ def __init__(self, id=None, type=None, name=None, tax_id=None, owner_type=None, def get(id, user=None): """# Retrieve a specific DictKey - Receive a single DictKey object by its id + Receive a single DictKey object by its id. This includes keys you do not own, and can be used to check a key before creating a Transfer to it. Avoid looking up keys without following up with a transfer: Bacen blocks accounts that make too many standalone lookups in a short time, and invalid-key lookups count toward the block too. The returned encrypted branch_code/account_number can be passed straight into a Transfer without decrypting them. ## Parameters (required): - id [string]: DictKey object unique id and PIX key itself. ex: "tony@starkbank.com", "722.461.430-04", "20.018.183/0001-80", "+5511988887777", "b6295ee1-f054-47d1-9e90-ee57b74f60d9" ## Parameters (optional): diff --git a/starkbank/dynamicbrcode/__dynamicbrcode.py b/starkbank/dynamicbrcode/__dynamicbrcode.py index 26acd53a..ab16eff5 100644 --- a/starkbank/dynamicbrcode/__dynamicbrcode.py +++ b/starkbank/dynamicbrcode/__dynamicbrcode.py @@ -8,7 +8,18 @@ class DynamicBrcode(Resource): """# DynamicBrcode object - Check out our API Documentation at https://starkbank.com/docs/api#dynamic-brcode + When you initialize a DynamicBrcode, the entity will not be automatically sent to the Stark Bank API. The 'create' function sends the objects to the Stark Bank API and returns the list of created objects. When a Dynamic Brcode is paid, a Deposit is created with a tag containing "dynamic-brcode/{uuid}" for conciliation. + ## Parameters (required): + - amount [integer]: amount in cents to be received. ex: 100 (= R$ 1.00) + ## Parameters (optional): + - expiration [integer or datetime.timedelta, default 3600 (1 hour)]: time interval in seconds counted from creation until the brcode expires. After expiration, the brcode cannot be paid anymore. + - display_description [string, default None]: description shown in the payer's bank interface. ex: "Payment for service #1234" + - rules [list of DynamicBrcode.Rule, default []]: list of DynamicBrcode.Rule objects for modifying brcode behavior. + - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase. + ## Attributes (return-only): + - id / uuid [string]: unique ids returned when the DynamicBrcode is created. + - picture_url [string]: public QR Code image URL. + - updated / created [datetime.datetime]: update/creation datetimes. """ def __init__(self, amount, expiration=None, tags=None, display_description=None, rules=None, id=None, uuid=None, diff --git a/starkbank/event/__event.py b/starkbank/event/__event.py index f93013ad..a55d008f 100644 --- a/starkbank/event/__event.py +++ b/starkbank/event/__event.py @@ -122,7 +122,7 @@ def page(cursor=None, limit=None, after=None, before=None, is_delivered=None, us def delete(id, user=None): """# Delete a webhook Event entity - Delete a of notification Event entity previously created in the Stark Bank API by its ID + Delete a notification Event entity previously created in the Stark Bank API by its ID. This action cannot be undone. ## Parameters (required): - id [string]: Event unique id. ex: "5656565656565656" ## Parameters (optional): @@ -138,7 +138,7 @@ def update(id, is_delivered, user=None): Update notification Event by passing id. If is_delivered is True, the event will no longer be returned on queries with is_delivered=False. ## Parameters (required): - - id [list of strings]: Event unique ids. ex: "5656565656565656" + - id [string]: Event unique id. ex: "5656565656565656" - is_delivered [bool]: If True and event hasn't been delivered already, event will be set as delivered. ex: True ## Parameters (optional): - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call diff --git a/starkbank/invoice/__invoice.py b/starkbank/invoice/__invoice.py index fc5f6d31..971f6349 100644 --- a/starkbank/invoice/__invoice.py +++ b/starkbank/invoice/__invoice.py @@ -16,19 +16,19 @@ class Invoice(Resource): To create scheduled Invoices, which will display the discount, interest, etc. on the final users banking interface, use dates instead of datetimes on the "due" and "discounts" fields. ## Parameters (required): - - amount [integer]: Invoice value in cents. Minimum = 0 (any value will be accepted). ex: 1234 (= R$ 12.34) + - amount [integer]: Invoice value in cents. Minimum = 0 (any value will be accepted). ex: 1234 (= R$ 12.34). If amount = 0, the Invoice will accept any amount paid by the customer; otherwise, only the exact amount will be accepted. When paid, this attribute is updated with the amount actually paid. - tax_id [string]: payer tax ID (CPF or CNPJ) with or without formatting. ex: "01234567890" or "20.018.183/0001-80" - name [string]: payer name. ex: "Iron Bank S.A." ## Parameters (optional): - due [datetime.datetime or datetime.date or string, default now + 2 days]: Invoice due date in UTC ISO format. ex: "2020-10-28T17:59:26.249976+00:00" for immediate invoices and "2020-10-28" for scheduled invoices - - expiration [integer or datetime.timedelta, default 5097600 (59 days)]: time interval in seconds between due date and expiration date. ex 123456789 + - expiration [integer or datetime.timedelta, default 5097600 (59 days)]: time interval in seconds between due date and expiration date. After the expiration, the Invoice can no longer be paid. ex 123456789 - fine [float, default 2.0]: Invoice fine for overdue payment in %. ex: 2.5 - interest [float, default 1.0]: Invoice monthly interest for overdue payment in %. ex: 5.2 - - discounts [list of dictionaries, default []]: list of dictionaries with "percentage":float and "due":datetime.datetime or string pairs + - discounts [list of dictionaries, default []]: list of up to 5 dictionaries with "percentage":float and "due":datetime.datetime or string pairs - rules [list of Invoice.Rules, default []]: list of Invoice.Rule objects for modifying invoice behavior. ex: [Invoice.Rule(key="allowedTaxIds", value=[ "012.345.678-90", "45.059.493/0001-73" ])] - splits [list of Split.Splits, default []]: list of Split.Splits objects to indicate payment receivers. ex: [Invoice.Split(amount=141, receiverId="5706627130851328")] - - tags [list of strings, default []]: list of strings for tagging - - descriptions [list of dictionaries, default []]: list of dictionaries with "key":string and (optional) "value":string pairs + - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase. + - descriptions [list of dictionaries, default []]: list of up to 15 dictionaries with "key":string and (optional) "value":string pairs ## Attributes (return-only): - pdf [string]: public Invoice PDF URL. ex: "https://invoice.starkbank.com/pdf/d454fa4e524441c1b0c1a729457ed9d8" - link [string]: public Invoice webpage URL. ex: "https://my-workspace.sandbox.starkbank.com/invoicelink/d454fa4e524441c1b0c1a729457ed9d8" @@ -106,7 +106,7 @@ def _parse_splits(splits): def create(invoices, user=None): """# Create Invoices - Send a list of Invoice objects for creation in the Stark Bank API + Send a list of Invoice objects for creation in the Stark Bank API. You can create up to 100 Invoices per call. ## Parameters (required): - invoices [list of Invoice objects]: list of Invoice objects to be created in the API ## Parameters (optional): @@ -188,12 +188,12 @@ def page(cursor=None, limit=None, status=None, tags=None, ids=None, after=None, def update(id, status=None, amount=None, due=None, expiration=None, user=None): """# Update Invoice entity - Update an Invoice by passing id, if it hasn't been paid yet. + Update an Invoice by passing its id. If the invoice hasn't been paid yet, you can adjust parameters such as the amount, due date and expiration; if it has already been paid, you may only decrease the amount, which triggers a payment reversal. ## Parameters (required): - id [string]: Invoice id. ex: '5656565656565656' ## Parameters (optional): - status [string]: You may cancel the invoice by passing 'canceled' in the status - - amount [string]: Nominal amount charged by the invoice. ex: 100 (R$1.00) + - amount [string, default None]: new amount to be charged. If the Invoice has already been paid, this is the final amount after reversal. ex: 100 (R$1.00) - due [datetime.datetime or string, default now + 2 days]: Invoice due date in UTC ISO format. ex: "2020-10-28T17:59:26.249976+00:00" - expiration [integer or datetime.timedelta, default None]: time interval in seconds between the due date and the expiration date. ex 123456789 - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call diff --git a/starkbank/invoicepullsubscription/__invoicepullsubscription.py b/starkbank/invoicepullsubscription/__invoicepullsubscription.py index 82760d14..6ee2bace 100644 --- a/starkbank/invoicepullsubscription/__invoicepullsubscription.py +++ b/starkbank/invoicepullsubscription/__invoicepullsubscription.py @@ -19,11 +19,11 @@ class InvoicePullSubscription(Resource): - amount_min_limit [integer, 0 None]: subscription minimum amount in cents. Required if an amount is not informed. Minimum = 1 (R$ 0.01). ex: 100 (= R$ 1.00) ## Parameters (optional): - display_description [string, default None]: Invoice description to be shown to the payer. ex: "Subscription payment" - - due [datetime.timedelta or integer, default None]: subscription invoice due offset. Available only for type "push". ex: timedelta(days=7) + - due [datetime.date, datetime.datetime or string, default None]: date by which the payer must approve or deny the subscription; defaults to 2 days after creation if not informed. Applies to every subscription type. ex: "2022-04-08" - external_id [string, default None]: string that must be unique among all your InvoicePullSubscriptions. Duplicated external_ids will cause failures. ex: "my-external-id" - reference_code [string, default None]: reference code for reconciliation. ex: "REF123456" - end [datetime.date or string, default None]: subscription end date. ex: "2023-04-01" - - data [dictionary, default None]: additional data for the subscription based on type + - data [dictionary, default None]: additional data for the subscription, required for types "push" (payer's account details), "qrcodeAndPayment" and "paymentAndOrQrcode" (immediate payment parameters); not required for type "qrcode" - name [string, default None]: subscription debtor name. ex: "Iron Bank S.A." - tax_id [string, default None]: subscription debtor tax ID (CPF or CNPJ) with or without formatting. ex: "01234567890" or "20.018.183/0001-80" - tags [list of strings, default []]: list of strings for tagging @@ -161,7 +161,7 @@ def page(cursor=None, limit=None, status=None, invoice_ids=None, external_ids=No def cancel(id, user=None): """# Cancel an InvoicePullSubscription entity - Cancel an InvoicePullSubscription entity previously created in the Stark Bank API + Cancel an InvoicePullSubscription entity previously created in the Stark Bank API. The subscription must currently be in "active" status to be canceled. ## Parameters (required): - id [string]: InvoicePullSubscription unique id. ex: '5656565656565656' ## Parameters (optional): diff --git a/starkbank/merchantcard/__merchantcard.py b/starkbank/merchantcard/__merchantcard.py index f4b5e23a..279c5a43 100644 --- a/starkbank/merchantcard/__merchantcard.py +++ b/starkbank/merchantcard/__merchantcard.py @@ -4,7 +4,12 @@ class MerchantCard(Resource): """# MerchantCard object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-card + Stores information about a card used in an approved purchase, so it can be reused in new purchases without a new MerchantSession. + ## Attributes (return-only): + - id, ending, funding_type, holder_name, network [string] + - status [string]: current status. ex: "active", "expired", "canceled" or "blocked" + - tags [list of strings] + - expiration, created, updated [datetime] """ def __init__(self, id=None, ending=None , funding_type=None, holder_name=None, network=None, status=None, tags=None, @@ -25,10 +30,32 @@ def __init__(self, id=None, ending=None , funding_type=None, holder_name=None, n def get(id, user=None): + """# Retrieve a specific MerchantCard + Receive a single MerchantCard object previously created in the Stark Bank API by its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantCard object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None): + """# Retrieve MerchantCards + Receive a generator of MerchantCard objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [string, default None]: filter for status of retrieved objects. ex: "active" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantCard objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -42,6 +69,22 @@ def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, def page(cursor=None, limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None): + """# Retrieve paged MerchantCards + Receive a list of up to 100 MerchantCard objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [string, default None]: filter for status of retrieved objects. ex: "active" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantCard objects with updated attributes + - cursor to retrieve the next page of MerchantCard objects + """ return rest.get_page( resource=_resource, cursor=cursor, diff --git a/starkbank/merchantcard/log/__log.py b/starkbank/merchantcard/log/__log.py index 68975830..6413e815 100644 --- a/starkbank/merchantcard/log/__log.py +++ b/starkbank/merchantcard/log/__log.py @@ -7,7 +7,15 @@ class Log(Resource): """# merchantcard.Log object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-card + Every time a MerchantCard entity is updated, a corresponding merchantcard.Log is generated for the entity. This + log is never generated by the user. + ## Attributes (return-only): + - id [string]: unique id returned when the log is created. ex: "5656565656565656" + - card [MerchantCard]: MerchantCard entity to which the log refers to. + - errors [list of strings]: list of errors linked to this MerchantCard event + - type [string]: type of the MerchantCard event which triggered the log creation. ex: "created", "updated" + - created [datetime.datetime]: creation datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - updated [datetime.datetime]: latest update datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, id, created, updated, type, errors, card): @@ -23,10 +31,31 @@ def __init__(self, id, created, updated, type, errors, card): def get(id, user=None): + """# Retrieve a specific MerchantCardLog + Receive a single MerchantCardLog object previously created by the Stark Bank API by passing its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantCardLog object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, card_ids=None, after=None, before=None, user=None, types=None): + """# Retrieve MerchantCardLogs + Receive a generator of MerchantCardLog objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - card_ids [list of strings, default None]: list of MerchantCard ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantCardLog objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -39,6 +68,21 @@ def query(limit=None, card_ids=None, after=None, before=None, user=None, types=N def page(cursor=None, limit=None, card_ids=None, after=None, before=None, user=None, types=None): + """# Retrieve paged MerchantCardLogs + Receive a list of up to 100 MerchantCardLog objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - card_ids [list of strings, default None]: list of MerchantCard ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantCardLog objects with updated attributes + - cursor to retrieve the next page of MerchantCardLog objects + """ return rest.get_page( resource=_resource, cursor=cursor, diff --git a/starkbank/merchantinstallment/__merchantinstallment.py b/starkbank/merchantinstallment/__merchantinstallment.py index 8af224ba..99a325f3 100644 --- a/starkbank/merchantinstallment/__merchantinstallment.py +++ b/starkbank/merchantinstallment/__merchantinstallment.py @@ -5,7 +5,20 @@ class MerchantInstallment(Resource): """# MerchantInstallment object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-installment + Represents one installment of a MerchantPurchase, generated automatically by the Stark Bank API when the purchase is split. + ## Attributes (return-only): + - id [string]: unique id returned when MerchantInstallment is created. ex: "5656565656565656" + - amount [integer]: MerchantInstallment value in cents. ex: 1234 (= R$ 12.34) + - due [datetime.date or datetime.datetime]: MerchantInstallment due date. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - fee [integer]: fee charged when the MerchantInstallment is processed. ex: 200 (= R$ 2.00) + - funding_type [string]: installment funding type. ex: "credit" + - network [string]: card network flag. ex: "visa", "mastercard" + - purchase_id [string]: unique id of the MerchantPurchase to which this installment belongs. ex: "5656565656565656" + - status [string]: current MerchantInstallment status. ex: "created", "success", "failed" + - tags [list of strings]: list of strings for tagging + - transaction_ids [list of strings]: ledger transaction ids linked to this MerchantInstallment + - created [datetime.datetime]: creation datetime for the MerchantInstallment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - updated [datetime.datetime]: latest update datetime for the MerchantInstallment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, id=None, amount=None, created=None, due=None, fee=None, funding_type=None, network=None, @@ -29,10 +42,33 @@ def __init__(self, id=None, amount=None, created=None, due=None, fee=None, fundi def get(id, user=None): + """# Retrieve a specific MerchantInstallment + Receive a single MerchantInstallment object previously created in the Stark Bank API by its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantInstallment object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None, purchase_ids=None): + """# Retrieve MerchantInstallments + Receive a generator of MerchantInstallment objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [string, default None]: filter for status of retrieved objects. ex: "success" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - purchase_ids [list of strings, default None]: list of MerchantPurchase ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantInstallment objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -47,6 +83,23 @@ def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, def page(cursor=None, limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None, purchase_ids=None): + """# Retrieve paged MerchantInstallments + Receive a list of up to 100 MerchantInstallment objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [string, default None]: filter for status of retrieved objects. ex: "success" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - purchase_ids [list of strings, default None]: list of MerchantPurchase ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantInstallment objects with updated attributes + - cursor to retrieve the next page of MerchantInstallment objects + """ return rest.get_page( resource=_resource, cursor=cursor, diff --git a/starkbank/merchantinstallment/log/__log.py b/starkbank/merchantinstallment/log/__log.py index 2db81c50..3740da06 100644 --- a/starkbank/merchantinstallment/log/__log.py +++ b/starkbank/merchantinstallment/log/__log.py @@ -7,7 +7,15 @@ class Log(Resource): """# merchantinstallment.Log object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-installment + Every time a MerchantInstallment entity is updated, a corresponding merchantinstallment.Log is generated for the entity. This + log is never generated by the user. + ## Attributes (return-only): + - id [string]: unique id returned when the log is created. ex: "5656565656565656" + - installment [MerchantInstallment]: MerchantInstallment entity to which the log refers to. + - errors [list of strings]: list of errors linked to this MerchantInstallment event + - type [string]: type of the MerchantInstallment event which triggered the log creation. ex: "created", "updated" + - created [datetime.datetime]: creation datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - updated [datetime.datetime]: latest update datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, id, created, updated, type, errors, installment): @@ -23,10 +31,31 @@ def __init__(self, id, created, updated, type, errors, installment): def get(id, user=None): + """# Retrieve a specific MerchantInstallmentLog + Receive a single MerchantInstallmentLog object previously created by the Stark Bank API by passing its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantInstallmentLog object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, after=None, before=None, types=None, user=None, installment_ids=None): + """# Retrieve MerchantInstallmentLogs + Receive a generator of MerchantInstallmentLog objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - installment_ids [list of strings, default None]: list of MerchantInstallment ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantInstallmentLog objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -39,6 +68,21 @@ def query(limit=None, after=None, before=None, types=None, user=None, installmen def page(cursor=None, limit=None, after=None, before=None, types=None, user=None, installment_ids=None): + """# Retrieve paged MerchantInstallmentLogs + Receive a list of up to 100 MerchantInstallmentLog objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - installment_ids [list of strings, default None]: list of MerchantInstallment ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantInstallmentLog objects with updated attributes + - cursor to retrieve the next page of MerchantInstallmentLog objects + """ return rest.get_page( resource=_resource, cursor=cursor, diff --git a/starkbank/merchantpurchase/__merchantpurchase.py b/starkbank/merchantpurchase/__merchantpurchase.py index 30f15e7b..eb415310 100644 --- a/starkbank/merchantpurchase/__merchantpurchase.py +++ b/starkbank/merchantpurchase/__merchantpurchase.py @@ -5,7 +5,33 @@ class MerchantPurchase(Resource): """# MerchantPurchase object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-purchase + When you initialize a MerchantPurchase, the entity will not be automatically + sent to the Stark Bank API. The 'create' function sends the object + to the Stark Bank API and returns the created object. + ## Parameters (required): + - amount [integer]: MerchantPurchase value in cents. ex: 1234 (= R$ 12.34) + - card_id [string]: unique id of the MerchantCard or MerchantSession Purchase used. ex: "5656565656565656" + - funding_type [string]: type of funding used. ex: "credit", "debit" + - installment_count [integer]: number of installments the purchase is split into. ex: 1 + ## Parameters (optional): + - card_expiration, card_number, card_security_code, holder_name, holder_email, holder_phone, holder_id [string, default None]: card and holder data, required only when not created through a MerchantSession. + - billing_country_code, billing_city, billing_state_code, billing_street_line_1, billing_street_line_2, billing_zip_code [string, default None]: billing address data. + - metadata [dictionary, default None]: additional 3DS metadata sent by the merchant's browser/app. + - soft_descriptor [string, default None]: text that will be shown in the holder's bank statement. ex: "my-store" + - tags [list of strings, default None]: list of strings for tagging + ## Attributes (return-only): + - id [string]: unique id returned when MerchantPurchase is created. ex: "5656565656565656" + - card_ending [string]: last 4 digits of the card used. ex: "1234" + - challenge_mode [string]: whether 3DS holder verification was used. ex: "enabled", "disabled" + - challenge_url [string]: URL to the 3DS challenge, when applicable. + - currency_code [string]: currency of the purchase. ex: "BRL" + - end_to_end_id [string]: unique transaction id for the acquirer network. + - fee [integer]: fee charged when the MerchantPurchase is processed. ex: 200 (= R$ 2.00) + - network [string]: card network flag. ex: "visa", "mastercard" + - source [string]: locator of the entity that generated the purchase. ex: "merchant-session/{sessionId}" + - status [string]: current MerchantPurchase status. ex: "approved", "confirmed", "canceled", "voided" + - created [datetime.datetime]: creation datetime for the MerchantPurchase. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - updated [datetime.datetime]: latest update datetime for the MerchantPurchase. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, amount, card_id, funding_type, installment_count, id=None, card_expiration=None, @@ -53,14 +79,46 @@ def __init__(self, amount, card_id, funding_type, installment_count, id=None, ca def create(merchant_purchase, user=None): + """# Create a MerchantPurchase + Send a MerchantPurchase object for creation in the Stark Bank API + ## Parameters (required): + - merchant_purchase [MerchantPurchase object]: MerchantPurchase object to be created in the API + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantPurchase object with updated attributes + """ return rest.post_single(resource=_resource, entity=merchant_purchase, user=user) def get(id, user=None): + """# Retrieve a specific MerchantPurchase + Receive a single MerchantPurchase object previously created in the Stark Bank API by its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantPurchase object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, holder_id=None, user=None): + """# Retrieve MerchantPurchases + Receive a generator of MerchantPurchase objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [string, default None]: filter for status of retrieved objects. ex: "approved" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - holder_id [string, default None]: filter for purchases made with cards belonging to a specific holder. ex: "5656565656565656" + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantPurchase objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -75,6 +133,23 @@ def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, def page(cursor=None, limit=None, after=None, before=None, status=None, tags=None, ids=None, holder_id=None, user=None): + """# Retrieve paged MerchantPurchases + Receive a list of up to 100 MerchantPurchase objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [string, default None]: filter for status of retrieved objects. ex: "approved" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - holder_id [string, default None]: filter for purchases made with cards belonging to a specific holder. ex: "5656565656565656" + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantPurchase objects with updated attributes + - cursor to retrieve the next page of MerchantPurchase objects + """ return rest.get_page( resource=_resource, cursor=cursor, @@ -90,6 +165,17 @@ def page(cursor=None, limit=None, after=None, before=None, status=None, tags=Non def update(id, status=None, amount=None, user=None): + """# Update MerchantPurchase entity + Update a MerchantPurchase by its id. If the purchase is "approved", you may only cancel it by passing status="canceled" together with amount=0. If the purchase is "confirmed", you may pass status="reversed" with a lower amount to debit and reverse the difference, partially or totally; a partial reversal keeps status "confirmed", while a full reversal moves it to "voided". + ## Parameters (required): + - id [string]: MerchantPurchase id. + ## Parameters (optional): + - status [string, default None]: "canceled" or "reversed", per the rules above. + - amount [integer, default None]: new amount; 0 to cancel an approved purchase, or a lower value to partially/fully reverse a confirmed one. + - user [Organization/Project object, default None]. + ## Return: + - target MerchantPurchase with updated attributes + """ payload = { "status": status, "amount": amount diff --git a/starkbank/merchantpurchase/log/__log.py b/starkbank/merchantpurchase/log/__log.py index 3ddcc4dd..cc248dc5 100644 --- a/starkbank/merchantpurchase/log/__log.py +++ b/starkbank/merchantpurchase/log/__log.py @@ -7,7 +7,14 @@ class Log(Resource): """# merchantpurchase.Log object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-purchase + Every time a MerchantPurchase entity is updated, a corresponding merchantpurchase.Log is generated for the entity. This + log is never generated by the user. + ## Attributes (return-only): + - id [string]: unique id returned when the log is created. ex: "5656565656565656" + - purchase [MerchantPurchase]: MerchantPurchase entity to which the log refers to. + - errors [list of strings]: list of errors linked to this MerchantPurchase event + - type [string]: type of the MerchantPurchase event which triggered the log creation. ex: "created", "updated" + - created [datetime.datetime]: creation datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, id, created, type, errors, purchase): @@ -23,10 +30,31 @@ def __init__(self, id, created, type, errors, purchase): def get(id, user=None): + """# Retrieve a specific MerchantPurchaseLog + Receive a single MerchantPurchaseLog object previously created by the Stark Bank API by passing its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantPurchaseLog object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, after=None, before=None, types=None, user=None, purchase_ids=None): + """# Retrieve MerchantPurchaseLogs + Receive a generator of MerchantPurchaseLog objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - purchase_ids [list of strings, default None]: list of MerchantPurchase ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantPurchaseLog objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -38,6 +66,21 @@ def query(limit=None, after=None, before=None, types=None, user=None, purchase_i ) def page(cursor=None, limit=None, after=None, before=None, types=None, user=None, purchase_ids=None): + """# Retrieve paged MerchantPurchaseLogs + Receive a list of up to 100 MerchantPurchaseLog objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - purchase_ids [list of strings, default None]: list of MerchantPurchase ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantPurchaseLog objects with updated attributes + - cursor to retrieve the next page of MerchantPurchaseLog objects + """ return rest.get_page( resource=_resource, cursor=cursor, diff --git a/starkbank/merchantsession/__merchantsession.py b/starkbank/merchantsession/__merchantsession.py index df0b7bab..67f8dae8 100644 --- a/starkbank/merchantsession/__merchantsession.py +++ b/starkbank/merchantsession/__merchantsession.py @@ -9,7 +9,25 @@ class MerchantSession(Resource): """# MerchantSession object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-session + When you initialize a MerchantSession, the entity will not be automatically + sent to the Stark Bank API. The 'create' function sends the object + to the Stark Bank API and returns the created object. + ## Parameters (required): + - allowed_funding_types [list of strings]: funding types allowed for the purchase. Options: "credit", "debit" + - allowed_installments [list of MerchantSession.AllowedInstallment]: amount/installment-count combinations allowed for the purchase + - expiration [integer or datetime.timedelta]: time in seconds from creation until the session expires; after expiration, no purchase can be created with it + ## Parameters (optional): + - allowed_ips [list of strings, default []]: IP addresses allowed to create a purchase with this session + - challenge_mode [string, default "enabled"]: whether 3DS holder verification is used. Options: "enabled", "disabled" + - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase. + ## Attributes (return-only): + - id [string]: unique id returned when MerchantSession is created. ex: "5656565656565656" + - uuid [string]: unique uuid returned when MerchantSession is created, used to create a MerchantSession Purchase. ex: "901e71f2447c43c886f58366a5432c4b" + - holder_id [string]: unique id of the card holder associated with this session, when applicable. + - soft_descriptor [string]: text that will be shown in the holder's bank statement, when applicable. + - status [string]: current MerchantSession status. ex: "created", "expired" + - created [datetime.datetime]: creation datetime for the MerchantSession. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - updated [datetime.datetime]: latest update datetime for the MerchantSession. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, allowed_funding_types, allowed_installments, expiration, id=None, allowed_ips=None, @@ -45,14 +63,46 @@ def _parse_allowed_installments(allowed_installments): def create(merchant_session, user=None): + """# Create a MerchantSession + Send a MerchantSession object for creation in the Stark Bank API + ## Parameters (required): + - merchant_session [MerchantSession object]: MerchantSession object to be created in the API + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantSession object with updated attributes + """ return rest.post_single(resource=_resource, entity=merchant_session, user=user) def get(id, user=None): + """# Retrieve a specific MerchantSession + Receive a single MerchantSession object previously created in the Stark Bank API by its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantSession object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, status=None, tags=None, ids=None, after=None, before=None, holder_id=None, user=None): + """# Retrieve MerchantSessions + Receive a generator of MerchantSession objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - status [string, default None]: filter for status of retrieved objects. ex: "created" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - holder_id [string, default None]: filter for sessions belonging to a specific card holder. ex: "5656565656565656" + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantSession objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -67,6 +117,23 @@ def query(limit=None, status=None, tags=None, ids=None, after=None, before=None, def page(cursor=None, limit=None, status=None, tags=None, ids=None, after=None, before=None, holder_id=None, user=None): + """# Retrieve paged MerchantSessions + Receive a list of up to 100 MerchantSession objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - status [string, default None]: filter for status of retrieved objects. ex: "created" + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - holder_id [string, default None]: filter for sessions belonging to a specific card holder. ex: "5656565656565656" + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantSession objects with updated attributes + - cursor to retrieve the next page of MerchantSession objects + """ return rest.get_page( resource=_resource, cursor=cursor, @@ -82,5 +149,18 @@ def page(cursor=None, limit=None, status=None, tags=None, ids=None, after=None, def purchase(uuid, purchase, user=None): + """# Create a MerchantSession Purchase + Send a MerchantPurchase object linked to a previously created MerchantSession, identified by its uuid, for creation in the Stark Bank API. + Depending on the MerchantSession's allowed_funding_types and 3DS configuration, the billing and card holder fields on the MerchantPurchase + (card_expiration, card_number, card_security_code, holder_name, holder_email, holder_phone, holder_id, billing_country_code, billing_city, + billing_state_code, billing_street_line_1, billing_street_line_2, billing_zip_code) and the 3DS metadata may be conditionally required. + ## Parameters (required): + - uuid [string]: MerchantSession unique uuid returned on creation. ex: "901e71f2447c43c886f58366a5432c4b" + - purchase [MerchantPurchase object]: MerchantPurchase object to be created against this session + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantPurchase object with updated attributes + """ return rest.post_sub_resource(resource=_resource, id=uuid, sub_resource=purchase_resource, entity=purchase, user=user) diff --git a/starkbank/merchantsession/log/__log.py b/starkbank/merchantsession/log/__log.py index e14bb0b9..15751d0e 100644 --- a/starkbank/merchantsession/log/__log.py +++ b/starkbank/merchantsession/log/__log.py @@ -7,7 +7,14 @@ class Log(Resource): """# merchantsession.Log object - Check out our API Documentation at https://starkbank.com/docs/api#merchant-session + Every time a MerchantSession entity is updated, a corresponding merchantsession.Log is generated for the entity. This + log is never generated by the user. + ## Attributes (return-only): + - id [string]: unique id returned when the log is created. ex: "5656565656565656" + - session [MerchantSession]: MerchantSession entity to which the log refers to. + - errors [list of strings]: list of errors linked to this MerchantSession event + - type [string]: type of the MerchantSession event which triggered the log creation. ex: "created", "updated" + - created [datetime.datetime]: creation datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) """ def __init__(self, id, created, type, errors, session): @@ -22,10 +29,31 @@ def __init__(self, id, created, type, errors, session): def get(id, user=None): + """# Retrieve a specific MerchantSessionLog + Receive a single MerchantSessionLog object previously created by the Stark Bank API by passing its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - MerchantSessionLog object with updated attributes + """ return rest.get_id(resource=_resource, id=id, user=user) def query(limit=None, after=None, before=None, types=None, session_ids=None, user=None): + """# Retrieve MerchantSessionLogs + Receive a generator of MerchantSessionLog objects previously created in the Stark Bank API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - session_ids [list of strings, default None]: list of MerchantSession ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - generator of MerchantSessionLog objects with updated attributes + """ return rest.get_stream( resource=_resource, limit=limit, @@ -38,6 +66,21 @@ def query(limit=None, after=None, before=None, types=None, session_ids=None, use def page(cursor=None, limit=None, after=None, before=None, types=None, session_ids=None, user=None): + """# Retrieve paged MerchantSessionLogs + Receive a list of up to 100 MerchantSessionLog objects previously created in the Stark Bank API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call + - limit [integer, default 100]: maximum number of objects to be retrieved. It must be an integer between 1 and 100. ex: 50 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - types [list of strings, default None]: filter retrieved objects by event types. ex: ["created", "updated"] + - session_ids [list of strings, default None]: list of MerchantSession ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call + ## Return: + - list of MerchantSessionLog objects with updated attributes + - cursor to retrieve the next page of MerchantSessionLog objects + """ return rest.get_page( resource=_resource, cursor=cursor, diff --git a/starkbank/paymentrequest/__paymentrequest.py b/starkbank/paymentrequest/__paymentrequest.py index 171252d8..798e942f 100644 --- a/starkbank/paymentrequest/__paymentrequest.py +++ b/starkbank/paymentrequest/__paymentrequest.py @@ -25,12 +25,12 @@ class PaymentRequest(Resource): cost center page. ## Parameters (required): - center_id [string]: target cost center ID. ex: "5656565656565656" - - payment [Transfer, BoletoPayment, UtilityPayment, BrcodePayment, Transaction, DarfPayment, TaxPayment or dictionary]: payment entity that should be approved and executed. + - payment [Transfer, BoletoPayment, UtilityPayment, BrcodePayment, Transaction, DarfPayment, TaxPayment or dictionary]: payment entity that should be approved and executed. Do not set a "scheduled" value on this entity -- the PaymentRequest's own due date serves that purpose. ## Parameters (conditionally required): - type [string]: payment type, inferred from the payment parameter if it is not a dictionary. ex: "transfer", "boleto-payment" ## Parameters (optional): - - due [datetime.date or string, default today]: Payment target date in ISO format. ex: 2020-04-30 - - tags [list of strings]: list of strings for tagging + - due [datetime.date or string, default today]: suggested payment target date in ISO format; the cost center's controllers may alter it during approval. ex: 2020-04-30 + - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase. ## Attributes (return-only): - id [string]: unique id returned when a PaymentRequest is created. ex: "5656565656565656" - amount [integer]: PaymentRequest amount. ex: 100000 = R$1.000,00 diff --git a/starkbank/splitprofile/__splitprofile.py b/starkbank/splitprofile/__splitprofile.py index 43986f1b..b5f22672 100644 --- a/starkbank/splitprofile/__splitprofile.py +++ b/starkbank/splitprofile/__splitprofile.py @@ -80,7 +80,7 @@ def query(limit=None, after=None, before=None, transaction_ids=None, status=None def page(cursor=None, after=None, before=None, tags=None, ids=None, receiver_ids=None, status=None, limit=None, user=None): """# Retrieve paged Split Profiles - Receive a list of up to 100 Split Profiles objects previously created in the Stark Bank API and the cursor to the next page. + Receive a list of up to 100 SplitProfile objects previously created in the Stark Bank API and the cursor to the next page. Use this function instead of query if you want to manually page your requests. ## Parameters (optional): - cursor [string, default None]: cursor returned on the previous page function call @@ -89,12 +89,11 @@ def page(cursor=None, after=None, before=None, tags=None, ids=None, receiver_ids - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"] - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] - - receiver_ids [list of strings, default None]: list of receiver ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] - status [string, default None]: filter for status of retrieved objects. ex: "success" - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call ## Return: - - list of Split objects with updated attributes - - cursor to retrieve the next page of Split objects + - list of SplitProfile objects with updated attributes + - cursor to retrieve the next page of SplitProfile objects """ return rest.get_page( resource=_resource, diff --git a/starkbank/taxpayment/__taxpayment.py b/starkbank/taxpayment/__taxpayment.py index 6b77ff1a..a4258f16 100644 --- a/starkbank/taxpayment/__taxpayment.py +++ b/starkbank/taxpayment/__taxpayment.py @@ -15,7 +15,7 @@ class TaxPayment(Resource): - description [string]: Text to be displayed in your statement (min. 10 characters). ex: "payment ABC" ## Parameters (optional): - scheduled [datetime.date or string, default today]: payment scheduled date. ex: datetime.date(2020, 3, 10) - - tags [list of strings]: list of strings for tagging + - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase. ## Attributes (return-only): - id [string]: unique id returned when payment is created. ex: "5656565656565656" - type [string]: tax type. ex: "das" @@ -77,7 +77,7 @@ def get(id, user=None): def pdf(id, user=None): """# Retrieve a specific TaxPayment pdf file Receive a single TaxPayment pdf file generated in the Stark Bank API by passing its id. - Only valid for tax payments with "success" status. + Only valid for tax payments with "success", "processing" or "created" status. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): @@ -146,7 +146,7 @@ def page(cursor=None, limit=None, after=None, before=None, tags=None, ids=None, def delete(id, user=None): """# Delete a TaxPayment entity - Delete a TaxPayment entity previously created in the Stark Bank API + Delete a TaxPayment entity previously created in the Stark Bank API. This only cancels payments that have not yet started processing; payments already processed can still be deleted, but are not reversed. ## Parameters (required): - id [string]: TaxPayment unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/transaction/__transaction.py b/starkbank/transaction/__transaction.py index 2cd91af5..8ff9958c 100644 --- a/starkbank/transaction/__transaction.py +++ b/starkbank/transaction/__transaction.py @@ -48,17 +48,8 @@ def __init__(self, amount, description, external_id, receiver_id, sender_id=None def create(transactions, user=None): - """ - Deprecated: Function deprecated since v2.31.0 - """ - """# Create Transactions - Send a list of Transaction objects for creation in the Stark Bank API - ## Parameters (required): - - transactions [list of Transaction objects]: list of Transaction objects to be created in the API - ## Parameters (optional): - - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call - ## Return: - - list of Transaction objects with updated attributes + """# [DEPRECATED] Create Transactions + This function is deprecated since v2.31.0 and always raises a StarkError. Transactions are now created only indirectly, as a side effect of other operations (such as transfer or charge-payment). """ raise StarkError([{"code": "deprecated", "message": "Function deprecated since v2.31.0"}]) diff --git a/starkbank/transfer/__transfer.py b/starkbank/transfer/__transfer.py index 109340a8..b35ace03 100644 --- a/starkbank/transfer/__transfer.py +++ b/starkbank/transfer/__transfer.py @@ -18,13 +18,13 @@ class Transfer(Resource): - bank_code [string]: code of the receiver bank institution in Brazil. If an ISPB (8 digits) is informed, a PIX transfer will be created, else a TED will be issued. ex: "20018183" or "341" - branch_code [string]: receiver bank account branch. Use '-' in case there is a verifier digit. ex: "1357-9" - account_number [string]: receiver bank account number. Use '-' before the verifier digit. ex: "876543-2" - - account_type [string]: Receiver bank account type. This parameter only has effect on Pix Transfers. ex: "checking", "savings", "salary" or "payment" ## Parameters (optional): + - account_type [string, default "checking"]: Receiver bank account type. Only has effect on Pix Transfers. ex: "checking", "savings", "salary" or "payment" - external_id [string, default None]: url safe string that must be unique among all your transfers. Duplicated external_ids will cause failures. By default, this parameter will block any transfer that repeats amount and receiver information on the same date. ex: "my-internal-id-123456" - - scheduled [datetime.date, datetime.datetime or string, default now]: date or datetime when the transfer will be processed. May be pushed to next business day if necessary. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - scheduled [datetime.date, datetime.datetime or string, default now]: date or datetime when the transfer will be processed. Ted transfers scheduled for today are accepted until 16:00 (BRT) and pushed to the next business day afterwards; Pix transfers are available 24/7 and may be scheduled for any date and time. - description [string, default None]: optional description to override default description to be shown in the bank statement. ex: "Payment for service #1234" - display_description [string, default None]: optional description to be shown in the receiver bank interface. ex: 'Payment for service #1234' - - tags [list of strings, default []]: list of strings for reference when searching for transfers. ex: ["employees", "monthly"] + - tags [list of strings, default []]: list of strings for reference when searching for transfers. All tags will be converted to lowercase. ex: ["employees", "monthly"] - rules [list of Transfer.Rules, default []]: list of Transfer.Rule objects for modifying transfer behavior. ex: [Transfer.Rule(key="resendingLimit", value=5)] ## Attributes (return-only): - id [string]: unique id returned when the transfer is created. ex: "5656565656565656" @@ -106,7 +106,7 @@ def get(id, user=None): def delete(id, user=None): """# Delete a Transfer entity - Delete a Transfer entity previously created in the Stark Bank API + Cancel a scheduled Transfer entity, previously created in the Stark Bank API, before it starts being processed. Canceled transfers still appear in later queries. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/utilitypayment/__utilitypayment.py b/starkbank/utilitypayment/__utilitypayment.py index 60dfab75..4891b3e7 100644 --- a/starkbank/utilitypayment/__utilitypayment.py +++ b/starkbank/utilitypayment/__utilitypayment.py @@ -15,7 +15,7 @@ class UtilityPayment(Resource): - description [string]: Text to be displayed in your statement (min. 10 characters). ex: "payment ABC" ## Parameters (optional): - scheduled [datetime.date or string, default today]: payment scheduled date. ex: datetime.date(2020, 3, 10) - - tags [list of strings]: list of strings for tagging + - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase. ## Attributes (return-only): - id [string]: unique id returned when payment is created. ex: "5656565656565656" - status [string]: current payment status. ex: "success" or "failed" @@ -77,7 +77,7 @@ def get(id, user=None): def pdf(id, user=None): """# Retrieve a specific UtilityPayment pdf file Receive a single UtilityPayment pdf file generated in the Stark Bank API by its id. - Only valid for utility payments with "success" status. + Only valid for utility payments with "success", "processing" or "created" status. ## Parameters (required): - id [string]: object unique id. ex: "5656565656565656" ## Parameters (optional): @@ -146,7 +146,7 @@ def page(cursor=None, limit=None, after=None, before=None, tags=None, ids=None, def delete(id, user=None): """# Delete a UtilityPayment entity - Delete a UtilityPayment entity previously created in the Stark Bank API + Delete a UtilityPayment entity previously created in the Stark Bank API. This only cancels payments that have not yet started processing; payments already processed can still be deleted, but are not reversed. ## Parameters (required): - id [string]: UtilityPayment unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/webhook/__webhook.py b/starkbank/webhook/__webhook.py index 10fc910d..1bc514a9 100644 --- a/starkbank/webhook/__webhook.py +++ b/starkbank/webhook/__webhook.py @@ -6,7 +6,8 @@ class Webhook(Resource): """# Webhook subscription object A Webhook is used to subscribe to notification events on a user-selected endpoint. Currently, available services for subscription are transfer, boleto, boleto-holmes, - boleto-payment, brcode-payment, utility-payment, deposit and invoice. + boleto-payment, brcode-payment, utility-payment, deposit, darf-payment, payment-request and invoice. + Events are delivered with a digital signature (the 'Digital-Signature' response header), verifiable with starkbank.event.parse(). If your endpoint does not return HTTP 200, delivery is retried up to three times, at 5, 30 and 120 minute intervals, after which the event is no longer resent -- use starkbank.event.query(is_delivered=False) daily to catch anything missed. A Webhook only receives events from the API version it was registered under. ## Parameters (required): - url [string]: Url that will be notified when an event occurs. - subscriptions [list of strings]: list of any non-empty combination of the available services. ex: ["transfer", "invoice", "deposit"] @@ -85,7 +86,7 @@ def page(cursor=None, limit=None, user=None): def delete(id, user=None): """# Delete a Webhook subscription entity - Delete a Webhook subscription entity previously created in the Stark Bank API + Delete a Webhook subscription entity previously created in the Stark Bank API. This action cannot be undone. ## Parameters (required): - id [string]: Webhook unique id. ex: "5656565656565656" ## Parameters (optional): diff --git a/starkbank/workspace/__workspace.py b/starkbank/workspace/__workspace.py index 9fde492f..481b0a88 100644 --- a/starkbank/workspace/__workspace.py +++ b/starkbank/workspace/__workspace.py @@ -10,7 +10,7 @@ class Workspace(Resource): The only property that is shared between your workspaces is that they are linked to your organization, which carries your basic informations, such as tax ID, name, etc.. ## Parameters (required): - - username [string]: Simplified name to define the workspace URL. This name must be unique across all Stark Bank Workspaces. ex: "starkbankworkspace" + - username [string]: Simplified, URL-safe name that defines the workspace URL. This name must be unique across all Stark Bank Workspaces. ex: "starkbankworkspace" - name [string]: Full name that identifies the Workspace. This name will appear when people access the Workspace on our platform, for example. ex: "Stark Bank Workspace" ## Parameters (optional): - allowed_tax_ids [list of strings, default None]: list of tax IDs that will be allowed to send Deposits to this Workspace. If empty, all are allowed. ex: ["012.345.678-90", "20.018.183/0001-80"]