# API Reference This is our second API version. It is another small step towards launching the product we want to create for you, but it's a giant leap for the Brazilian financial market. We created the first banking API in Brazil and we are proud of it. Our API is [RESTFul](https://en.wikipedia.org/wiki/Representational_State_Transfer). This means we use predictable, resource-oriented URLs to do banking operations. The API itself speaks exclusively in [JSON](http://www.json.org), including errors, but our [SDK libraries](https://github.com/starkinfra?q=sdk) convert responses to appropriate language-specific objects. Want to check our [OpenAPI 3.1](https://www.openapis.org/) specification? You can download our yaml file [right here](https://docs.starkinfra.com/static/starkinfra-openapi.yml). You can also try our [Postman](https://www.postman.com) collection. Download it [here](https://docs.starkinfra.com/static/starkinfra-postman.json). **Production URL:** `https://api.starkinfra.com` **Sandbox URL:** `https://sandbox.api.starkinfra.com` **Install (Python)** ```python pip install starkinfra ``` **SDK Repository:** https://github.com/starkinfra/sdk-python ## Available Languages Code samples on this page are in Python. The same content is available with samples in: - [Python](https://docs.starkinfra.com/api-python.md) - [Node.js](https://docs.starkinfra.com/api-node.md) - [PHP](https://docs.starkinfra.com/api-php.md) - [Java](https://docs.starkinfra.com/api-java.md) - [Ruby](https://docs.starkinfra.com/api-ruby.md) - [Elixir](https://docs.starkinfra.com/api-elixir.md) - [.NET](https://docs.starkinfra.com/api-dotnet.md) - [Go](https://docs.starkinfra.com/api-go.md) - [Clojure](https://docs.starkinfra.com/api-clojure.md) - [cURL](https://docs.starkinfra.com/api-curl.md) ## Contents - [Tech Support](#tech-support) - [Testing in Sandbox](#testing-in-sandbox) - [Moving to Production](#moving-to-production) - [Versioning](#versioning) - [Authentication](#authentication) - [Static IP list](#static-ip-list) - [Errors](#errors) - [Supported Languages](#supported-languages) - [Pagination](#pagination) - [Date & Time](#date--time) - **Pix** - [Pix Request](#pix-request): [Create Pix Requests](#create-pix-requests), [List Pix Requests](#list-pix-requests), [Get a Pix Request](#get-a-pix-request), [List Pix Request Logs](#list-pix-request-logs), [Get a Pix Request Log](#get-a-pix-request-log) - [Pix Reversal](#pix-reversal): [Create Pix Reversals](#create-pix-reversals), [List Pix Reversals](#list-pix-reversals), [Get a Pix Reversal](#get-a-pix-reversal), [List Pix Reversal Logs](#list-pix-reversal-logs), [Get a Pix Reversal Log](#get-a-pix-reversal-log) - [Pix Internal Transaction Report](#pix-internal-transaction-report): [Create Pix Internal Transaction Reports](#create-pix-internal-transaction-reports), [List Pix Internal Transaction Reports](#list-pix-internal-transaction-reports), [Get a Pix Internal Transaction Report](#get-a-pix-internal-transaction-report), [List Pix Internal Transaction Report Logs](#list-pix-internal-transaction-report-logs), [Get a Pix Internal Transaction Report Log](#get-a-pix-internal-transaction-report-log) - [Static Brcode](#static-brcode): [Create Static Brcodes](#create-static-brcodes), [List Static Brcodes](#list-static-brcodes), [Get a Static Brcode](#get-a-static-brcode) - [Dynamic Brcode](#dynamic-brcode): [Create Dynamic Brcodes](#create-dynamic-brcodes), [List Dynamic Brcodes](#list-dynamic-brcodes), [Get a Dynamic Brcode](#get-a-dynamic-brcode) - [Brcode Preview](#brcode-preview): [Create Brcode Previews](#create-brcode-previews) - [Pix Pull Subscription](#pix-pull-subscription): [Create Pix Pull Subscriptions](#create-pix-pull-subscriptions), [List Pix Pull Subscriptions](#list-pix-pull-subscriptions), [Get a Pix Pull Subscription](#get-a-pix-pull-subscription), [Update a Pix Pull Subscription](#update-a-pix-pull-subscription), [Cancel a Pix Pull Subscription](#cancel-a-pix-pull-subscription), [List Pix Pull Subscription Logs](#list-pix-pull-subscription-logs), [Get a Pix Pull Subscription Log](#get-a-pix-pull-subscription-log) - [Pix Pull Request](#pix-pull-request): [Create Pix Pull Requests](#create-pix-pull-requests), [List Pix Pull Requests](#list-pix-pull-requests), [Get a Pix Pull Request](#get-a-pix-pull-request), [Update a Pix Pull Request](#update-a-pix-pull-request), [Cancel a Pix Pull Request](#cancel-a-pix-pull-request), [List Pix Pull Request Logs](#list-pix-pull-request-logs), [Get a Pix Pull Request Log](#get-a-pix-pull-request-log) - [Pix Key](#pix-key): [Create a Pix Key](#create-a-pix-key), [List Pix Keys](#list-pix-keys), [Get a Pix Key](#get-a-pix-key), [Update a Pix Key](#update-a-pix-key), [Cancel a Pix Key](#cancel-a-pix-key), [List Pix Key Logs](#list-pix-key-logs), [Get a Pix Key Log](#get-a-pix-key-log) - [Pix Key Holmes](#pix-key-holmes): [Create Pix Key Holmes](#create-pix-key-holmes), [List Pix Key Holmes](#list-pix-key-holmes), [Get a Pix Key Holmes](#get-a-pix-key-holmes), [List Pix Key Holmes Logs](#list-pix-key-holmes-logs), [Get a Pix Key Holmes Log](#get-a-pix-key-holmes-log) - [Pix Claim](#pix-claim): [Create a Pix Claim](#create-a-pix-claim), [List Pix Claims](#list-pix-claims), [Get a Pix Claim](#get-a-pix-claim), [Update a Pix Claim](#update-a-pix-claim), [List Pix Claim Logs](#list-pix-claim-logs), [Get a Pix Claim Log](#get-a-pix-claim-log) - [Pix Infraction](#pix-infraction): [List Pix Infractions](#list-pix-infractions), [Get a Pix Infraction](#get-a-pix-infraction), [Update a Pix Infraction](#update-a-pix-infraction), [Cancel a Pix Infraction](#cancel-a-pix-infraction), [List Pix Infraction Logs](#list-pix-infraction-logs), [Get a Pix Infraction Log](#get-a-pix-infraction-log) - [Pix Chargeback](#pix-chargeback): [Create Pix Chargebacks](#create-pix-chargebacks), [List Pix Chargebacks](#list-pix-chargebacks), [Get a Pix Chargeback](#get-a-pix-chargeback), [Update a Pix Chargeback](#update-a-pix-chargeback), [Cancel a Pix Chargeback](#cancel-a-pix-chargeback), [List Pix Chargeback Logs](#list-pix-chargeback-logs), [Get a Pix Chargeback Log](#get-a-pix-chargeback-log) - [Pix Fraud](#pix-fraud): [Create Pix Fraud Reports](#create-pix-fraud-reports), [List Pix Fraud Reports](#list-pix-fraud-reports), [Get a Pix Fraud Report](#get-a-pix-fraud-report), [Cancel a Pix Fraud Report](#cancel-a-pix-fraud-report), [List Pix Fraud Logs](#list-pix-fraud-logs), [Get a Pix Fraud Log](#get-a-pix-fraud-log) - [Pix Dispute](#pix-dispute): [Create Pix Disputes](#create-pix-disputes), [List Pix Disputes](#list-pix-disputes), [Get a Pix Dispute](#get-a-pix-dispute), [Cancel a Pix Dispute](#cancel-a-pix-dispute), [List Pix Dispute Logs](#list-pix-dispute-logs), [Get a Pix Dispute Log](#get-a-pix-dispute-log) - [Pix User](#pix-user): [Get a Pix User](#get-a-pix-user) - [Pix Balance](#pix-balance): [Get Pix Balance](#get-pix-balance) - [Pix Domain](#pix-domain): [List Pix Domains](#list-pix-domains) - [Pix Statement](#pix-statement): [Create a Pix Statement](#create-a-pix-statement), [List Pix Statements](#list-pix-statements), [Get a Pix Statement](#get-a-pix-statement), [Get a Pix Statement CSV](#get-a-pix-statement-csv), [Get a Pix Statement Chunk](#get-a-pix-statement-chunk) - [Pix Director](#pix-director): [Create a Pix Director](#create-a-pix-director) - **Issuing** - [Issuing Balance](#issuing-balance): [Get the Issuing Balance](#get-the-issuing-balance) - [Issuing Product](#issuing-product): [List Issuing Products](#list-issuing-products) - [Issuing Holder](#issuing-holder): [Create Issuing Holders](#create-issuing-holders), [List Issuing Holders](#list-issuing-holders), [Get an Issuing Holder](#get-an-issuing-holder), [Update an Issuing Holder](#update-an-issuing-holder), [Cancel an Issuing Holder](#cancel-an-issuing-holder), [List Issuing Holder Logs](#list-issuing-holder-logs), [Get an Issuing Holder Log](#get-an-issuing-holder-log) - [Issuing Card](#issuing-card): [Create Issuing Cards](#create-issuing-cards), [List Issuing Cards](#list-issuing-cards), [Get an Issuing Card](#get-an-issuing-card), [Update an Issuing Card](#update-an-issuing-card), [Cancel an Issuing Card](#cancel-an-issuing-card), [List Issuing Card Logs](#list-issuing-card-logs), [Get an Issuing Card Log](#get-an-issuing-card-log) - [Issuing Design](#issuing-design): [List Issuing Designs](#list-issuing-designs), [Get an Issuing Design](#get-an-issuing-design), [Get an Issuing Design PDF](#get-an-issuing-design-pdf) - [Issuing Embossing Kit](#issuing-embossing-kit): [List Issuing Embossing Kits](#list-issuing-embossing-kits), [Get an Issuing Embossing Kit](#get-an-issuing-embossing-kit) - [Issuing Stock](#issuing-stock): [List Issuing Stocks](#list-issuing-stocks), [Get an Issuing Stock](#get-an-issuing-stock), [List Issuing Stock Logs](#list-issuing-stock-logs), [Get an Issuing Stock Log](#get-an-issuing-stock-log) - [Issuing Stock Rule](#issuing-stock-rule): [Create Issuing Stock Rules](#create-issuing-stock-rules), [List Issuing Stock Rules](#list-issuing-stock-rules), [Update an Issuing Stock Rule](#update-an-issuing-stock-rule), [Cancel an Issuing Stock Rule](#cancel-an-issuing-stock-rule) - [Issuing Restock](#issuing-restock): [Create Issuing Restocks](#create-issuing-restocks), [List Issuing Restocks](#list-issuing-restocks), [Get an Issuing Restock](#get-an-issuing-restock), [List Issuing Restock Logs](#list-issuing-restock-logs), [Get an Issuing Restock Log](#get-an-issuing-restock-log) - [Issuing Embossing Request](#issuing-embossing-request): [Create Issuing Embossing Requests](#create-issuing-embossing-requests), [List Issuing Embossing Requests](#list-issuing-embossing-requests), [Get an Issuing Embossing Request](#get-an-issuing-embossing-request), [List Issuing Embossing Request Logs](#list-issuing-embossing-request-logs), [Get an Issuing Embossing Request Log](#get-an-issuing-embossing-request-log) - [Issuing Token](#issuing-token): [List Issuing Tokens](#list-issuing-tokens), [Get an Issuing Token](#get-an-issuing-token), [Update an Issuing Token](#update-an-issuing-token), [Cancel an Issuing Token](#cancel-an-issuing-token), [List Issuing Token Logs](#list-issuing-token-logs), [Get an Issuing Token Log](#get-an-issuing-token-log) - [Issuing Token Request](#issuing-token-request): [Create an Issuing Token Request](#create-an-issuing-token-request) - [Issuing Token Design](#issuing-token-design): [List Issuing Token Designs](#list-issuing-token-designs), [Get an Issuing Token Design](#get-an-issuing-token-design), [Get an Issuing Token Design PDF](#get-an-issuing-token-design-pdf) - [Issuing Invoice](#issuing-invoice): [Create an Issuing Invoice](#create-an-issuing-invoice), [List Issuing Invoices](#list-issuing-invoices), [Get an Issuing Invoice](#get-an-issuing-invoice), [List Issuing Invoice Logs](#list-issuing-invoice-logs), [Get an Issuing Invoice Log](#get-an-issuing-invoice-log) - [Issuing Billing Invoice](#issuing-billing-invoice): [List Issuing Billing Invoices](#list-issuing-billing-invoices), [Get an Issuing Billing Invoice](#get-an-issuing-billing-invoice) - [Issuing Billing Transaction](#issuing-billing-transaction): [List Issuing Billing Transactions](#list-issuing-billing-transactions) - [Issuing Purchase](#issuing-purchase): [List Issuing Purchases](#list-issuing-purchases), [Get an Issuing Purchase](#get-an-issuing-purchase), [Update an Issuing Purchase](#update-an-issuing-purchase), [List Issuing Purchase Logs](#list-issuing-purchase-logs), [Get an Issuing Purchase Log](#get-an-issuing-purchase-log) - [Issuing Preview Installment](#issuing-preview-installment): [List Issuing Preview Installments](#list-issuing-preview-installments) - [Issuing Transaction](#issuing-transaction): [List Issuing Transactions](#list-issuing-transactions), [Get an Issuing Transaction](#get-an-issuing-transaction) - [Issuing Withdrawal](#issuing-withdrawal): [Create an Issuing Withdrawal](#create-an-issuing-withdrawal), [List Issuing Withdrawals](#list-issuing-withdrawals), [Get an Issuing Withdrawal](#get-an-issuing-withdrawal) - [Card Method](#card-method): [List Card Methods](#list-card-methods) - [Merchant Category](#merchant-category): [List Merchant Categories](#list-merchant-categories) - [Merchant Country](#merchant-country): [List Merchant Countries](#list-merchant-countries) - **Lending** - [Credit Note](#credit-note): [Create Credit Notes](#create-credit-notes), [List Credit Notes](#list-credit-notes), [Get a Credit Note](#get-a-credit-note), [Cancel a Credit Note](#cancel-a-credit-note), [Get a Credit Note PDF](#get-a-credit-note-pdf), [Get a Credit Note Payment PDF](#get-a-credit-note-payment-pdf), [List Credit Note Logs](#list-credit-note-logs), [Get a Credit Note Log](#get-a-credit-note-log) - [Credit Signer](#credit-signer): [Update a Credit Signer](#update-a-credit-signer) - [Credit Preview](#credit-preview): [Create Credit Previews](#create-credit-previews) - [Credit Holmes](#credit-holmes): [Create Credit Holmes](#create-credit-holmes), [List Credit Holmes](#list-credit-holmes), [Get a Credit Holmes](#get-a-credit-holmes), [List Credit Holmes Logs](#list-credit-holmes-logs), [Get a Credit Holmes Log](#get-a-credit-holmes-log) - **Ledger** - [Ledger](#ledger): [Create Ledgers](#create-ledgers), [List Ledgers](#list-ledgers), [Get a Ledger](#get-a-ledger), [Update a Ledger](#update-a-ledger), [List Ledger Logs](#list-ledger-logs), [Get a Ledger Log](#get-a-ledger-log) - [Ledger Transaction](#ledger-transaction): [Create Ledger Transactions](#create-ledger-transactions), [List Ledger Transactions](#list-ledger-transactions), [Get a Ledger Transaction](#get-a-ledger-transaction) - **AI** - [AI Agent](#ai-agent): [Create an AI Agent](#create-an-ai-agent), [List AI Agents](#list-ai-agents), [Get an AI Agent](#get-an-ai-agent), [Update an AI Agent](#update-an-ai-agent), [Delete AI Agents](#delete-ai-agents) - [AI Chat](#ai-chat): [Create an AI Chat](#create-an-ai-chat), [List AI Chats](#list-ai-chats), [Get an AI Chat](#get-an-ai-chat), [Update an AI Chat](#update-an-ai-chat), [Delete AI Chats](#delete-ai-chats) - [AI Message](#ai-message): [Send an AI Message](#send-an-ai-message), [List AI Messages](#list-ai-messages) - [AI Knowledge Base](#ai-knowledge-base): [Create an AI Knowledge Base](#create-an-ai-knowledge-base), [List AI Knowledge Bases](#list-ai-knowledge-bases), [Get an AI Knowledge Base](#get-an-ai-knowledge-base), [Update an AI Knowledge Base](#update-an-ai-knowledge-base), [List AI Knowledge Base Hosts](#list-ai-knowledge-base-hosts), [Delete AI Knowledge Bases](#delete-ai-knowledge-bases) - [AI Voice](#ai-voice): [Create an AI Voice](#create-an-ai-voice), [List AI Voices](#list-ai-voices), [Delete AI Voices](#delete-ai-voices) - [AI Speech](#ai-speech): [Create an AI Speech](#create-an-ai-speech), [List AI Speeches](#list-ai-speeches), [Get an AI Speech](#get-an-ai-speech) - [AI Transcript](#ai-transcript): [Create an AI Transcript](#create-an-ai-transcript), [List AI Transcripts](#list-ai-transcripts) - **Identity** - [Business Identity](#business-identity): [Create Business Identities](#create-business-identities), [List Business Identities](#list-business-identities), [Get a Business Identity](#get-a-business-identity), [Update a Business Identity](#update-a-business-identity), [Cancel a Business Identity](#cancel-a-business-identity), [List Business Identity Logs](#list-business-identity-logs), [Get a Business Identity Log](#get-a-business-identity-log) - [Business Attachment](#business-attachment): [Upload a Business Attachment](#upload-a-business-attachment), [List Business Attachments](#list-business-attachments), [Get a Business Attachment](#get-a-business-attachment), [Cancel a Business Attachment](#cancel-a-business-attachment), [List Business Attachment Logs](#list-business-attachment-logs), [Get a Business Attachment Log](#get-a-business-attachment-log) - [Individual Account Attachment](#individual-account-attachment): [Create an Individual Account Attachment](#create-an-individual-account-attachment), [List Individual Account Attachments](#list-individual-account-attachments), [Get an Individual Account Attachment](#get-an-individual-account-attachment), [Cancel an Individual Account Attachment](#cancel-an-individual-account-attachment), [List Individual Account Attachment Logs](#list-individual-account-attachment-logs), [Get an Individual Account Attachment Log](#get-an-individual-account-attachment-log) - [Individual Identity](#individual-identity): [Create Individual Identities](#create-individual-identities), [List Individual Identities](#list-individual-identities), [Get an Individual Identity](#get-an-individual-identity), [Update an Individual Identity](#update-an-individual-identity), [Cancel an Individual Identity](#cancel-an-individual-identity), [List Individual Identity Logs](#list-individual-identity-logs), [Get an Individual Identity Log](#get-an-individual-identity-log) - [Individual Identity Proof](#individual-identity-proof): [List Individual Identity Proofs](#list-individual-identity-proofs), [Get an Individual Identity Proof](#get-an-individual-identity-proof), [Submit an Individual Identity Proof](#submit-an-individual-identity-proof) - [Individual Account Request](#individual-account-request): [Create Individual Account Requests](#create-individual-account-requests), [List Individual Account Requests](#list-individual-account-requests), [Get an Individual Account Request](#get-an-individual-account-request), [Update an Individual Account Request](#update-an-individual-account-request), [List Individual Account Request Logs](#list-individual-account-request-logs), [Get an Individual Account Request Log](#get-an-individual-account-request-log) - [Business Account Request](#business-account-request): [Create Business Account Requests](#create-business-account-requests), [List Business Account Requests](#list-business-account-requests), [Get a Business Account Request](#get-a-business-account-request), [Update a Business Account Request](#update-a-business-account-request), [List Business Account Request Logs](#list-business-account-request-logs), [Get a Business Account Request Log](#get-a-business-account-request-log) - [Individual Holmes](#individual-holmes): [Query an Individual Bureau](#query-an-individual-bureau) - [Business Holmes](#business-holmes): [Query a Business Bureau](#query-a-business-bureau) - **Others** - [Webhook](#webhook): [Create a Webhook](#create-a-webhook), [List Webhooks](#list-webhooks), [Get a Webhook](#get-a-webhook), [Delete a Webhook](#delete-a-webhook) - [Event](#event): [List Events](#list-events), [Get an Event](#get-an-event), [Delete an Event](#delete-an-event), [Update an Event](#update-an-event) - [Event Attempt](#event-attempt): [List failed Webhook Event delivery attempts](#list-failed-webhook-event-delivery-attempts), [Get an Event Attempt](#get-an-event-attempt) ## Tech Support If you have any questions about our API or [SDKs](https://github.com/starkinfra?q=sdk), feel free to email us. We will respond to you quickly, pinky promise. We are here to help you integrate with us ASAP. We also love feedback, so don't be shy about sharing your thoughts with us. **CONTACT US** help@starkinfra.com ## Testing in Sandbox In order to send any request to Stark Infra, you first need to create a digital account with us. We call our accounts workspaces. Feel free to test our services in Sandbox by creating your workspace here (no need to contact us): [Create a Workspace in Sandbox](https://web.sandbox.starkinfra.com) Your initial balance is zero. You can add balance by creating Pix Requests, as they will be processed automatically in the Sandbox environment within a few minutes. **BASE URL - Sandbox** https://sandbox.api.starkinfra.com ## Moving to Production Sandbox and Production share the same code but are isolated from each other as they are running on separate servers and access different databases. Switching to Production requires you to change the base url and the credentials only. The [SDKs](https://github.com/starkinfra?q=sdk) select the base url according to the environment you choose. **Note 1:** Since we will be talking about real money here, we strongly recommend integrating in Sandbox first. **Note 2:** The response times are different in each environment as we emulate the results in Sandbox, while in Production we depend on other financial institutions to operate. You can request an account in Production here: [Create a Workspace in Production](https://web.starkinfra.com/signup/email) **BASE URL - Production** https://api.starkinfra.com ## Versioning We avoid breaking changes at all costs and we won't let your application stop working because of a change we made. We are always adding features and making improvements to our API, but whenever we make a significant change to an endpoint, we will launch a new API version. Also, whenever the API is upgraded, we will add a new log to our changelog. We consider the following changes to be backward-compatible: Adding new API resources; Adding new optional request parameters; Making a mandatory request parameter optional; Adding new properties to existing API responses; Changing the order of properties in existing API responses; Adding new events to webhooks (that means your webhook listener should gracefully handle unfamiliar event types). **Current API Version** v2 ## Authentication At Stark Infra, we do not use static API keys or access tokens. Instead, all API requests are authenticated using [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) digital signatures with the [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) curve and [SHA-256](https://en.bitcoin.it/wiki/SHA-256) digest. Each request is signed locally on your server using your private key, which is never transmitted. The signature is sent with the request, and we verify it using your registered public key. Our [SDKs](https://github.com/starkbank?q=sdk) automatically handle request signing. **Credential Types:** **Projects:** Bound to a specific Workspace, recommended for most integrations, and only a workspace admin can register. **Organizations:** Bound to your company’s Tax ID, can manage multiple Workspaces, and only a legal representative can register. **Setup:** 1. Generate a private and public keys, [learn how](https://docs.starkinfra.com/how-to-create-ecdsa-keys.md). 2. Upload your public key in our Web Banking (Sandbox or Production). 3. Configure your SDK with your Project ID or Organization ID and your private key. **Security:** 1. Keep your private key secure at all times. Never share it with anyone — including Stark Infra — and never hard-code it in your source code. Store it in a [Hardware Security Module (HSM)](https://en.wikipedia.org/wiki/Hardware_security_module) whenever possible. Otherwise, keep it encrypted, such as in an environment variable or secure database. 2. Restrict API access by configuring an [IP allowlist](https://docs.starkinfra.com/ip-allowlisting.md) for your credential. **Example** ```python import starkbank # Example key only — replace with your own. # Never hardcode private keys in source. Store them in an HSM, # or at minimum in an encrypted KMS. private_key_content = """ -----BEGIN EC PARAMETERS----- BgUrgQQACg== -----END EC PARAMETERS----- -----BEGIN EC PRIVATE KEY----- MHQCAQEEIMCwW74H6egQkTiz87WDvLNm7fK/cA+ctA2vg/bbHx3woAcGBSuBBAAK oUQDQgAE0iaeEHEgr3oTbCfh8U2L+r7zoaeOX964xaAnND5jATGpD/tHec6Oe9U1 IF16ZoTVt1FzZ8WkYQ3XomRD4HS13A== -----END EC PRIVATE KEY----- """ # for project users: user = starkbank.Project( environment="sandbox", id="5656565656565656", private_key=private_key_content ) # or, for organization users: user = starkbank.Organization( environment="sandbox", id="4545454545454545", private_key=private_key_content ) starkbank.user = user ``` ### Do it yourself Just in case you are unable to use our [SDKs](https://github.com/starkbank?q=sdk), in every request we pass three custom headers: Access-Id, Access-Time, and Access-Signature. Here is a pseudo-code explaining how to make authenticated requests: ``` # Set your user Id accessId = "project/12345" accessId = "organization/12345" accessId = "organization/12345/workspace/67890" # Get current Unix Time accessTime = 1584041509 # Get you json content in string format for POST/PUT/PATCH requests # or empty string for GET/DELETE requests. bodyString = "" # Build the message in this format: message = accessId + ":" + accessTime + ":" + bodyString # Load your private key from its pem string privateKey = PrivateKey.fromPem(...) # Use ECDSA to sign the message signature = ECDSA.sign(message, privateKey) # Convert the signature to base 64 accessSignature = signature.toBase64() # You are now ready to send the request request = Request.get( url="https://sandbox.api.starkinfra.com/v2/transfer", body=bodyString, headers={ "Access-Id" : accessId, "Access-Time" : accessTime, "Access-Signature": accessSignature } ) ``` Feeling adventurous? Check out our [Digital Signature libraries](https://github.com/starkbank?q=ecdsa). **CUSTOM HEADERS** | Header | Description | | --- | --- | | Access-Id | Static string that identifies the user: project/{projectId} for projects; organization/{organizationId} for organizations; organization/{organizationId}/workspace/{workspaceId} for organizations operating inside a Workspace. | | Access-Time | Current Unix-Time: the number of seconds since 1 January 1970. | | Access-Signature | Base64-encoded ECDSA signature of Access-Id + ":" + Access-Time + ":" + body, where body is the JSON string for POST/PUT/PATCH requests and an empty string for GET/DELETE requests. | **Access-Id Example** project/12345 **Access-Time Example** 1584041509 **Access-Signature Example** MEYCIQC5wiR/fEmwJHscoQ1a4gn9w/qiYQlr8qsdo95MsfgFNwIhAIi4jJ3bzhg+6QEu8g5qK0SNSzIi9JwRuDuP2NZYpLP3 ## Static IP list To ensure the integrity and safety of our requests to your services, we recommend adding our static IP addresses to your firewall ingress rules. The following IP addresses are currently being used: **Production** ** - 35.199.76.124** ** - 34.85.188.162** ** - 34.39.190.119** **Sandbox** ** - 35.247.226.240** ** - 35.245.182.229** ** - 35.247.194.253** ## Errors We like standards. Unfortunately, not all of our possible errors could fit in the HTTP status standard. Since we believe numbers are not descriptive enough, we prefer to use strings as error codes. In order to be compatible with request libraries, though, we use the HTTP status in the summary below. **HTTP STATUS CODE SUMMARY** | Status | Description | | --- | --- | | 200 | Everything went right | | 400 | Your input is incorrect. We will send you a json explaining what went wrong. | | 500 | Something went wrong on our side. Our engineering team will be notified and act to fix the problem ASAP. | **ERROR SAMPLE** ``` { "errors": [ { "code": "invalidEmail", "message": "Your email address should look like “person@domain.com”." }, { "code": "invalidName", "message": "Your name must have at least 6 characters." } ] } ``` ## Supported Languages Our API returns messages in two different languages: **US English** (default language) and **Brazilian Portuguese**. To select one of them, just add the optional header key Accept-Language to your request with "en-US" or "pt-BR" as value. If you use anything else, messages will be returned in English. **Accept-Language Header** | Code | Language | | --- | --- | | en-US | US English (default) | | pt-BR | Brazilian Portuguese | ## Pagination List endpoints return at most **100** objects per call, together with a `cursor` string. To fetch the next batch, repeat the same request with the cursor in the query string (`?cursor=...`), keeping every other filter unchanged. The cursor comes back as **null** when there are no more results. Cursors are opaque: do not parse, build or compare them, and do not rely on integer offsets. Use `limit` to ask for smaller batches (up to 100). Our [SDKs](https://github.com/starkinfra?q=sdk) expose two ways to list: `query`, a generator that walks through every page for you, and `page`, which returns one batch plus the next cursor so you can stop and resume whenever it is convenient. The example uses `page`; the last call shows how to send the cursor over plain HTTP. **Example** ```python import starkinfra cursor = None while True: requests, cursor = starkinfra.pixrequest.page(limit=50, cursor=cursor) for request in requests: print(request) if cursor is None: break ``` ## Date & Time All dates returned by our API will be in UTC ISO format. That means no matter where you are, you will always receive UTC times and should handle conversions to local time on your end whenever needed. **Example** 2018-12-29T18:27:12.343531+00:00 # Pix ## Pix Request A Pix Request represents an inbound or outbound Pix payment in the Brazilian instant payment system. Here we will show you how to create and manage them. ### The Pix Request Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix request. | | `amount` | INTEGER | Amount in cents to be transferred. Example: 100 (R$1.00). | | `endToEndId` | STRING | Unique end-to-end ID assigned by the Pix system. | | `fee` | INTEGER | Fee charged in cents for this Pix request. | | `flow` | STRING | Direction of the Pix request. Options: "in" (received), "out" (sent). | | `method` | STRING | Method through which this Pix was processed. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". | | `externalId` | STRING | Unique external ID to prevent duplicates. | | `initiatorTaxId` | STRING | Tax ID of the payment initiator. | | `receiverBankCode` | STRING | Bank ISPB code of the receiver. | | `receiverBranchCode` | STRING | Branch code of the receiver's bank account. | | `receiverAccountNumber` | STRING | Account number of the receiver. | | `receiverAccountType` | STRING | Account type of the receiver. Options: "checking", "savings", "salary", "payment". | | `receiverName` | STRING | Full name of the receiver. | | `receiverTaxId` | STRING | CPF or CNPJ of the receiver. | | `senderBankCode` | STRING | Bank ISPB code of the sender. | | `senderBranchCode` | STRING | Branch code of the sender's bank account. | | `senderAccountNumber` | STRING | Account number of the sender. | | `senderAccountType` | STRING | Account type of the sender. Options: "checking", "savings", "salary", "payment". | | `senderName` | STRING | Full name of the sender. | | `senderTaxId` | STRING | CPF or CNPJ of the sender. | | `status` | STRING | Current status. Options: "created", "processing", "success", "failed". | | `tags` | LIST OF STRINGS | Tags associated with the Pix request. | | `description` | STRING | Description of the Pix request. | | `reconciliationId` | STRING | Reconciliation ID for the Pix request. | | `cashAmount` | INTEGER | Amount in cents to be withdrawal when paying. Example: 1000 (R$10.00). | | `cashierType` | STRING | Cashier's type for Pix Cash-out and Pix Change. Options: "merchant", "participant", "other". | | `cashierBankCode` | STRING | Cashier's bank ISPB code for Pix Cash-out and Pix Change. | | `priority` | STRING | Pix request processing priority. Options: "high", "low". | | `reason` | STRING | Reason why this Pix request was created. Options: "customerRequest", "subscriptionFlaw", "fraud". | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Requests `POST /v2/pix-request` Send Pix payments to any Pix-enabled bank account in Brazil. To create a manual Pix Request you need the receiver's account information. If you only have a [Pix Key](#pix-key), use Get a Pix Key to retrieve the required information before creating the Pix Request. Every time a participant sends you a Pix, an inbound Pix Request is created and a synchronous POST authorization request is sent to your registered pixRequestUrl, which you must answer with approval or denial within 1 second (HTTP 200) or it is denied by default. Approve with status "approved"; deny with status "denied" and a reason such as "invalidAccountNumber". You can create up to 100 Pix requests in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `amount` | REQUIRED | Amount in cents to be transferred. Example: 100 (R$1.00). | | `externalId` | REQUIRED | Unique string to prevent duplicates. Repeated externalIds will cause failures. By default, this parameter also blocks any Pix Request that repeats amount and receiver information on the same date. | | `endToEndId` | REQUIRED | Unique end-to-end ID generated for the Pix request. | | `senderAccountNumber` | REQUIRED | Account number of the sender. | | `senderBranchCode` | REQUIRED | Branch code of the sender's bank account. | | `senderAccountType` | REQUIRED | Account type of the sender. Options: "checking", "savings", "salary", "payment". | | `senderName` | REQUIRED | Full name of the sender. | | `senderTaxId` | REQUIRED | CPF or CNPJ of the sender. | | `receiverAccountNumber` | REQUIRED | Account number of the receiver. | | `receiverAccountType` | REQUIRED | Account type of the receiver. Options: "checking", "savings", "salary", "payment". | | `receiverBankCode` | REQUIRED | Bank ISPB code of the receiver. | | `receiverTaxId` | REQUIRED | CPF or CNPJ of the receiver. | | `receiverBranchCode` | OPTIONAL | Branch code of the receiver's bank account. | | `receiverName` | OPTIONAL | Full name of the receiver. | | `description` | OPTIONAL | Description of the Pix request. | | `initiatorTaxId` | OPTIONAL | Tax ID of the payment initiator. | | `reconciliationId` | OPTIONAL | Reconciliation ID for internal reference. | | `method` | OPTIONAL | Method through which this Pix should be processed. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". | | `cashAmount` | OPTIONAL | Amount in cents to be withdrawal when paying. Example: 1000 (R$10.00). | | `cashierType` | OPTIONAL | Cashier's type for Pix Cash-out and Pix Change. Options: "merchant", "participant", "other". | | `cashierBankCode` | OPTIONAL | Cashier's bank ISPB code for Pix Cash-out and Pix Change. | | `priority` | OPTIONAL | Pix request processing priority, which selects the message channel used to send it: "high" uses the primary channel and "low" the secondary one. Default is "high". Options: "high", "low". | | `reason` | OPTIONAL | Reason why this Pix request was created. Default is "customerRequest". Options: "customerRequest", "subscriptionFlaw", "fraud". | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra requests = starkinfra.pixrequest.create([ starkinfra.PixRequest( amount=1000, external_id="my-external-id-1", end_to_end_id="E20018183202201011000r01", sender_account_number="00000-0", sender_branch_code="0001", sender_account_type="checking", sender_name="Arya Stark", sender_tax_id="012.345.678-90", receiver_account_number="10000-0", receiver_account_type="checking", receiver_bank_code="20018183", receiver_tax_id="98.765.432/0001-10", receiver_branch_code="0001", receiver_name="Jon Snow", tags=["transfer", "pix"] ) ]) for request in requests: print(request) ``` **Response** ```python [ PixRequest( id="5656565656565656", amount=1000, end_to_end_id="E20018183202201011000r01", fee=0, flow="out", method="manual", external_id="my-external-id-1", initiator_tax_id="", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_name="Jon Snow", receiver_tax_id="98.765.432/0001-10", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_name="Arya Stark", sender_tax_id="012.345.678-90", status="created", tags=["transfer", "pix"], description="", reconciliation_id="", cash_amount=0, cashier_type="", cashier_bank_code="", priority="high", reason="customerRequest", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Requests `GET /v2/pix-request` List and filter all Pix requests. Results are paged. Every time a participant sends you a Pix, an inbound Pix Request is created and a synchronous POST authorization request is sent to your registered pixRequestUrl, which you must answer with approval or denial within 1 second (HTTP 200) or it is denied by default. Approve with status "approved"; deny with status "denied" and a reason such as "invalidAccountNumber". **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `endToEndIds` | OPTIONAL | Filter by end-to-end IDs. | | `externalIds` | OPTIONAL | Filter by external IDs. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | **Request** ```python import starkinfra requests = starkinfra.pixrequest.query( limit=10, after="2022-01-01", before="2022-12-31", status=["success"], tags=["pix"] ) for request in requests: print(request) ``` **Response** ```python PixRequest( id="5656565656565656", amount=1000, end_to_end_id="E20018183202201011000r01", fee=0, flow="out", method="manual", status="success", tags=["pix"], priority="high", reason="customerRequest", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Pix Request `GET /v2/pix-request/:id` Get a single Pix request by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix request entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra request = starkinfra.pixrequest.get("5656565656565656") print(request) ``` **Response** ```python PixRequest( id="5656565656565656", amount=1000, end_to_end_id="E20018183202201011000r01", fee=0, flow="out", method="manual", external_id="my-external-id-1", initiator_tax_id="", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_name="Jon Snow", receiver_tax_id="98.765.432/0001-10", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_name="Arya Stark", sender_tax_id="012.345.678-90", status="success", tags=["pix"], description="", reconciliation_id="", cash_amount=0, cashier_type="", cashier_bank_code="", priority="high", reason="customerRequest", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Request Logs `GET /v2/pix-request/log` Get a paged list of all Pix request logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `requestIds` | OPTIONAL | Array of Pix request ids linked to the logs. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixrequest.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["success"], request_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", type="success", errors=[], request=PixRequest( id="5656565656565656", amount=1000, end_to_end_id="E20018183202201011000r01", fee=0, flow="out", method="manual", external_id="my-external-id-1", initiator_tax_id="", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_name="Jon Snow", receiver_tax_id="98.765.432/0001-10", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_name="Arya Stark", sender_tax_id="012.345.678-90", status="success", tags=["pix"], description="", reconciliation_id="", cash_amount=0, cashier_type="", cashier_bank_code="", priority="high", reason="customerRequest", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Request Log `GET /v2/pix-request/log/:id` Get a single Pix request log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.pixrequest.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", type="success", errors=[], request=PixRequest( id="5656565656565656", amount=1000, end_to_end_id="E20018183202201011000r01", fee=0, flow="out", method="manual", external_id="my-external-id-1", initiator_tax_id="", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_name="Jon Snow", receiver_tax_id="98.765.432/0001-10", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_name="Arya Stark", sender_tax_id="012.345.678-90", status="success", tags=["pix"], description="", reconciliation_id="", cash_amount=0, cashier_type="", cashier_bank_code="", priority="high", reason="customerRequest", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ## Pix Reversal A Pix Reversal allows you to reverse a previously made Pix transfer, sending the funds back to the original sender. Here we will show you how to create and manage them. ### The Pix Reversal Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix reversal. | | `amount` | INTEGER | Amount in cents to be reversed. | | `externalId` | STRING | Unique external ID to prevent duplicates. | | `endToEndId` | STRING | End-to-end ID of the original Pix request to be reversed. | | `returnId` | STRING | Central Bank return ID generated for the Pix reversal. | | `reason` | STRING | Reason for the reversal. Options: "fraud", "bankError", "cashierError", "customerRequest". | | `status` | STRING | Current status. Options: "created", "processing", "success", "failed". | | `tags` | LIST OF STRINGS | Tags associated with the Pix reversal. | | `fee` | INTEGER | Fee charged in cents for this reversal. | | `flow` | STRING | Direction of the reversal. Options: "in" (received), "out" (sent). | | `description` | STRING | Description of the reversal. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Reversals `POST /v2/pix-reversal` Reverse a Pix payment by providing the original end-to-end ID. Pix Reversals can only be created for inbound [Pix Requests](#pix-request) with status success. Reference the original Pix Request by passing its endToEndId. When a participant reverses a Pix you successfully sent, an authorization request is sent to your pixReversalUrl (which must differ from your pixRequestUrl); answer within 1 second (HTTP 200) or it is denied by default; if no pixReversalUrl is registered, inbound Pix Reversals are accepted by default. You can create up to 100 reversals in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `amount` | REQUIRED | Amount in cents to be reversed. | | `endToEndId` | REQUIRED | End-to-end ID of the original Pix request to be reversed. | | `externalId` | REQUIRED | Unique string to prevent duplicates. By default, this parameter also blocks any Pix Reversal that repeats amount and receiver information on the same date. | | `reason` | REQUIRED | Reason for the reversal. Options: "fraud", "bankError", "cashierError", "customerRequest". | | `description` | OPTIONAL | Description of the reversal. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra reversals = starkinfra.pixreversal.create([ starkinfra.PixReversal( amount=1000, external_id="my-reversal-id-1", end_to_end_id="E20018183202201060100rq1feOMJqtZ", reason="fraud", description="reversing a fraudulent transfer", tags=["reversal", "pix"] ) ]) for reversal in reversals: print(reversal) ``` **Response** ```python [ PixReversal( id="5656565656565656", amount=1000, external_id="my-reversal-id-1", end_to_end_id="E20018183202201060100rq1feOMJqtZ", return_id="D20018183202202030109X3OoBHG74wo", reason="fraud", status="created", flow="out", fee=0, description="reversing a fraudulent transfer", tags=["reversal", "pix"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Reversals `GET /v2/pix-reversal` List and filter all Pix reversals. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `externalIds` | OPTIONAL | Filter by external IDs. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | **Request** ```python import starkinfra reversals = starkinfra.pixreversal.query( limit=10, after="2022-01-01", before="2022-12-31", status=["success"], external_ids=["my-reversal-id-1"], tags=["pix"] ) for reversal in reversals: print(reversal) ``` **Response** ```python PixReversal( id="5656565656565656", amount=1000, external_id="my-reversal-id-1", end_to_end_id="E20018183202201060100rq1feOMJqtZ", return_id="D20018183202202030109X3OoBHG74wo", reason="fraud", status="success", flow="out", fee=0, description="reversing a fraudulent transfer", tags=["pix"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Pix Reversal `GET /v2/pix-reversal/:id` Get a single Pix reversal by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix reversal entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra reversal = starkinfra.pixreversal.get("5656565656565656") print(reversal) ``` **Response** ```python PixReversal( id="5656565656565656", amount=1000, external_id="my-reversal-id-1", end_to_end_id="E20018183202201060100rq1feOMJqtZ", return_id="D20018183202202030109X3OoBHG74wo", reason="fraud", status="success", flow="out", fee=0, description="reversing a fraudulent transfer", tags=["pix"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Reversal Logs `GET /v2/pix-reversal/log` Get a paged list of all Pix reversal logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `reversalIds` | OPTIONAL | Array of Pix reversal ids linked to the logs. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixreversal.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["success"], reversal_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", type="success", reversal=PixReversal( id="5656565656565656", amount=1000, external_id="my-reversal-id-1", end_to_end_id="E20018183202201060100rq1feOMJqtZ", return_id="D20018183202202030109X3OoBHG74wo", reason="fraud", status="success", flow="out", fee=0, description="reversing a fraudulent transfer", tags=["pix"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Reversal Log `GET /v2/pix-reversal/log/:id` Get a single Pix reversal log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.pixreversal.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", type="success", reversal=PixReversal( id="5656565656565656", amount=1000, external_id="my-reversal-id-1", end_to_end_id="E20018183202201060100rq1feOMJqtZ", return_id="D20018183202202030109X3OoBHG74wo", reason="fraud", status="success", flow="out", fee=0, description="reversing a fraudulent transfer", tags=["pix"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ## Pix Internal Transaction Report A Pix Internal Transaction Report lets Direct and Indirect participants report transactions that were settled internally on the participant, such as transfers between two Indirect participants of the same Direct participant or between accounts of the same participant. Here we will show you how to create and manage them. ### The Pix Internal Transaction Report Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix internal transaction report. | | `referenceType` | STRING | Origin of the report's reference id. Options: "request" (derived from endToEndId), "reversal" (derived from returnId). | | `amount` | INTEGER | Transaction amount in cents. Example: 100 (R$1.00). | | `endToEndId` | STRING | End-to-end id of the reported Pix transaction. | | `returnId` | STRING | Return id of the reported transaction. Present when referenceType is "reversal". | | `method` | STRING | Type of the reported transaction. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". | | `senderBankCode` | STRING | Bank ISPB code of the sender. | | `senderBranchCode` | STRING | Branch code of the sender's bank account. | | `senderAccountNumber` | STRING | Account number of the sender. | | `senderAccountType` | STRING | Account type of the sender. Options: "checking", "savings", "salary", "payment", "other". | | `senderTaxId` | STRING | CPF or CNPJ of the sender. | | `receiverBankCode` | STRING | Bank ISPB code of the receiver. | | `receiverBranchCode` | STRING | Branch code of the receiver's bank account. | | `receiverAccountNumber` | STRING | Account number of the receiver. | | `receiverAccountType` | STRING | Account type of the receiver. Options: "checking", "savings", "salary", "payment", "other". | | `receiverTaxId` | STRING | CPF or CNPJ of the receiver. | | `receiverKeyId` | STRING | Pix key of the receiver, when the transaction used one. | | `status` | STRING | Current status of the report. Options: "created", "processing", "success", "failed". | | `created` | STRING | Datetime of the original transaction, supplied at creation. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Internal Transaction Reports `POST /v2/pix-internal-transaction-report` Report transactions that were settled internally on the participant, such as transfers between two Indirect participants of the same Direct participant or between accounts of the same participant. You can create up to 100 reports in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `referenceType` | REQUIRED | Origin of the report's reference id. Options: "request" (use with endToEndId), "reversal" (use with returnId). | | `amount` | REQUIRED | Transaction amount in cents. Example: 100 (R$1.00). | | `endToEndId` | REQUIRED | End-to-end id of the reported Pix transaction. | | `method` | REQUIRED | Type of the reported transaction. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". | | `created` | REQUIRED | Datetime of the original transaction. | | `senderBankCode` | REQUIRED | Bank ISPB code of the sender. | | `senderBranchCode` | REQUIRED | Branch code of the sender's bank account. | | `senderAccountNumber` | REQUIRED | Account number of the sender. | | `senderAccountType` | REQUIRED | Account type of the sender. Options: "checking", "savings", "salary", "payment", "other". | | `senderTaxId` | REQUIRED | CPF or CNPJ of the sender. | | `receiverBankCode` | REQUIRED | Bank ISPB code of the receiver. | | `receiverBranchCode` | REQUIRED | Branch code of the receiver's bank account. | | `receiverAccountNumber` | REQUIRED | Account number of the receiver. | | `receiverAccountType` | REQUIRED | Account type of the receiver. Options: "checking", "savings", "salary", "payment", "other". | | `receiverTaxId` | REQUIRED | CPF or CNPJ of the receiver. | | `returnId` | OPTIONAL | Return id of the reported transaction. Required when referenceType is "reversal". | | `receiverKeyId` | OPTIONAL | Pix key of the receiver, when the transaction used one. | **Request** ```python import starkinfra reports = starkinfra.pixinternaltransactionreport.create([ starkinfra.PixInternalTransactionReport( reference_type="request", amount=1000, end_to_end_id="E20018183202201011000r01", method="manual", created="2022-01-01T00:00:00+00:00", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_tax_id="012.345.678-90", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_tax_id="20.018.183/0001-80", receiver_key_id="20.018.183/0001-80" ) ]) for report in reports: print(report) ``` **Response** ```python [ PixInternalTransactionReport( id="5656565656565656", reference_type="request", amount=1000, end_to_end_id="E20018183202201011000r01", return_id="", method="manual", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_tax_id="012.345.678-90", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_tax_id="20.018.183/0001-80", receiver_key_id="20.018.183/0001-80", status="created", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Internal Transaction Reports `GET /v2/pix-internal-transaction-report` List and filter all Pix internal transaction reports. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | List of ids to get specific entities. Max = 100. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. Options: "created", "processing", "success", "failed". | | `referenceIds` | OPTIONAL | Filter by reference ids (endToEndId or returnId). Max = 30. | | `referenceTypes` | OPTIONAL | Filter by reference types. Options: "request", "reversal". Max = 30. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra reports = starkinfra.pixinternaltransactionreport.query( limit=10, after="2022-01-01", before="2022-12-31", status=["success"], ids=["5656565656565656"] ) for report in reports: print(report) ``` **Response** ```python PixInternalTransactionReport( id="5656565656565656", reference_type="request", amount=1000, end_to_end_id="E20018183202201011000r01", method="manual", status="success", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Pix Internal Transaction Report `GET /v2/pix-internal-transaction-report/:id` Get a single Pix internal transaction report by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix internal transaction report entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra report = starkinfra.pixinternaltransactionreport.get("5656565656565656") print(report) ``` **Response** ```python PixInternalTransactionReport( id="5656565656565656", reference_type="request", amount=1000, end_to_end_id="E20018183202201011000r01", return_id="", method="manual", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_tax_id="012.345.678-90", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_tax_id="20.018.183/0001-80", receiver_key_id="20.018.183/0001-80", status="success", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Internal Transaction Report Logs `GET /v2/pix-internal-transaction-report/log` Get a paged list of all Pix internal transaction report logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | Filter by log ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log types. Options: "created", "sent", "success", "failed". | | `reportIds` | OPTIONAL | Filter logs by Pix internal transaction report ids. | **Request** ```python import starkinfra logs = starkinfra.pixinternaltransactionreport.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["success"], report_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", type="success", errors=[], report=PixInternalTransactionReport( id="5656565656565656", reference_type="request", amount=1000, end_to_end_id="E20018183202201011000r01", return_id="", method="manual", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_tax_id="012.345.678-90", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_tax_id="20.018.183/0001-80", receiver_key_id="20.018.183/0001-80", status="success", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Internal Transaction Report Log `GET /v2/pix-internal-transaction-report/log/:id` Get a single Pix internal transaction report log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixinternaltransactionreport.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", type="success", errors=[], report=PixInternalTransactionReport( id="5656565656565656", reference_type="request", amount=1000, end_to_end_id="E20018183202201011000r01", return_id="", method="manual", sender_bank_code="34052649", sender_branch_code="0001", sender_account_number="00000-0", sender_account_type="checking", sender_tax_id="012.345.678-90", receiver_bank_code="20018183", receiver_branch_code="0001", receiver_account_number="10000-0", receiver_account_type="checking", receiver_tax_id="20.018.183/0001-80", receiver_key_id="20.018.183/0001-80", status="success", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ## Static Brcode A Static Brcode is a QR Code that can receive multiple Pix payments with a fixed or open amount. Here we will show you how to create and manage them. ### The Static Brcode Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the static Brcode. | | `name` | STRING | Receiver name displayed in the QR code. | | `keyId` | STRING | Pix key to which payments will be directed. | | `city` | STRING | City of the receiver. | | `amount` | INTEGER | Fixed amount in cents. Leave empty for open amount QR codes. | | `reconciliationId` | STRING | Reconciliation ID included in the QR code. | | `cashierBankCode` | STRING | Bank ISPB code of the cashier for Pix Saque/Troco operations. | | `type` | STRING | Type of the static Brcode. Options: "instant", "instantAndOrSubscription". | | `description` | STRING | Description of the static Brcode. | | `tags` | LIST OF STRINGS | Tags associated with the static Brcode. | | `uuid` | STRING | Unique UUID used to identify this QR code. | | `url` | STRING | URL for the QR code image. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Static Brcodes `POST /v2/static-brcode` Create static Pix QR codes for receiving payments. You can create up to 100 static Brcodes in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `keyId` | REQUIRED | Pix key to which payments will be directed. | | `name` | REQUIRED | Receiver name displayed in the QR code. | | `city` | REQUIRED | City of the receiver. | | `amount` | OPTIONAL | Fixed amount in cents. Leave empty for open amount QR codes. | | `cashierBankCode` | OPTIONAL | Bank ISPB code of the cashier for Pix Saque/Troco operations. | | `type` | OPTIONAL | Type of the static Brcode. Options: "instant", "instantAndOrSubscription". Defaults to "instant". | | `description` | OPTIONAL | Description of the static Brcode. | | `reconciliationId` | OPTIONAL | Reconciliation ID included in the QR code. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra brcodes = starkinfra.staticbrcode.create([ starkinfra.StaticBrcode( name="Jon Snow", key_id="+5511989898989", city="São Paulo", amount=1000, cashier_bank_code="20018183", type="instant", reconciliation_id="my-reconciliation-id", description="Payment for services", tags=["invoice", "payment"] ) ]) for brcode in brcodes: print(brcode) ``` **Response** ```python [ StaticBrcode( id="5656565656565656", name="Jon Snow", key_id="+5511989898989", city="São Paulo", amount=1000, reconciliation_id="my-reconciliation-id", cashier_bank_code="20018183", type="instant", description="Payment for services", tags=["invoice", "payment"], uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890", url="https://brcode.starkinfra.com/static-qrcode/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Static Brcodes `GET /v2/static-brcode` List and filter all static Brcodes. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `uuids` | OPTIONAL | Filter by UUIDs. | **Request** ```python import starkinfra brcodes = starkinfra.staticbrcode.query( limit=10, after="2022-01-01", before="2022-12-31", uuids=["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], tags=["invoice"] ) for brcode in brcodes: print(brcode) ``` **Response** ```python StaticBrcode( id="5656565656565656", name="Jon Snow", key_id="+5511989898989", city="São Paulo", amount=1000, reconciliation_id="my-reconciliation-id", cashier_bank_code="20018183", type="instant", description="Payment for services", tags=["invoice"], uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890", url="https://brcode.starkinfra.com/static-qrcode/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Static Brcode `GET /v2/static-brcode/:uuid` Get a single static Brcode by its UUID. **Parameters** | Name | Required | Description | | --- | --- | --- | | `uuid` | REQUIRED | UUID of the static Brcode. | **Request** ```python import starkinfra brcode = starkinfra.staticbrcode.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(brcode) ``` **Response** ```python StaticBrcode( id="5656565656565656", name="Jon Snow", key_id="+5511989898989", city="São Paulo", amount=1000, reconciliation_id="my-reconciliation-id", cashier_bank_code="20018183", type="instant", description="Payment for services", tags=["invoice", "payment"], uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890", url="https://brcode.starkinfra.com/static-qrcode/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ## Dynamic Brcode A Dynamic Brcode is a QR Code that returns payment details dynamically from your server when scanned. The "subscription", "subscriptionAndInstant" and "dueAndOrSubscription" types let a Dynamic Brcode initiate a Pix Automático recurring authorization. Here we will show you how to create and manage them. ### The Dynamic Brcode Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the dynamic Brcode. | | `name` | STRING | Receiver name displayed in the QR code. | | `city` | STRING | City of the receiver. | | `externalId` | STRING | Your internal ID for this Brcode, used to prevent duplicates. | | `type` | STRING | Type of dynamic Brcode. Options: "instant", "due", "subscription", "subscriptionAndInstant", "dueAndOrSubscription". | | `tags` | LIST OF STRINGS | Tags associated with the dynamic Brcode. | | `uuid` | STRING | Unique UUID used to identify this QR code. | | `url` | STRING | URL for the QR code image. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Dynamic Brcodes `POST /v2/dynamic-brcode` Create dynamic Pix QR codes that fetch payment details from your server. You can create up to 100 dynamic Brcodes in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `city` | REQUIRED | City of the receiver. | | `externalId` | REQUIRED | Your internal ID used to match payment callbacks and to prevent duplicates. | | `name` | REQUIRED | Receiver name displayed in the QR code. | | `type` | OPTIONAL | Type of dynamic Brcode. Options: "instant", "due", "subscription", "subscriptionAndInstant", "dueAndOrSubscription". Defaults to "instant" when omitted. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra brcodes = starkinfra.dynamicbrcode.create([ starkinfra.DynamicBrcode( name="Jon Snow", city="São Paulo", external_id="my-dynamic-brcode-id-1", type="subscription", tags=["dynamic", "subscription"] ) ]) for brcode in brcodes: print(brcode) ``` **Response** ```python [ DynamicBrcode( id="5656565656565656", name="Jon Snow", city="São Paulo", external_id="my-dynamic-brcode-id-1", type="subscription", tags=["dynamic", "subscription"], uuid="b2c3d4e5-f6a7-8901-bcde-f12345678901", url="https://brcode.starkinfra.com/dynamic-qrcode/b2c3d4e5-f6a7-8901-bcde-f12345678901.png", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Dynamic Brcodes `GET /v2/dynamic-brcode` List and filter all dynamic Brcodes. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `externalIds` | OPTIONAL | Filter by external IDs. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `uuids` | OPTIONAL | Filter by UUIDs. | **Request** ```python import starkinfra brcodes = starkinfra.dynamicbrcode.query( limit=10, after="2022-01-01", before="2022-12-31", tags=["dynamic"] ) for brcode in brcodes: print(brcode) ``` **Response** ```python DynamicBrcode( id="5656565656565656", name="Jon Snow", city="São Paulo", external_id="my-dynamic-brcode-id-1", type="instant", tags=["dynamic"], uuid="b2c3d4e5-f6a7-8901-bcde-f12345678901", url="https://brcode.starkinfra.com/dynamic-qrcode/b2c3d4e5-f6a7-8901-bcde-f12345678901.png", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Dynamic Brcode `GET /v2/dynamic-brcode/:uuid` Get a single dynamic Brcode by its UUID. **Parameters** | Name | Required | Description | | --- | --- | --- | | `uuid` | REQUIRED | UUID of the dynamic Brcode. | **Request** ```python import starkinfra brcode = starkinfra.dynamicbrcode.get("b2c3d4e5-f6a7-8901-bcde-f12345678901") print(brcode) ``` **Response** ```python DynamicBrcode( id="5656565656565656", name="Jon Snow", city="São Paulo", external_id="my-dynamic-brcode-id-1", type="instant", tags=["dynamic", "instant"], uuid="b2c3d4e5-f6a7-8901-bcde-f12345678901", url="https://brcode.starkinfra.com/dynamic-qrcode/b2c3d4e5-f6a7-8901-bcde-f12345678901.png", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ## Brcode Preview A Brcode Preview allows you to fetch the information encoded in a QR code before initiating a Pix payment or accepting a Pix Subscription. Here we will show you how to retrieve Brcode previews. ### The Brcode Preview Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | QR code content (the EMV string from the QR code). | | `payerId` | STRING | CPF or CNPJ of the payer. | | `endToEndId` | STRING | Unique end-to-end ID of the Pix transaction associated with this preview. | | `status` | STRING | Status of the QR code. Options: "created", "overdue", "paid", "voided", "canceled", "expired". | | `name` | STRING | Receiver name. | | `taxId` | STRING | CPF or CNPJ of the receiver. | | `bankCode` | STRING | Bank ISPB code of the receiver. | | `branchCode` | STRING | Branch code of the receiver's account. | | `accountNumber` | STRING | Account number of the receiver. | | `accountType` | STRING | Account type of the receiver. | | `senderFinalName` | STRING | Full name of the final sender (The debtor). | | `senderFinalTaxId` | STRING | CPF or CNPJ of the final sender (The debtor). | | `amount` | INTEGER | Amount in cents to be paid. If 0, the BR Code accepts any value. | | `nominalAmount` | INTEGER | Nominal amount in cents before discounts, fines and interest. | | `amountType` | STRING | Type of amount. If the amount type is "custom" the BR Code's amount can be changed by the sender at the moment of payment. Options: "fixed", "custom". | | `reconciliationId` | STRING | Reconciliation ID from the QR code. A dynamic BR Code carries 26 to 35 alphanumeric characters here; a static one carries up to 25. | | `description` | STRING | Description of the payment. | | `cashierType` | STRING | Cashier type for Pix Saque/Troco. Options: "merchant", "other", "participant". | | `cashierBankCode` | STRING | Bank ISPB code of the cashier. | | `cashAmount` | INTEGER | Cash amount in cents for Pix Saque/Troco. | | `discountAmount` | INTEGER | Discount amount in cents. | | `fineAmount` | INTEGER | Fine amount in cents for late payment. | | `interestAmount` | INTEGER | Interest amount in cents for late payment. | | `reductionAmount` | INTEGER | Reduction (abatement) amount in cents. | | `due` | STRING | Due date and time for payment of the dynamic QR code. Example: "2020-04-23T23:00:00.000000+00:00". | | `expired` | STRING | Date and time after which the dynamic QR code is considered expired. Example: "2020-04-23T23:00:00.000000+00:00". | | `keyId` | STRING | Pix key of the receiver. | | `data` | LIST OF OBJECTS | List of additional data objects with key and value. | | `scheduled` | STRING | Date and time the payment is scheduled for. Example: "2020-04-23T23:00:00.000000+00:00". | | `jws` | STRING | JWS (JSON Web Signature) of the dynamic QR code. Returned only when "jws" is passed in the expand query parameter. | | `subscription.amount` | INTEGER | Fixed amount in cents to be pulled on each cycle. Returns 0 when the receiver registered no fixed amount and the amount of each pull is variable. Example: 1000 (R$10.00). | | `subscription.amountMinLimit` | INTEGER | Minimum amount in cents the receiver accepts on a pull of a variable-amount subscription. Returns 0 when no minimum was registered. Example: 500 (R$5.00). | | `subscription.bacenId` | STRING | Central Bank's unique id for the recurring authorization. Example: "RR20220101200181830000000000001". | | `subscription.created` | STRING | Datetime when the recurring authorization was created at the Central Bank. Example: "2022-01-01T10:00:00+00:00". | | `subscription.description` | STRING | Description of the recurring authorization, presented to the payer. Returns an empty string when the receiver registered none. Example: "Streaming subscription". | | `subscription.installmentEnd` | STRING | Last instant at which a pull of this subscription is allowed. The Central Bank registers a date, and the API returns its last microsecond in São Paulo time, converted to UTC. Returns an empty string when the authorization has no end date. Example: "2023-01-02T02:59:59.999999+00:00" for a subscription registered to end on 2023-01-01. | | `subscription.installmentStart` | STRING | Instant from which a pull of this subscription is allowed, built from the registered start date the same way as **subscription.installmentEnd**. Example: "2022-01-02T02:59:59.999999+00:00" for a subscription registered to start on 2022-01-01. | | `subscription.interval` | STRING | Interval between two pulls of this subscription. Options: "week", "month", "quarter", "semester", "year". | | `subscription.pullRetryLimit` | INTEGER | Number of retries the receiver may attempt for a failed pull. Options: 0 (retries not allowed) or 3 (up to 3 retries inside 7 days). | | `subscription.receiverBankCode` | STRING | Bank ISPB code of the receiver of the recurring authorization. Example: "20018183". | | `subscription.receiverName` | STRING | Name of the receiver of the recurring authorization. Example: "Stark Bank S.A.". | | `subscription.receiverTaxId` | STRING | CNPJ of the receiver of the recurring authorization, returned exactly as registered at the Central Bank and therefore usually unformatted. Example: "20018183000180". | | `subscription.referenceCode` | STRING | Code the receiver uses to identify the contract behind the subscription. Example: "contract-12345". | | `subscription.senderFinalName` | STRING | Name of the final payer of the recurring authorization. Returns an empty string when the authorization registers no final payer. Example: "Jon Snow". | | `subscription.senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, returned exactly as registered at the Central Bank and therefore usually unformatted. Returns an empty string when the authorization registers no final payer. Example: "01234567890". | | `subscription.status` | STRING | Status of the recurring authorization, read from its latest update at the Central Bank. Options: "created", "approved", "denied", "expired", "canceled". | | `subscription.type` | STRING | How this BR Code combines payment and recurring authorization. Options: "qrcode" (authorization only, no payment data), "qrcodeAndPayment" (immediate payment plus authorization), "paymentAndOrQrcode" (static or due BR Code plus authorization). | | `subscription.updated` | STRING | Datetime of the latest update of the recurring authorization at the Central Bank. Example: "2022-01-01T10:05:00+00:00". | ### Create Brcode Previews `POST /v2/brcode-preview` Fetch and preview the details of one or more Pix QR codes before payment. You can preview up to 100 Brcodes in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | QR code content (the EMV string from the QR code). | | `payerId` | REQUIRED | CPF or CNPJ of the payer for dynamic QR codes. | | `scheduled` | OPTIONAL | Date the payment is scheduled to be processed. This affects the preview values for due dynamic QR codes. Example: "2022-01-31". | | `endToEndId` | OPTIONAL | Unique end-to-end ID of the Pix transaction associated with this preview. One will be generated if none is provided. | | `cityCode` | OPTIONAL | IBGE city code of the payer, with 7 digits. Example: "5300108". | | `expand` | OPTIONAL | Entity fields to expand in the response. Options: "jws". | **Request** ```python import starkinfra previews = starkinfra.brcodepreview.create([ starkinfra.BrcodePreview( id="00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5905Stark6009Sao Paulo62070503***63041D3D", payer_id="012.345.678-90", end_to_end_id="E20018183202201201450u34sDGd19lz", scheduled="2022-01-31" ) ]) for preview in previews: print(preview) ``` **Response** ```python [ BrcodePreview( id="00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5905Stark6009Sao Paulo62070503***63041D3D", payer_id="012.345.678-90", end_to_end_id="E20018183202201201450u34sDGd19lz", status="active", name="Jon Snow", tax_id="012.345.678-90", bank_code="20018183", branch_code="0001", account_number="10000-0", account_type="checking", amount=1000, nominal_amount=1000, amount_type="fixed", reconciliation_id="my-reconciliation-id", description="Payment for services", cashier_type="merchant", cashier_bank_code="20018183", cash_amount=0, discount_amount=0, fine_amount=0, interest_amount=0, reduction_amount=0, due="2022-01-31T00:00:00+00:00", expired="2022-02-01T00:00:00+00:00", key_id="+5511989898989", data=[ {"key": "additional-info", "value": "order #12345"} ], scheduled="2022-01-31T00:00:00+00:00", jws="eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...", subscription=Subscription( bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="Subscription for services", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="2023-01-01T00:00:00+00:00", pull_retry_limit=3, receiver_name="Stark Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_final_name="Jon Snow", sender_final_tax_id="012.345.678-90", type="qrcodeAndPayment", status="approved", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ) ] ``` ## Pix Pull Subscription A Pix Pull Subscription is a recurring authorization (Pix Automático) that lets a receiver pull Pix payments from a payer's account on a defined schedule. Here we will show you how to create and manage them. ### The Pix Pull Subscription Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix pull subscription. | | `bacenId` | STRING | Central Bank identifier of the recurring authorization. | | `amount` | INTEGER | Fixed amount in cents pulled on each cycle. 0 when the amount is variable. | | `amountMinLimit` | INTEGER | Minimum amount in cents allowed per pull when the amount is variable. | | `interval` | STRING | Billing interval. Options: "week", "month", "quarter", "semester", "year". | | `description` | STRING | Description presented to the payer. | | `referenceCode` | STRING | Free reference code for the subscription. | | `installmentStart` | STRING | Date when the recurring authorization starts. | | `installmentEnd` | STRING | Date when the recurring authorization ends. | | `due` | STRING | Due datetime for the payer to approve the authorization. | | `pullRetryLimit` | INTEGER | Maximum number of pull retries allowed per cycle. | | `type` | STRING | Subscription type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode". | | `externalId` | STRING | Unique external id to prevent duplicates. | | `receiverName` | STRING | Name of the receiver (creditor). | | `receiverTaxId` | STRING | CPF or CNPJ of the receiver. | | `receiverBankCode` | STRING | Bank ISPB code of the receiver. | | `senderTaxId` | STRING | CPF or CNPJ of the payer (debtor). | | `senderAccountNumber` | STRING | Account number of the payer. | | `senderBranchCode` | STRING | Branch code of the payer's account. | | `senderBankCode` | STRING | Bank ISPB code of the payer. | | `senderFinalName` | STRING | Name of the final payer, when different from the account holder. | | `senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, when different from the account holder. | | `senderCityCode` | STRING | IBGE city code of the payer. | | `status` | STRING | Current status. Options: "created", "pending", "approved", "active", "failed", "denied", "canceled", "expired". | | `tags` | LIST OF STRINGS | Tags associated with the Pix pull subscription. | | `flow` | STRING | Direction of the subscription. Options: "out" (you are the receiver), "in" (you are the payer). | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Pull Subscriptions `POST /v2/pix-pull-subscription` Create recurring Pix authorizations (Pix Automático). Authorization is obtained through one of four journeys via the subscription type: push (push notification to the payer's bank), qrcode (QR Code with direct authorization), qrcodeAndPayment (QR Code with authorization upon payment), and paymentAndOrQrcode (billing QR Code with an authorization offer). **Parameters** | Name | Required | Description | | --- | --- | --- | | `subscriptions` | REQUIRED | List of 1 to 100 subscription objects to create. Each object accepts the parameters described below. | | `type` | OPTIONAL | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode". | | `externalId` | REQUIRED | Unique string to prevent duplicates. | | `bacenId` | REQUIRED | Central Bank identifier of the recurring authorization. | | `referenceCode` | REQUIRED | Free reference code for the subscription. | | `interval` | REQUIRED | Billing interval. Options: "week", "month", "quarter", "semester", "year". | | `installmentStart` | REQUIRED | Date when the recurring authorization starts. | | `receiverName` | REQUIRED | Name of the receiver (creditor). | | `receiverTaxId` | REQUIRED | CPF or CNPJ of the receiver. | | `senderTaxId` | REQUIRED | CPF or CNPJ of the payer (debtor). | | `senderAccountNumber` | REQUIRED | Account number of the payer. | | `senderBranchCode` | REQUIRED | Branch code of the payer's account. | | `amount` | OPTIONAL | Fixed amount in cents pulled on each cycle. Omit for a variable amount. | | `amountMinLimit` | OPTIONAL | Minimum amount in cents allowed per pull when the amount is variable. | | `pullRetryLimit` | OPTIONAL | Maximum number of pull retries allowed per cycle. | | `installmentEnd` | OPTIONAL | Date when the recurring authorization ends. | | `due` | OPTIONAL | Due datetime for the payer to approve the authorization. | | `description` | OPTIONAL | Description presented to the payer. | | `senderBankCode` | REQUIRED | Bank ISPB code of the payer. Example: "20018183". | | `senderFinalName` | OPTIONAL | Name of the final payer, when different from the account holder. | | `senderFinalTaxId` | OPTIONAL | CPF or CNPJ of the final payer, when different from the account holder. | | `senderCityCode` | REQUIRED | IBGE city code of the payer. | | `receiverBankCode` | REQUIRED | Bank ISPB code of the receiver. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra subscriptions = starkinfra.pixpullsubscription.create([ starkinfra.PixPullSubscription( type="push", external_id="my-subscription-id-1", bacen_id="RR20220101200181830000000000001", reference_code="contract-12345", interval="month", installment_start="2022-01-01", amount=1000, receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", tags=["automatic", "pix"] ) ]) for subscription in subscriptions: print(subscription) ``` **Response** ```python [ PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="", status="created", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Pull Subscriptions `GET /v2/pix-pull-subscription` List and filter all Pix pull subscriptions. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `externalIds` | OPTIONAL | Filter by the external ids provided on creation. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `flows` | OPTIONAL | Filter by flow direction. Options: "in", "out". | **Request** ```python import starkinfra subscriptions = starkinfra.pixpullsubscription.query( limit=10, status="active" ) for subscription in subscriptions: print(subscription) ``` **Response** ```python PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="", status="active", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-02T00:00:00+00:00" ) ``` ### Get a Pix Pull Subscription `GET /v2/pix-pull-subscription/:id` Get a single Pix pull subscription by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix pull subscription entity. | **Request** ```python import starkinfra subscription = starkinfra.pixpullsubscription.get("5656565656565656") print(subscription) ``` **Response** ```python PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="", status="active", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-02T00:00:00+00:00" ) ``` ### Update a Pix Pull Subscription `PATCH /v2/pix-pull-subscription/:id` Approve, deny or activate a Pix pull subscription. The allowed status transitions depend on whether you are the payer or the receiver. When confirming a received subscription, include the senderCityCode field. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix pull subscription entity. | | `status` | REQUIRED | New status. As the receiver, you may set status to "approved" or "denied" when the subscription's type is "subscriptionAndPayment". As the sender, you may set it to "confirmed" or "denied" for a delivered subscription; when confirming, the senderCityCode field is required. | | `reason` | OPTIONAL | Reason for the status change, required when denying. The available values depend on whether you are the sender or the receiver. Options: "accountClosed", "accountBlocked", "invalidBranchCode", "notRecognizedBySender", "userRejected", "notOffered". | | `senderCityCode` | OPTIONAL | IBGE city code of the payer. Required when status is being patched to "confirmed" (as the sender, when confirming a delivered subscription). | **Request** ```python import starkinfra subscription = starkinfra.pixpullsubscription.update( "5656565656565656", status="approved", sender_city_code="3550308" ) print(subscription) ``` **Response** ```python PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="3550308", status="approved", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-02T00:00:00+00:00" ) ``` ### Cancel a Pix Pull Subscription `DELETE /v2/pix-pull-subscription/:id` Cancel a Pix pull subscription. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix pull subscription entity. | | `reason` | OPTIONAL | Reason for the cancellation. The available values depend on whether you are the sender or the receiver. Options: "accountClosed", "receiverOrganizationClosed", "receiverInternalError", "senderDeceased", "fraud", "senderUserRequested", "receiverUserRequested", "paymentNotFound". | **Request** ```python import starkinfra subscription = starkinfra.pixpullsubscription.cancel("5656565656565656") print(subscription) ``` **Response** ```python PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="", status="canceled", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-03T00:00:00+00:00" ) ``` ### List Pix Pull Subscription Logs `GET /v2/pix-pull-subscription/log` Get a paged list of all Pix pull subscription logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `subscriptionIds` | OPTIONAL | Filter logs by the Pix pull subscription ids they belong to. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter by log types. Options: "created", "delivering", "delivered", "approved", "confirmed", "failed", "denied", "canceling", "canceled", "expired". | **Request** ```python import starkinfra logs = starkinfra.pixpullsubscription.log.query( limit=10, types=["approved"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", subscription=PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="3550308", status="approved", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-02T00:00:00+00:00" ), type="approved", errors=[], reason="", created="2022-01-02T00:00:00+00:00" ) ``` ### Get a Pix Pull Subscription Log `GET /v2/pix-pull-subscription/log/:id` Get a single Pix pull subscription log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixpullsubscription.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", subscription=PixPullSubscription( id="5656565656565656", bacen_id="RR20220101200181830000000000001", amount=1000, amount_min_limit=0, interval="month", description="", reference_code="contract-12345", installment_start="2022-01-01T00:00:00+00:00", installment_end="", due="", pull_retry_limit=3, type="push", external_id="my-subscription-id-1", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", sender_tax_id="012.345.678-90", sender_account_number="00000-0", sender_branch_code="0001", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", sender_city_code="3550308", status="approved", tags=["automatic", "pix"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-02T00:00:00+00:00" ), type="approved", errors=[], reason="", created="2022-01-02T00:00:00+00:00" ) ``` ## Pix Pull Request A Pix Pull Request is a single charge issued against an active [Pix Pull Subscription](#pix-pull-subscription) (Pix Automático), pulling a payment from the payer's account. Here we will show you how to create and manage them. ### The Pix Pull Request Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix pull request. | | `amount` | INTEGER | Amount in cents to be pulled. | | `description` | STRING | Description of the pull request. | | `due` | STRING | Due datetime for the pull. | | `endToEndId` | STRING | End-to-end id of the Pix pull request. | | `reconciliationId` | STRING | Reconciliation id (txid) of the pull. | | `subscriptionId` | STRING | Id of the Pix pull subscription this request belongs to. | | `subscriptionBacenId` | STRING | Central Bank id of the related subscription. | | `receiverName` | STRING | Name of the receiver (creditor). | | `receiverTaxId` | STRING | CPF or CNPJ of the receiver. | | `receiverBankCode` | STRING | Bank ISPB code of the receiver. | | `receiverAccountNumber` | STRING | Account number of the receiver. | | `receiverBranchCode` | STRING | Branch code of the receiver's account. | | `receiverAccountType` | STRING | Type of the receiver's account. | | `senderTaxId` | STRING | CPF or CNPJ of the payer (debtor). | | `senderBankCode` | STRING | Bank ISPB code of the payer. | | `senderFinalName` | STRING | Name of the final payer, when different from the account holder. | | `senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, when different from the account holder. | | `attemptType` | STRING | Pull attempt type. Options: "default", "scheduledRetry", "instantRetry". | | `tags` | LIST OF STRINGS | Tags associated with the Pix pull request. | | `flow` | STRING | Direction of the pull request. Options: "out" (you are the receiver), "in" (you are the payer). | | `status` | STRING | Current status. Options: "created", "processing", "scheduled", "denied", "success", "failed", "canceled", "expired". | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Pull Requests `POST /v2/pix-pull-request` Issue charges against active Pix pull subscriptions. As the receiver bank, create a Pix Pull Request to instruct a debit from the payer's account on a scheduled date. Stark Infra verifies that the subscription is approved, the amount is within the authorized limit, the settlement date matches the subscription's charge cycle, payer/receiver details match the contract, the request is made between 10 and 2 days before settlement, and there is no other scheduled request for the same cycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `requests` | REQUIRED | List of Pix pull request objects to be created. Min = 1, Max = 100. The parameters below describe the fields of each object. | | `subscriptionId` | REQUIRED | Id of the active Pix pull subscription to charge. | | `amount` | REQUIRED | Amount in cents to be pulled. | | `due` | REQUIRED | Due datetime for the pull. | | `attemptType` | REQUIRED | Pull attempt type. Options: "default", "scheduledRetry", "instantRetry". | | `endToEndId` | REQUIRED | End-to-end id of the Pix pull request. | | `reconciliationId` | REQUIRED | Reconciliation id (txid) of the pull. | | `receiverAccountNumber` | REQUIRED | Account number of the receiver. | | `receiverAccountType` | REQUIRED | Type of the receiver's account. | | `receiverBankCode` | OPTIONAL | Bank ISPB code of the receiver. | | `receiverBranchCode` | OPTIONAL | Branch code of the receiver's account. | | `description` | OPTIONAL | Description of the pull request. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra requests = starkinfra.pixpullrequest.create([ starkinfra.PixPullRequest( subscription_id="5656565656565656", amount=1000, due="2022-02-01T00:00:00+00:00", attempt_type="default", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", receiver_account_number="00000-0", receiver_account_type="checking", tags=["automatic", "pix"] ) ]) for request in requests: print(request) ``` **Response** ```python [ PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="out", status="created", created="2022-01-15T00:00:00+00:00", updated="2022-01-15T00:00:00+00:00" ) ] ``` ### List Pix Pull Requests `GET /v2/pix-pull-request` List and filter all Pix pull requests. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `subscriptionIds` | OPTIONAL | Filter by the Pix pull subscription ids the requests belong to. | | `endToEndIds` | OPTIONAL | Filter by the end-to-end ids of the requests. | | `externalIds` | OPTIONAL | Filter by the external ids of the requests. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `attemptTypes` | OPTIONAL | Filter by attempt type. Options: "default", "scheduledRetry", "instantRetry". | | `flows` | OPTIONAL | Filter by flow direction. Options: "in", "out". | **Request** ```python import starkinfra requests = starkinfra.pixpullrequest.query( limit=10, subscription_ids=["5656565656565656"] ) for request in requests: print(request) ``` **Response** ```python PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="out", status="success", created="2022-01-15T00:00:00+00:00", updated="2022-02-01T00:00:00+00:00" ) ``` ### Get a Pix Pull Request `GET /v2/pix-pull-request/:id` Get a single Pix pull request by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix pull request entity. | **Request** ```python import starkinfra request = starkinfra.pixpullrequest.get("4646464646464646") print(request) ``` **Response** ```python PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="out", status="success", created="2022-01-15T00:00:00+00:00", updated="2022-02-01T00:00:00+00:00" ) ``` ### Update a Pix Pull Request `PATCH /v2/pix-pull-request/:id` Schedule or deny a Pix pull request. Only the payer may update a pull request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix pull request entity. | | `status` | REQUIRED | New status. Options: "scheduled", "denied". | | `reason` | OPTIONAL | Reason for the status change, required when denying. Options: "senderAccountClosed", "senderAccountBlocked", "amountNotAllowed". | **Request** ```python import starkinfra request = starkinfra.pixpullrequest.update( "4646464646464646", status="denied", reason="senderAccountClosed" ) print(request) ``` **Response** ```python PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="in", status="denied", created="2022-01-15T00:00:00+00:00", updated="2022-01-16T00:00:00+00:00" ) ``` ### Cancel a Pix Pull Request `DELETE /v2/pix-pull-request/:id` Cancel a Pix pull request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix pull request entity. | | `reason` | REQUIRED | Reason for the cancellation. The available values depend on whether you are the sender or the receiver. Options: "accountClosed", "accountBlocked", "pixRequestFailed", "other", "senderUserRequested", "receiverUserRequested". | **Request** ```python import starkinfra request = starkinfra.pixpullrequest.cancel( "4646464646464646", reason="senderAccountClosed" ) print(request) ``` **Response** ```python PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="out", status="canceled", created="2022-01-15T00:00:00+00:00", updated="2022-01-16T00:00:00+00:00" ) ``` ### List Pix Pull Request Logs `GET /v2/pix-pull-request/log` Get a paged list of all Pix pull request logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `requestIds` | OPTIONAL | Filter logs by the Pix pull request ids they belong to. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter by log types. Options: "created", "sent", "scheduled", "denied", "success", "failed", "canceling", "canceled", "expired". | **Request** ```python import starkinfra logs = starkinfra.pixpullrequest.log.query( limit=10, types=["success"] ) for log in logs: print(log) ``` **Response** ```python Log( id="5757575757575757", request=PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="out", status="success", created="2022-01-15T00:00:00+00:00", updated="2022-02-01T00:00:00+00:00" ), type="success", errors=[], reason="", description="The Pix Pull Request was settled.", created="2022-02-01T00:00:00+00:00" ) ``` ### Get a Pix Pull Request Log `GET /v2/pix-pull-request/log/:id` Get a single Pix pull request log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixpullrequest.log.get("5757575757575757") print(log) ``` **Response** ```python Log( id="5757575757575757", request=PixPullRequest( id="4646464646464646", amount=1000, description="", due="2022-02-01T00:00:00+00:00", end_to_end_id="E20018183202201010000000000001", reconciliation_id="txid1234567890", subscription_id="5656565656565656", subscription_bacen_id="RR20220101200181830000000000001", receiver_name="Iron Bank S.A.", receiver_tax_id="20.018.183/0001-80", receiver_bank_code="20018183", receiver_account_number="00000-0", receiver_branch_code="0001", receiver_account_type="checking", sender_tax_id="012.345.678-90", sender_bank_code="00000000", sender_final_name="", sender_final_tax_id="", attempt_type="default", tags=["automatic", "pix"], flow="out", status="success", created="2022-01-15T00:00:00+00:00", updated="2022-02-01T00:00:00+00:00" ), type="success", errors=[], reason="", description="The Pix Pull Request was settled.", created="2022-02-01T00:00:00+00:00" ) ``` ## Pix Key A Pix Key is an alias that can be used to identify a bank account in the Brazilian Pix system (DICT). Here we will show you how to create and manage them. ### The Pix Key Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix key (the key value itself, e.g., CPF, email, phone, EVP). | | `type` | STRING | Type of the Pix key. Options: "cpf", "cnpj", "phone", "email", "evp". | | `accountCreated` | STRING | Creation date of the linked bank account. | | `accountType` | STRING | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". | | `bankCode` | STRING | Bank ISPB code of the linked account. | | `branchCode` | STRING | Branch code of the linked bank account. | | `accountNumber` | STRING | Account number of the linked bank account. | | `holderName` | STRING | Name of the account holder. | | `holderTaxId` | STRING | CPF or CNPJ of the account holder. | | `status` | STRING | Current status. Options: "created", "registered", "canceled", "failed". | | `owned` | STRING | Datetime when the key was registered in DICT. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create a Pix Key `POST /v2/pix-key` Register a new Pix key in DICT for your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `accountCreated` | REQUIRED | Creation date of the linked bank account. | | `accountNumber` | REQUIRED | Account number of the linked bank account. | | `accountType` | REQUIRED | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". | | `branchCode` | REQUIRED | Branch code of the linked bank account. | | `name` | REQUIRED | Name of the account holder. | | `taxId` | REQUIRED | CPF or CNPJ of the account holder. | | `id` | OPTIONAL | Key value (CPF, CNPJ, email, phone). Leave empty to generate an EVP key. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra key = starkinfra.pixkey.create( starkinfra.PixKey( account_created="2022-01-01", account_number="10000-0", account_type="checking", branch_code="0001", name="Jon Snow", tax_id="012.345.678-90", id="jon.snow@starkinfra.com", tags=["pix", "key"] ) ) print(key) ``` **Response** ```python PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="checking", bank_code="20018183", branch_code="0001", account_number="10000-0", name="Jon Snow", tax_id="012.345.678-90", status="created", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], created="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Keys `GET /v2/pix-key` List and filter all Pix keys registered in your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | List of key values to get specific entities. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `taxId` | OPTIONAL | Filter Pix keys by the holder's CPF or CNPJ. | | `type` | OPTIONAL | Filter by key type. | **Request** ```python import starkinfra keys = starkinfra.pixkey.query( limit=10, after="2022-01-01", before="2022-12-31", status="registered", tags=["pix", "key"], ids=["jon.snow@starkinfra.com"], type="email", tax_id="012.345.678-90" ) for key in keys: print(key) ``` **Response** ```python PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="checking", bank_code="20018183", branch_code="0001", account_number="10000-0", name="Jon Snow", tax_id="012.345.678-90", status="registered", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], created="2022-01-01T00:00:00+00:00" ) ``` ### Get a Pix Key `GET /v2/pix-key/:id` Get a single Pix key by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id (key value) of the Pix key entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `payerTaxId` | OPTIONAL | Not a parameter you provide: the API automatically uses your Workspace's own registered tax ID (CPF/CNPJ) as the payer for DICT query rate-limiting purposes, so this field should be omitted. Any value sent has no effect. | | `endToEndId` | OPTIONAL | Unique end-to-end ID of the Pix transaction associated with this DICT query. | | `expand` | OPTIONAL | Entity fields to expand in the response. Options: "statistics", "ownerStatistics". | **Request** ```python import starkinfra key = starkinfra.pixkey.get( "jon.snow@starkinfra.com", payer_id="012.345.678-90", end_to_end_id="E00002649202201172211u34srod19le", expand=["statistics", "owner_statistics"] ) print(key) ``` **Response** ```python PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="checking", bank_code="20018183", branch_code="0001", account_number="10000-0", name="Jon Snow", tax_id="012.345.678-90", status="registered", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], statistics=[Statistic(after="2022-01-01", type="reconciliations", value=1)], owner_statistics=[Statistic(after="2022-01-01", type="settlements", value=3)], created="2022-01-01T00:00:00+00:00" ) ``` ### Update a Pix Key `PATCH /v2/pix-key/:id` Update the account information linked to a Pix key. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id (key value) of the Pix key entity. | | `reason` | REQUIRED | Reason for the update. Options: "branchTransfer", "reconciliation", "userRequested", "entryInvalid". | | `accountCreated` | OPTIONAL | New creation date of the linked bank account. | | `accountNumber` | OPTIONAL | New account number. | | `accountType` | OPTIONAL | New account type. | | `branchCode` | OPTIONAL | New branch code. | | `name` | OPTIONAL | New holder name. | **Request** ```python import starkinfra key = starkinfra.pixkey.update( "jon.snow@starkinfra.com", reason="branchTransfer", account_created="2022-01-01", account_number="20000-1", account_type="savings", branch_code="0002", name="Jon Snow" ) print(key) ``` **Response** ```python PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="savings", bank_code="20018183", branch_code="0002", account_number="20000-1", name="Jon Snow", tax_id="012.345.678-90", status="registered", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], created="2022-01-01T00:00:00+00:00" ) ``` ### Cancel a Pix Key `DELETE /v2/pix-key/:id` Cancel a Pix key and remove it from DICT. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id (key value) of the Pix key entity. | **Request** ```python import starkinfra key = starkinfra.pixkey.cancel("jon.snow@starkinfra.com") print(key) ``` **Response** ```python PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="checking", bank_code="20018183", branch_code="0001", account_number="10000-0", name="Jon Snow", tax_id="012.345.678-90", status="canceled", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], created="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Key Logs `GET /v2/pix-key/log` Get a paged list of all Pix key logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | Filter by Pix key ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixkey.log.query( limit=10, after="2022-01-01", before="2022-12-31", ids=["6767676767676767"], types=["registered"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", key=PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="checking", bank_code="20018183", branch_code="0001", account_number="10000-0", name="Jon Snow", tax_id="012.345.678-90", status="registered", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], statistics=[Statistic(after="2022-01-01", type="reconciliations", value=1)], owner_statistics=[Statistic(after="2022-01-01", type="settlements", value=3)], created="2022-01-01T00:00:00+00:00" ), type="registered", errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Key Log `GET /v2/pix-key/log/:id` Get a single Pix key log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixkey.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", key=PixKey( id="jon.snow@starkinfra.com", type="email", account_created="2022-01-01", account_type="checking", bank_code="20018183", branch_code="0001", account_number="10000-0", name="Jon Snow", tax_id="012.345.678-90", status="registered", owned="2022-01-01T00:00:00+00:00", tags=["pix", "key"], statistics=[Statistic(after="2022-01-01", type="reconciliations", value=1)], owner_statistics=[Statistic(after="2022-01-01", type="settlements", value=3)], created="2022-01-01T00:00:00+00:00" ), type="registered", errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ## Pix Key Holmes PixKeyHolmes are used by a Pix participant to verify whether a Pix key is registered in DICT, the Brazilian Central Bank's key directory. Here we will show you how to create and manage them. ### The Pix Key Holmes Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix key holmes. | | `status` | STRING | Current status. Options: "created", "solving", "solved", "failed". | | `keyId` | STRING | Pix key under verification. | | `result` | STRING | Verification result. Options: "registered", "unregistered". Empty until the status is "solved". | | `tags` | LIST OF STRINGS | Tags associated with the Pix key holmes. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Key Holmes `POST /v2/pix-key-holmes` Request the verification of one or more Pix keys in DICT. You can create up to 100 Pix key holmes in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `keyId` | REQUIRED | Pix key to be verified. Can be a CPF, CNPJ, phone, e-mail or EVP (random) key. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra holmes = starkinfra.pixkeyholmes.create([ starkinfra.PixKeyHolmes( key_id="jon.snow@starkinfra.com", tags=["key-check"] ) ]) for sherlock in holmes: print(sherlock) ``` **Response** ```python [ PixKeyHolmes( id="5656565656565656", status="solving", key_id="jon.snow@starkinfra.com", result="", tags=["key-check"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Key Holmes `GET /v2/pix-key-holmes` List and filter all Pix key holmes. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `keyId` | OPTIONAL | Filter by the verified Pix key. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. Options: "created", "solving", "solved", "failed". | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | **Request** ```python import starkinfra holmes = starkinfra.pixkeyholmes.query( limit=10, status="solved" ) for sherlock in holmes: print(sherlock) ``` **Response** ```python PixKeyHolmes( id="5656565656565656", status="solved", key_id="jon.snow@starkinfra.com", result="registered", tags=["key-check"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:05+00:00" ) ``` ### Get a Pix Key Holmes `GET /v2/pix-key-holmes/:id` Get a single Pix key holmes by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix key holmes entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra sherlock = starkinfra.pixkeyholmes.get("5656565656565656") print(sherlock) ``` **Response** ```python PixKeyHolmes( id="5656565656565656", status="solved", key_id="jon.snow@starkinfra.com", result="registered", tags=["key-check"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:05+00:00" ) ``` ### List Pix Key Holmes Logs `GET /v2/pix-key-holmes/log` Get a paged list of all Pix key holmes logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | Filter by Pix key holmes log ids. | | `holmesIds` | OPTIONAL | Filter logs by the Pix key holmes ids they belong to. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter by log types. Options: "solving", "solved". | **Request** ```python import starkinfra logs = starkinfra.pixkeyholmes.log.query( limit=10, types="solved" ) for log in logs: print(log) ``` **Response** ```python PixKeyHolmes.Log( id="6767676767676767", type="solved", holmes=PixKeyHolmes( id="5656565656565656", status="solved", key_id="jon.snow@starkinfra.com", result="registered", tags=["key-check"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:05+00:00" ), errors=[], created="2022-01-01T00:00:05+00:00" ) ``` ### Get a Pix Key Holmes Log `GET /v2/pix-key-holmes/log/:id` Get a single Pix key holmes log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.pixkeyholmes.log.get("6767676767676767") print(log) ``` **Response** ```python PixKeyHolmes.Log( id="6767676767676767", type="solved", holmes=PixKeyHolmes( id="5656565656565656", status="solved", key_id="jon.snow@starkinfra.com", result="registered", tags=["key-check"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:05+00:00" ), errors=[], created="2022-01-01T00:00:05+00:00" ) ``` ## Pix Claim A Pix Claim is used to port or own a Pix key from another institution to your workspace. Here we will show you how to create and manage them. ### The Pix Claim Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix claim. | | `type` | STRING | Type of the claim. Options: "ownership", "portability". | | `keyType` | STRING | Type of the Pix key being claimed. Options: "cpf", "cnpj", "phone", "email", "evp". | | `keyId` | STRING | Value of the Pix key being claimed. | | `status` | STRING | Current status. Options: "created", "failed", "delivered", "confirmed", "success", "canceled". | | `flow` | STRING | Direction of the Pix claim. Options: "out" (you are claiming a key from another institution), "in" (another institution is claiming a key from you). | | `name` | STRING | Name of the account holder. | | `taxId` | STRING | CPF or CNPJ of the account holder. | | `bacenId` | STRING | Central Bank ID for this Pix claim. | | `tags` | LIST OF STRINGS | Tags associated with the Pix claim. | | `claimerBankCode` | STRING | Bank ISPB code of the institution claiming the Pix key. | | `claimedBankCode` | STRING | Bank ISPB code of the institution that currently owns the Pix key. | | `branchCode` | STRING | Branch code of the linked bank account. | | `accountNumber` | STRING | Account number of the linked bank account. | | `accountType` | STRING | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". | | `accountCreated` | STRING | Creation date of the linked bank account. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create a Pix Claim `POST /v2/pix-claim` Initiate a Pix key portability or ownership claim. An ownership claim changes the holder of a [Pix Key](#pix-key) (only phone keyType). A portability claim changes the linked account without changing the holder (phone, email or taxId keyTypes). **Parameters** | Name | Required | Description | | --- | --- | --- | | `accountCreated` | REQUIRED | Creation date of your linked bank account. | | `accountNumber` | REQUIRED | Your bank account number. | | `accountType` | REQUIRED | Your bank account type. Options: "checking", "savings", "salary", "payment". | | `branchCode` | REQUIRED | Your bank account branch code. | | `name` | REQUIRED | Name of the account holder. | | `taxId` | REQUIRED | CPF or CNPJ of the account holder. | | `keyId` | REQUIRED | Value of the Pix key being claimed. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra claim = starkinfra.pixclaim.create( starkinfra.PixClaim( account_created="2022-01-01", account_number="10000-0", account_type="checking", branch_code="0001", name="Jon Snow", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", tags=["claim", "portability"] ) ) print(claim) ``` **Response** ```python PixClaim( id="5656565656565656", type="portability", key_type="email", key_id="jon.snow@starkinfra.com", status="created", flow="out", name="Jon Snow", tax_id="012.345.678-90", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["claim", "portability"], claimer_bank_code="20018183", claimed_bank_code="60701190", branch_code="0001", account_number="10000-0", account_type="checking", account_created="2022-01-01T00:00:00+00:00", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Claims `GET /v2/pix-claim` List and filter all Pix claims. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `bacenId` | OPTIONAL | Filter by the Central Bank ID of the Pix claim. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `flow` | OPTIONAL | Filter by claim flow. Options: "in" (incoming claims), "out" (outgoing claims). | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `keyId` | OPTIONAL | Filter by the Pix key value. | | `keyType` | OPTIONAL | Filter by the type of the Pix key being claimed. Options: "cpf", "cnpj", "phone", "email", "evp". | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `type` | OPTIONAL | Filter by claim type. | **Request** ```python import starkinfra claims = starkinfra.pixclaim.query( limit=10, after="2022-01-01", before="2022-12-31", status=["delivered"], type="portability", flow="out" ) for claim in claims: print(claim) ``` **Response** ```python PixClaim( id="5656565656565656", type="portability", key_type="email", key_id="jon.snow@starkinfra.com", status="delivered", flow="out", name="Jon Snow", tax_id="012.345.678-90", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["claim", "portability"], claimer_bank_code="20018183", claimed_bank_code="60701190", branch_code="0001", account_number="10000-0", account_type="checking", account_created="2022-01-01T00:00:00+00:00", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Claim `GET /v2/pix-claim/:id` Get a single Pix claim by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix claim entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra claim = starkinfra.pixclaim.get("5656565656565656") print(claim) ``` **Response** ```python PixClaim( id="5656565656565656", type="portability", key_type="email", key_id="jon.snow@starkinfra.com", status="delivered", flow="out", name="Jon Snow", tax_id="012.345.678-90", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["claim", "portability"], claimer_bank_code="20018183", claimed_bank_code="60701190", branch_code="0001", account_number="10000-0", account_type="checking", account_created="2022-01-01T00:00:00+00:00", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ) ``` ### Update a Pix Claim `PATCH /v2/pix-claim/:id` Confirm or cancel an incoming Pix claim. You must answer an inbound Pix Claim within 7 days of its status changing to delivered. If unanswered, a portability claim is rejected by default and an ownership claim is accepted by default, both with reason defaultBehavior. You can only confirm Pix Claims with delivered status; confirming deletes the referenced [Pix Key](#pix-key) from Stark Infra and the Central Bank. You can only cancel Pix Claims with delivered or confirmed status. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix claim entity. | | `status` | REQUIRED | New status for the claim. Options: "confirmed", "canceled". | | `reason` | OPTIONAL | Reason for the status change. Options: "userRequested", "accountClosure", "fraud". Defaults to "userRequested". | **Request** ```python import starkinfra claim = starkinfra.pixclaim.update( "5656565656565656", status="confirmed", reason="userRequested" ) print(claim) ``` **Response** ```python PixClaim( id="5656565656565656", type="portability", key_type="email", key_id="jon.snow@starkinfra.com", status="confirmed", flow="out", name="Jon Snow", tax_id="012.345.678-90", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["claim", "portability"], claimer_bank_code="20018183", claimed_bank_code="60701190", branch_code="0001", account_number="10000-0", account_type="checking", account_created="2022-01-01T00:00:00+00:00", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:02:00+00:00" ) ``` ### List Pix Claim Logs `GET /v2/pix-claim/log` Get a paged list of all Pix claim logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `claimIds` | OPTIONAL | List of strings to filter logs by their Pix claim ids. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | Filter by Pix claim ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixclaim.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["confirmed"], claim_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", claim=PixClaim( id="5656565656565656", type="portability", key_type="email", key_id="jon.snow@starkinfra.com", status="delivered", flow="out", name="Jon Snow", tax_id="012.345.678-90", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["claim", "portability"], claimer_bank_code="20018183", claimed_bank_code="60701190", branch_code="0001", account_number="10000-0", account_type="checking", account_created="2022-01-01T00:00:00+00:00", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), type="confirmed", errors=[], reason="userRequested", created="2022-01-01T00:02:00+00:00" ) ``` ### Get a Pix Claim Log `GET /v2/pix-claim/log/:id` Get a single Pix claim log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.pixclaim.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", claim=PixClaim( id="5656565656565656", type="portability", key_type="email", key_id="jon.snow@starkinfra.com", status="delivered", flow="out", name="Jon Snow", tax_id="012.345.678-90", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["claim", "portability"], claimer_bank_code="20018183", claimed_bank_code="60701190", branch_code="0001", account_number="10000-0", account_type="checking", account_created="2022-01-01T00:00:00+00:00", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), type="confirmed", errors=[], reason="userRequested", created="2022-01-01T00:02:00+00:00" ) ``` ## Pix Infraction A Pix Infraction is used to respond to Pix fraud and operational issues to the Brazilian Central Bank. Here we will show you how to manage them. ### The Pix Infraction Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix infraction. | | `referenceId` | STRING | End-to-end id of the transaction the infraction refers to. | | `type` | STRING | Type of infraction. Options: "reversal", "reversalChargeback". | | `method` | STRING | Fraud method. Options: "scam", "invasion", "other", "unauthorized", "coercion", "unknown". | | `operatorEmail` | STRING | Contact email of the operator responsible for the Pix infraction. | | `operatorPhone` | STRING | Contact phone number of the operator responsible for the Pix infraction. | | `fraudId` | STRING | Id of the Pix fraud marking associated with the infraction. | | `fraudType` | STRING | Type of fraud associated with the infraction. Options: "identity", "mule", "scam", "other", "unknown". | | `description` | STRING | Description of the infraction. | | `analysis` | STRING | Analysis text that justifies the result of the infraction report. | | `tags` | LIST OF STRINGS | Tags associated with the Pix infraction. | | `bacenId` | STRING | Id of the infraction at the Brazilian Central Bank. | | `disputeId` | STRING | Id of the Pix dispute associated with the infraction. | | `amount` | INTEGER | Amount in cents related to the infraction. Example: 1234 (= R$ 12.34). | | `flow` | STRING | Direction of the infraction report. Options: "out" (reported by you), "in" (reported against you). | | `status` | STRING | Current status. Options: "created", "failed", "delivered", "closed", "canceled". | | `creditedBankCode` | STRING | Bank ISPB code of the credited party. | | `debitedBankCode` | STRING | Bank ISPB code of the debited party. | | `reportedBy` | STRING | Institution that reported the infraction. Options: "debited", "credited". | | `result` | STRING | Result of the infraction analysis. Options: "agreed", "disagreed". | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### List Pix Infractions `GET /v2/pix-infraction` List and filter all Pix infractions. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `type` | OPTIONAL | Filter by infraction type. | **Request** ```python import starkinfra infractions = starkinfra.pixinfraction.query( limit=10, after="2022-01-01", before="2022-12-31", status=["delivered"], type=["fraud"], flow="out", tags=["infraction", "fraud"] ) for infraction in infractions: print(infraction) ``` **Response** ```python PixInfraction( id="5656565656565656", reference_id="E20018183202201060100rq1feOMJqtZ", type="fraud", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", fraud_id="5741774970552320", fraud_type="scam", description="Client reported unauthorized transaction.", analysis="Fraud confirmed after investigation.", tags=["infraction", "fraud"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="4545454545454545", amount=1234, flow="out", status="delivered", credited_bank_code="20018183", debited_bank_code="20018183", reported_by="credited", result="agreed", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Infraction `GET /v2/pix-infraction/:id` Get a single Pix infraction by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix infraction entity. | **Request** ```python import starkinfra infraction = starkinfra.pixinfraction.get("5656565656565656") print(infraction) ``` **Response** ```python PixInfraction( id="5656565656565656", reference_id="E20018183202201060100rq1feOMJqtZ", type="fraud", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", fraud_id="5741774970552320", fraud_type="scam", description="Client reported unauthorized transaction.", analysis="Fraud confirmed after investigation.", tags=["infraction", "fraud"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="4545454545454545", amount=1234, flow="out", status="delivered", credited_bank_code="20018183", debited_bank_code="20018183", reported_by="credited", result="agreed", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ) ``` ### Update a Pix Infraction `PATCH /v2/pix-infraction/:id` Respond to an incoming Pix infraction report. Agree with an inbound infraction by patching its analysis to agreed, or disagree by patching it to disagreed. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix infraction entity. | | `result` | REQUIRED | Result of the analysis. Options: "agreed", "disagreed". | | `fraudType` | CONDITIONALLY REQUIRED | Type of fraud associated with the infraction. Required when result is "agreed", optional when result is "disagreed". Options: "identity", "mule", "scam", "other". | | `analysis` | OPTIONAL | Analysis text explaining the result. | **Request** ```python import starkinfra infraction = starkinfra.pixinfraction.update( "5656565656565656", result="agreed", fraud_type="scam", analysis="Fraud confirmed after investigation." ) print(infraction) ``` **Response** ```python PixInfraction( id="5656565656565656", reference_id="E20018183202201060100rq1feOMJqtZ", type="fraud", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", fraud_id="5741774970552320", fraud_type="scam", description="Client reported unauthorized transaction.", analysis="Fraud confirmed after investigation.", tags=["infraction", "fraud"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="4545454545454545", amount=1234, flow="in", status="closed", credited_bank_code="20018183", debited_bank_code="20018183", reported_by="debited", result="agreed", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:02:00+00:00" ) ``` ### Cancel a Pix Infraction `DELETE /v2/pix-infraction/:id` Cancel a Pix infraction you reported. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix infraction entity. | **Request** ```python import starkinfra infraction = starkinfra.pixinfraction.cancel("5656565656565656") print(infraction) ``` **Response** ```python PixInfraction( id="5656565656565656", reference_id="E20018183202201060100rq1feOMJqtZ", type="fraud", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", fraud_id="5741774970552320", fraud_type="scam", description="Client reported unauthorized transaction.", analysis="Fraud confirmed after investigation.", tags=["infraction", "fraud"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="4545454545454545", amount=1234, flow="out", status="canceled", credited_bank_code="20018183", debited_bank_code="20018183", reported_by="credited", result="agreed", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:03:00+00:00" ) ``` ### List Pix Infraction Logs `GET /v2/pix-infraction/log` Get a paged list of all Pix infraction logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | Filter by Pix infraction ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixinfraction.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["delivered"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", infraction=PixInfraction( id="5656565656565656", reference_id="E20018183202201060100rq1feOMJqtZ", type="fraud", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", fraud_id="5741774970552320", fraud_type="scam", description="Client reported unauthorized transaction.", analysis="Fraud confirmed after investigation.", tags=["infraction", "fraud"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="4545454545454545", amount=1234, flow="out", status="delivered", credited_bank_code="20018183", debited_bank_code="20018183", reported_by="credited", result="agreed", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), type="delivered", errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Infraction Log `GET /v2/pix-infraction/log/:id` Get a single Pix infraction log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixinfraction.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", infraction=PixInfraction( id="5656565656565656", reference_id="E20018183202201060100rq1feOMJqtZ", type="fraud", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", fraud_id="5741774970552320", fraud_type="scam", description="Client reported unauthorized transaction.", analysis="Fraud confirmed after investigation.", tags=["infraction", "fraud"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="4545454545454545", amount=1234, flow="out", status="delivered", credited_bank_code="20018183", debited_bank_code="20018183", reported_by="credited", result="agreed", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), type="delivered", errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ## Pix Chargeback A Pix Chargeback allows you to request the return of funds from a Pix transaction made in error or due to fraud, and to respond to chargebacks opened against your transactions, through MED. Here we will show you how to create and manage them. ### The Pix Chargeback Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix chargeback. | | `amount` | INTEGER | Amount in cents to be charged back. | | `referenceId` | STRING | End-to-end ID of the original Pix transaction. | | `reason` | STRING | Reason for the chargeback. Options: "flaw", "fraud", "subscriptionFlaw", "reversalChargeback". | | `result` | STRING | Result of the chargeback. Options: "rejected", "accepted", "partiallyAccepted". | | `analysis` | STRING | Analysis text from the responding party. | | `description` | STRING | Description of the chargeback request. | | `senderBankCode` | STRING | Bank ISPB code of the sender in the original transaction. | | `receiverBankCode` | STRING | Bank ISPB code of the receiver in the original transaction. | | `rejectionReason` | STRING | Reason for rejection if the chargeback was not agreed. Options: "other", "noBalance", "accountClosed", "invalidRequest". | | `bacenId` | STRING | Central Bank ID for this Pix chargeback. | | `disputeId` | STRING | Unique id of the Pix dispute associated with the chargeback. | | `isMonitoringRequired` | BOOLEAN | Indicates whether monitoring is required for this chargeback. | | `reversalBankCode` | STRING | Bank ISPB code of the account that received the reversal. | | `reversalBranchCode` | STRING | Branch code of the account that received the reversal. | | `reversalAccountNumber` | STRING | Number of the account that received the reversal. | | `reversalAccountType` | STRING | Type of the account that received the reversal. Options: "checking", "savings", "salary", "payment", "other". | | `reversalTaxId` | STRING | Tax ID (CPF/CNPJ) of the account that received the reversal. | | `status` | STRING | Current status. Options: "created", "failed", "delivered", "closed", "canceled". | | `tags` | LIST OF STRINGS | Tags associated with the Pix chargeback. | | `flow` | STRING | Direction of the chargeback. Options: "out" (you requested), "in" (requested against you). | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Chargebacks `POST /v2/pix-chargeback` Request a chargeback for a Pix transaction. A Pix Chargeback requests the reversal of a Pix transaction and should only be created after a corresponding [Pix Infraction](#pix-infraction) is completed (or a system malfunction). The other participant must answer within 24 hours. The only supported reason is flaw — reversing an erroneous transaction caused by a system malfunction. **Parameters** | Name | Required | Description | | --- | --- | --- | | `amount` | REQUIRED | Amount in cents to be charged back. | | `reason` | REQUIRED | Reason for the chargeback. Options: "flaw", "fraud", "subscriptionFlaw" - the only reasons you can submit on creation. "reversalChargeback" is assigned automatically by the API to chargebacks created from a closed Pix Infraction, and cannot be set directly. | | `referenceId` | REQUIRED | End-to-end ID of the original Pix transaction. | | `description` | CONDITIONALLY REQUIRED | Description of the chargeback request. Required when reason is "flaw". | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra chargebacks = starkinfra.pixchargeback.create([ starkinfra.PixChargeback( amount=1000, reason="flaw", reference_id="E20018183202201201450u34sDjD7334", description="Chargeback request due to confirmed fraud", tags=["chargeback", "fraud"] ) ]) for chargeback in chargebacks: print(chargeback) ``` **Response** ```python [ PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="flaw", result=None, analysis=None, description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code=None, reversal_branch_code=None, reversal_account_number=None, reversal_account_type=None, reversal_tax_id=None, status="created", tags=["chargeback", "fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Chargebacks `GET /v2/pix-chargeback` List and filter all Pix chargebacks. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `bacenId` | OPTIONAL | Filter by the Central Bank ID of the Pix chargeback. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `flow` | OPTIONAL | Filter by flow direction. Options: "in", "out". | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `referenceIds` | OPTIONAL | List of end-to-end IDs of the original Pix transactions to filter by. Max = 30. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | **Request** ```python import starkinfra chargebacks = starkinfra.pixchargeback.query( limit=10, after="2022-01-01", before="2022-12-31", status=["delivered"], ids=["5656565656565656"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", reference_ids=["E20018183202201201450u34sDjD7334"], flow="out", tags=["fraud"] ) for chargeback in chargebacks: print(chargeback) ``` **Response** ```python PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="fraud", result=None, analysis=None, description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code=None, reversal_branch_code=None, reversal_account_number=None, reversal_account_type=None, reversal_tax_id=None, status="delivered", tags=["fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Pix Chargeback `GET /v2/pix-chargeback/:id` Get a single Pix chargeback by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix chargeback entity. | **Request** ```python import starkinfra chargeback = starkinfra.pixchargeback.get("5656565656565656") print(chargeback) ``` **Response** ```python PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="fraud", result=None, analysis=None, description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code=None, reversal_branch_code=None, reversal_account_number=None, reversal_account_type=None, reversal_tax_id=None, status="delivered", tags=["fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Update a Pix Chargeback `PATCH /v2/pix-chargeback/:id` Respond to an incoming Pix chargeback request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix chargeback entity. | | `result` | REQUIRED | Result of the chargeback analysis. Options: "rejected", "accepted", "partiallyAccepted". | | `analysis` | OPTIONAL | Analysis text explaining the result. Required when rejectionReason is "invalidRequest". | | `rejectionReason` | OPTIONAL | Reason for rejection. Required when result is "rejected". Options: "other", "noBalance", "accountClosed", "invalidRequest". | | `reversalReferenceId` | OPTIONAL | Return ID of the reversal used to partially or fully agree to the chargeback. | **Request** ```python import starkinfra chargeback = starkinfra.pixchargeback.update( "5656565656565656", result="agreed", analysis="Fraud confirmed, agreeing to chargeback.", reversal_reference_id="D20018183202201201450u34sDjD7334" ) print(chargeback) ``` **Response** ```python PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="fraud", result="agreed", analysis="Fraud confirmed, agreeing to chargeback.", description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code="20018183", reversal_branch_code="0001", reversal_account_number="5341615776841728", reversal_account_type="checking", reversal_tax_id="012.345.678-90", status="closed", tags=["chargeback", "fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-06-01T00:00:00+00:00" ) ``` ### Cancel a Pix Chargeback `DELETE /v2/pix-chargeback/:id` Cancel a Pix chargeback you requested. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix chargeback entity. | **Request** ```python import starkinfra chargeback = starkinfra.pixchargeback.cancel("5656565656565656") print(chargeback) ``` **Response** ```python PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="fraud", result=None, analysis=None, description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code=None, reversal_branch_code=None, reversal_account_number=None, reversal_account_type=None, reversal_tax_id=None, status="canceled", tags=["chargeback", "fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-06-01T00:00:00+00:00" ) ``` ### List Pix Chargeback Logs `GET /v2/pix-chargeback/log` Get a paged list of all Pix chargeback logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `chargebackIds` | OPTIONAL | Filter by Pix chargeback ids. Max = 30. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixchargeback.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["delivered"], chargeback_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", chargeback=PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="flaw", result=None, analysis=None, description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code=None, reversal_branch_code=None, reversal_account_number=None, reversal_account_type=None, reversal_tax_id=None, status="delivered", tags=["fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), type="delivered", errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Chargeback Log `GET /v2/pix-chargeback/log/:id` Get a single Pix chargeback log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixchargeback.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", chargeback=PixChargeback( id="5656565656565656", amount=1000, reference_id="E20018183202201201450u34sDjD7334", reason="flaw", result=None, analysis=None, description="Chargeback request due to confirmed fraud", sender_bank_code="20018183", receiver_bank_code="34052649", rejection_reason=None, bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", dispute_id="d20018183202201201450u34sDjD7334", is_monitoring_required=False, reversal_bank_code=None, reversal_branch_code=None, reversal_account_number=None, reversal_account_type=None, reversal_tax_id=None, status="delivered", tags=["fraud"], flow="out", created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), type="delivered", errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ## Pix Fraud A Pix Fraud report allows you to flag suspicious users or keys in the Brazilian Pix system (DICT). Here we will show you how to create and manage them. ### The Pix Fraud Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix fraud report. | | `externalId` | STRING | Unique external ID to prevent duplicates. | | `type` | STRING | Type of fraud. Options: "identity", "mule", "scam", "other", "unknown". | | `taxId` | STRING | CPF or CNPJ of the fraudster. | | `keyId` | STRING | Pix key associated with the fraud. | | `bacenId` | STRING | Central Bank ID for this fraud report. | | `status` | STRING | Current status. Options: "created", "failed", "registered", "canceled". | | `tags` | LIST OF STRINGS | Tags associated with the Pix fraud report. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Fraud Reports `POST /v2/pix-fraud` Report a fraudulent user or Pix key to DICT. You can create up to 100 fraud reports in a single request. **Parameters** | Name | Required | Description | | --- | --- | --- | | `externalId` | REQUIRED | Unique string to prevent duplicates. | | `type` | REQUIRED | Type of fraud. Options: "identity", "mule", "scam", "other". | | `taxId` | REQUIRED | CPF or CNPJ of the fraudster. | | `keyId` | OPTIONAL | Pix key associated with the fraud. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra frauds = starkinfra.pixfraud.create([ starkinfra.PixFraud( external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", tags=["fraud", "mule"] ) ]) for fraud in frauds: print(fraud) ``` **Response** ```python [ PixFraud( id="5656565656565656", external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", status="created", tags=["fraud", "mule"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Fraud Reports `GET /v2/pix-fraud` List and filter all Pix fraud reports. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `bacenId` | OPTIONAL | Filter by the Central Bank ID of the fraud report. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `type` | OPTIONAL | Filter by fraud type. Options: "identity", "mule", "scam", "other". | **Request** ```python import starkinfra frauds = starkinfra.pixfraud.query( limit=10, after="2022-01-01", before="2022-12-31", status=["registered"], type=["mule"], bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", tags=["fraud", "mule"] ) for fraud in frauds: print(fraud) ``` **Response** ```python PixFraud( id="5656565656565656", external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", status="registered", tags=["fraud", "mule"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Fraud Report `GET /v2/pix-fraud/:id` Get a single Pix fraud report by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix fraud entity. | **Request** ```python import starkinfra fraud = starkinfra.pixfraud.get("5656565656565656") print(fraud) ``` **Response** ```python PixFraud( id="5656565656565656", external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", status="registered", tags=["fraud", "mule"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ) ``` ### Cancel a Pix Fraud Report `DELETE /v2/pix-fraud/:id` Cancel a Pix fraud report you submitted. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix fraud entity. | **Request** ```python import starkinfra fraud = starkinfra.pixfraud.cancel("5656565656565656") print(fraud) ``` **Response** ```python PixFraud( id="5656565656565656", external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", status="canceled", tags=["fraud", "mule"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:02:00+00:00" ) ``` ### List Pix Fraud Logs `GET /v2/pix-fraud/log` Get a paged list of all Pix fraud logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | | `ids` | OPTIONAL | Filter by Pix fraud log ids. | | `fraudIds` | OPTIONAL | Filter logs by the Pix fraud report ids they belong to. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter by log types. Options: "created", "failed", "registered", "canceling", "canceled". | **Request** ```python import starkinfra logs = starkinfra.pixfraud.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["registered"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", type="registered", fraud=PixFraud( id="5656565656565656", external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", status="registered", tags=["fraud", "mule"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Fraud Log `GET /v2/pix-fraud/log/:id` Get a single Pix fraud log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixfraud.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", type="registered", fraud=PixFraud( id="5656565656565656", external_id="my-fraud-id-1", type="mule", tax_id="012.345.678-90", key_id="jon.snow@starkinfra.com", bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99", status="registered", tags=["fraud", "mule"], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), errors=[], created="2022-01-01T00:01:00+00:00" ) ``` ## Pix Dispute A Pix Dispute allows you to request, cancel and consult disputes related to Pix transactions through MED 2.0. Here we will show you how to create and manage them. ### The Pix Dispute Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix dispute. | | `referenceId` | STRING | End-to-end ID of the original Pix transaction. | | `bacenId` | STRING | Central Bank's unique ID for the Pix dispute. | | `method` | STRING | Method of the dispute. Options: "scam", "unauthorized", "coercion", "invasion", "other", "unknown". | | `description` | STRING | Description of the Pix dispute. | | `operatorEmail` | STRING | Contact email of the operator responsible for the Pix dispute. | | `operatorPhone` | STRING | Contact phone number of the operator responsible for the Pix dispute. | | `status` | STRING | Current status. Options: "created", "failed", "delivered", "analysed", "processing", "closed", "canceled". | | `tags` | LIST OF STRINGS | Tags associated with the Pix dispute. | | `flow` | STRING | Direction of the dispute. Options: "out" (you initiated), "in" (raised against you). | | `minTransactionAmount` | INTEGER | Minimum amount in cents of the transactions to be tracked in the dispute. | | `maxTransactionCount` | INTEGER | Maximum number of transactions to be tracked in the dispute. | | `maxHopCount` | INTEGER | Maximum number of hops to be tracked in the dispute. | | `maxHopInterval` | INTEGER | Maximum interval in seconds between hops to be tracked in the dispute. | | `transactions` | LIST OF OBJECTS | List of transaction objects tracked in the dispute. | | `transactions.endToEndId` | STRING | End-to-end ID of the tracked Pix transaction. | | `transactions.amount` | INTEGER | Transaction amount in cents. | | `transactions.nominalAmount` | INTEGER | Refundable amount in cents of the transaction. | | `transactions.senderId` | STRING | Bacen-generated pseudo ID for the sender, used only for transaction-tracking context (not a real account identifier). | | `transactions.senderType` | STRING | Type of the sender entity. Options: "individual", "business". | | `transactions.senderTaxIdCreated` | STRING | Returned only for CNPJ tax IDs: the date the sender company was opened. Example: "2020-04-23T23:00:00.000000+00:00". | | `transactions.senderAccountCreated` | STRING | Datetime when the sender's account was opened. Example: "2020-04-23T23:00:00.000000+00:00". | | `transactions.senderBankCode` | STRING | Bank code of the sender's institution. | | `transactions.receiverId` | STRING | Bacen-generated pseudo ID for the receiver, used only for transaction-tracking context (not a real account identifier). | | `transactions.receiverType` | STRING | Type of the receiver entity. Options: "individual", "business". | | `transactions.receiverTaxIdCreated` | STRING | Returned only for CNPJ tax IDs: the date the receiver company was opened. Example: "2020-04-23T23:00:00.000000+00:00". | | `transactions.receiverAccountCreated` | STRING | Datetime when the receiver's account was opened. Example: "2020-04-23T23:00:00.000000+00:00". | | `transactions.receiverBankCode` | STRING | Bank code of the receiver's institution. | | `transactions.settled` | STRING | Datetime when the transaction was settled. Example: "2020-04-23T23:00:00.000000+00:00". | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create Pix Disputes `POST /v2/pix-dispute` Initiate a Pix dispute for a transaction. **Parameters** | Name | Required | Description | | --- | --- | --- | | `referenceId` | REQUIRED | End-to-end ID of the original Pix transaction. | | `method` | REQUIRED | Method of the dispute. Options: "scam", "unauthorized", "coercion", "invasion", "other", "unknown". | | `operatorEmail` | REQUIRED | Contact email of the operator responsible for the Pix dispute. | | `operatorPhone` | REQUIRED | Contact phone number of the operator responsible for the Pix dispute. | | `description` | OPTIONAL | Description of the Pix dispute. Required when method is "other". | | `minTransactionAmount` | OPTIONAL | Minimum amount in cents of the transactions to be tracked in the dispute. | | `maxHopCount` | OPTIONAL | Maximum number of hops to be tracked in the dispute. | | `maxHopInterval` | OPTIONAL | Maximum interval in seconds between hops to be tracked in the dispute. | | `maxTransactionCount` | OPTIONAL | Maximum number of transactions to be tracked in the dispute. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra disputes = starkinfra.pixdispute.create([ starkinfra.PixDispute( reference_id="E20018183202201201450u34sDjD7334", method="scam", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", description="Transaction reported by the account holder as fraudulent.", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, tags=["dispute", "scam"] ) ]) for dispute in disputes: print(dispute) ``` **Response** ```python [ PixDispute( id="5656565656565656", reference_id="E20018183202201201450u34sDjD7334", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", method="scam", description="Transaction reported by the account holder as fraudulent.", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", status="created", tags=["dispute", "scam"], flow="out", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, transactions=[], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ] ``` ### List Pix Disputes `GET /v2/pix-dispute` List and filter all Pix disputes. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `bacenId` | OPTIONAL | Filter for the Central Bank's unique ID of the Pix dispute. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `flow` | OPTIONAL | Filter by flow direction. Options: "in", "out". | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `referenceIds` | OPTIONAL | List of end-to-end IDs to get disputes by their original Pix transactions. | | `status` | OPTIONAL | Filter by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | **Request** ```python import starkinfra disputes = starkinfra.pixdispute.query( limit=10, after="2022-01-01", before="2022-12-31", status="delivered", flow="out", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", reference_ids=["E20018183202201201450u34sDjD7334"], ids=["5656565656565656", "4545454545454545"], tags=["scam"] ) for dispute in disputes: print(dispute) ``` **Response** ```python PixDispute( id="5656565656565656", reference_id="E20018183202201201450u34sDjD7334", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", method="scam", description="Transaction reported by the account holder as fraudulent.", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", status="delivered", tags=["scam"], flow="out", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, transactions=[], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Get a Pix Dispute `GET /v2/pix-dispute/:id` Get a single Pix dispute by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix dispute entity. | **Request** ```python import starkinfra dispute = starkinfra.pixdispute.get("5656565656565656") print(dispute) ``` **Response** ```python PixDispute( id="5656565656565656", reference_id="E20018183202201201450u34sDjD7334", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", method="scam", description="Transaction reported by the account holder as fraudulent.", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", status="delivered", tags=["dispute", "scam"], flow="out", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, transactions=[], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### Cancel a Pix Dispute `DELETE /v2/pix-dispute/:id` Cancel a Pix dispute you initiated. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix dispute entity. | **Request** ```python import starkinfra dispute = starkinfra.pixdispute.cancel("5656565656565656") print(dispute) ``` **Response** ```python PixDispute( id="5656565656565656", reference_id="E20018183202201201450u34sDjD7334", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", method="scam", description="Transaction reported by the account holder as fraudulent.", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", status="canceled", tags=["dispute", "scam"], flow="out", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, transactions=[], created="2022-01-01T00:00:00+00:00", updated="2022-06-01T00:00:00+00:00" ) ``` ### List Pix Dispute Logs `GET /v2/pix-dispute/log` Get a paged list of all Pix dispute logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `disputeIds` | OPTIONAL | List of strings to get logs by their Pix dispute ids. | | `ids` | OPTIONAL | Filter by Pix dispute ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log types. | **Request** ```python import starkinfra logs = starkinfra.pixdispute.log.query( limit=10, after="2022-01-01", before="2022-12-31", types=["delivered"], dispute_ids=["5656565656565656"], ids=["6767676767676767"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6767676767676767", type="delivered", dispute=PixDispute( id="5656565656565656", reference_id="E20018183202201201450u34sDjD7334", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", method="scam", description="Transaction reported by the account holder as fraudulent.", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", status="delivered", tags=["dispute", "scam"], flow="out", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, transactions=[], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ### Get a Pix Dispute Log `GET /v2/pix-dispute/log/:id` Get a single Pix dispute log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.pixdispute.log.get("6767676767676767") print(log) ``` **Response** ```python Log( id="6767676767676767", type="delivered", dispute=PixDispute( id="5656565656565656", reference_id="E20018183202201201450u34sDjD7334", bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05", method="scam", description="Transaction reported by the account holder as fraudulent.", operator_email="ned.stark@starkbank.com", operator_phone="+5511999999999", status="delivered", tags=["dispute", "scam"], flow="out", min_transaction_amount=100, max_transaction_count=10, max_hop_count=5, max_hop_interval=3600, transactions=[], created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:01:00+00:00" ), created="2022-01-01T00:01:00+00:00" ) ``` ## Pix User The Pix User resource lets you consult, through DICT, an end user's statistics on Pix keys, Pix requests, frauds and infractions registered across Bacen's systems (e.g. SPI for Pix requests). Here we will show you how to retrieve user data. ### The Pix User Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Tax ID (CPF or CNPJ) used to query the user. | | `statistics.value` | INTEGER | Number of occurrences counted for this statistic. | | `statistics.type` | STRING | Type of the statistic; the valid values depend on the source. Options: "registered", "unique" (pix-key); "settled" (pix-request); "identity", "mule", "scam", "other", "unknown", "amount", "unique" (pix-fraud); "open", "denied", "unique" (pix-infraction). | | `statistics.source` | STRING | Source of the statistic. Options: "pix-key", "pix-fraud", "pix-request", "pix-infraction". | | `statistics.after` | STRING | Datetime from which the statistic was computed. Example: "2020-04-23T23:00:00.000000+00:00". | | `statistics.updated` | STRING | Last update datetime of the statistic. Example: "2020-04-23T23:00:00.000000+00:00". | ### Get a Pix User `GET /v2/pix-user/:taxId` Retrieve a user's aggregated Pix statistics — Pix keys, Pix requests, frauds and infractions — for a specific user by their tax ID. **Parameters** | Name | Required | Description | | --- | --- | --- | | `taxId` | REQUIRED | CPF or CNPJ of the user to query. | | `keyId` | OPTIONAL | Pix key to retrieve statistics for. When provided, the response returns the key statistics instead of the owner statistics. | **Request** ```python import starkinfra user = starkinfra.pixuser.get("012.345.678-90") print(user) ``` **Response** ```python PixUser( id="012.345.678-90", statistics=[ PixUser.Statistics( value=3, type="open", source="pix-infraction", after="2020-04-23T23:00:00.000000+00:00", updated="2020-04-23T23:00:00.000000+00:00" ) ] ) ``` ## Pix Balance The Pix Balance represents the current available balance in your Pix account. Here we will show you how to retrieve it. ### The Pix Balance Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Identifier of the balance. Holds the participant bank code for direct participants or the workspace id for indirect participants. | | `currency` | STRING | Currency of the balance amount. Example: "BRL". | | `amount` | INTEGER | Current balance amount in cents. Example: 1234 (R$ 12.34). | | `updated` | STRING | ISO datetime that represents when the balance was last updated. Example: "2020-04-23T23:00:00.000000+00:00". | ### Get Pix Balance `GET /v2/pix-balance` Retrieve the current Pix balance of your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `before` | OPTIONAL | Date used to retrieve the balance as of the end of the informed day. Example: "2022-01-31". When omitted or set to the current day, the current balance is returned. | **Request** ```python import starkinfra balance = starkinfra.pixbalance.get( before="2022-01-31" ) print(balance) ``` **Response** ```python PixBalance( id="5656565656565656", amount=10000000, currency="BRL", updated="2022-01-01T00:00:00+00:00" ) ``` ## Pix Domain Pix Domains are the domains Pix participants register with Bacen to provide Brcodes, along with their respective certificate chains used for secure communication. Here we will show you how to list them. ### The Pix Domain Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `name` | STRING | Domain name registered in the Pix system. | | `certificates` | LIST OF OBJECTS | List of certificate objects that make up the domain's certificate chain. | | `certificates.content` | STRING | Certificate in PEM format. | ### List Pix Domains `GET /v2/pix-domain` List all registered Pix domains and their certificate chains. **Parameters** | Name | Required | Description | | --- | --- | --- | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra domains = starkinfra.pixdomain.query() for domain in domains: print(domain) ``` **Response** ```python PixDomain( name="pix.starkbank.com", certificates=[ pixdomain.Certificate( content="-----BEGIN CERTIFICATE-----..." ) ] ) ``` ## Pix Statement A Pix Statement allows you to request a detailed report of all Pix transactions in your account for a given period. A statement must be created before it can be read, and this feature is only available for direct Pix participants. Here we will show you how to create and manage them. ### The Pix Statement Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Pix statement. | | `after` | STRING | Start date of the statement period. | | `before` | STRING | End date of the statement period. | | `type` | STRING | Type of the statement. Options: "interchange", "interchangeTotal", "transaction". | | `status` | STRING | Current status. Options: "created", "looking", "success", "failed". | | `chunkCount` | INTEGER | Number of chunks the statement file is split into. Each chunk can be downloaded individually. | | `transactionCount` | INTEGER | Number of transactions in the statement. | | `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". | ### Create a Pix Statement `POST /v2/pix-statement` Request a Pix statement for a specific period and type. The after and before parameters must name the same single day the statement covers. For type "interchange" or "interchangeTotal", that day must be the first day of a past month (after = before = "2022-01-01"). For type "transaction", after and before may be full timestamps up to 24 hours apart. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | REQUIRED | Start date of the statement period. Example: "2022-01-01". | | `before` | REQUIRED | End date of the statement period. Example: "2022-01-01". | | `type` | REQUIRED | Type of the statement. Options: "interchange", "interchangeTotal", "transaction". | **Request** ```python import starkinfra statement = starkinfra.pixstatement.create( starkinfra.PixStatement( after="2022-01-01", before="2022-01-31", type="transaction" ) ) print(statement) ``` **Response** ```python PixStatement( id="5656565656565656", after="2022-01-01", before="2022-01-31", type="transaction", status="created", chunk_count=0, transaction_count=0, created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:00:00+00:00" ) ``` ### List Pix Statements `GET /v2/pix-statement` List and filter all Pix statements. Results are paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | **Request** ```python import starkinfra statements = starkinfra.pixstatement.query(limit=10) for statement in statements: print(statement) ``` **Response** ```python PixStatement( id="5656565656565656", after="2022-01-01", before="2022-01-31", type="transaction", status="success", chunk_count=2, transaction_count=150, created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:05:00+00:00" ) ``` ### Get a Pix Statement `GET /v2/pix-statement/:id` Get a single Pix statement by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix statement entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra statement = starkinfra.pixstatement.get("5656565656565656") print(statement) ``` **Response** ```python PixStatement( id="5656565656565656", after="2022-01-01", before="2022-01-31", type="transaction", status="success", chunk_count=2, transaction_count=150, created="2022-01-01T00:00:00+00:00", updated="2022-01-01T00:05:00+00:00" ) ``` ### Get a Pix Statement CSV `GET /v2/pix-statement/:id/csv` Get the CSV file for a completed Pix statement. The file is returned compressed in the gzip format. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix statement entity. | **Request** ```python import starkinfra csv = starkinfra.pixstatement.csv("5656565656565656") with open("statement.zip", "wb") as f: f.write(csv) ``` **Response** ```python ``` ### Get a Pix Statement Chunk `GET /v2/pix-statement/:id/chunk/:number` Get a single chunk of a completed Pix statement. Large statements are split into numbered parts, letting you download one chunk at a time. The chunk is returned compressed in the gzip format. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Pix statement entity. | | `number` | REQUIRED | Number of the chunk to retrieve, ranging from 1 to the statement's chunkCount. | **Request** ```python import starkinfra response = starkinfra.request.get("/pix-statement/5656565656565656/chunk/1") with open("statement-chunk-1.csv.gz", "wb") as f: f.write(response.content) ``` **Response** ```python ``` ## Pix Director The Pix Director represents the responsible officer for Pix operations in your institution, as required by the Brazilian Central Bank. Here we will show you how to register them. ### The Pix Director Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `name` | STRING | Full name of the director. | | `taxId` | STRING | CPF of the director. | | `phone` | STRING | Phone number of the director. | | `email` | STRING | Email address of the director. | | `password` | STRING | Password for director access. | | `teamEmail` | STRING | Team email for Pix notifications. | | `teamPhones` | LIST OF STRINGS | List of team phone numbers for Pix notifications. | | `status` | STRING | Current registration status of the Pix director. Options: "success", "processing", "failed". | ### Create a Pix Director `POST /v2/pix-director` Register the Pix director for your institution as required by the Brazilian Central Bank. **Parameters** | Name | Required | Description | | --- | --- | --- | | `email` | REQUIRED | Email address of the director. | | `name` | REQUIRED | Full name of the director. | | `password` | REQUIRED | Password for director access. | | `phone` | REQUIRED | Phone number of the director. | | `taxId` | REQUIRED | CPF of the director. | | `teamEmail` | REQUIRED | Team email for Pix notifications. | | `teamPhones` | REQUIRED | List of team phone numbers for Pix notifications. | **Request** ```python import starkinfra director = starkinfra.pixdirector.create( starkinfra.PixDirector( name="Jon Snow", tax_id="012.345.678-90", phone="+5511999999999", email="jon.snow@starkinfra.com", password="P@ssword1234", team_email="team@starkinfra.com", team_phones=["+5511888888888", "+5511777777777"] ) ) print(director) ``` **Response** ```python PixDirector( id="5656565656565656", name="Jon Snow", tax_id="012.345.678-90", phone="+5511999999999", email="jon.snow@starkinfra.com", password="P@ssword1234", team_email="team@starkinfra.com", team_phones=["+5511888888888", "+5511777777777"], status="success" ) ``` # Issuing ## Issuing Balance The Issuing Balance resource represents the total funds available in your issuing wallet. This balance is separate from your main Stark Infra balance and is used exclusively for card spending. Fund your issuing balance using [Issuing Invoices](#issuing-invoice) and withdraw using [Issuing Withdrawals](#issuing-withdrawal). ### The Issuing Balance object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing balance. | | `amount` | INTEGER | Current issuing balance amount in cents. Example: 5000000 (R$50,000.00). | | `limit` | INTEGER | Spending limit of the balance. | | `maxLimit` | INTEGER | Maximum spending limit. This field is currently always equal to limit. | | `currency` | STRING | Currency code of the balance. Example: "BRL". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Get the Issuing Balance `GET /v2/issuing-balance` Get the current balance in your issuing wallet. **Request** ```python import starkinfra balance = starkinfra.issuingbalance.get() print(balance) ``` **Response** ```python IssuingBalance( id=5715709195239424, amount=5000000, limit=100000000, max_limit=100000000, currency=BRL, updated=2022-01-01 00:00:00 ) ``` ## Issuing Product The Issuing Product resource lists the card products available to your workspace. Each product has a network, funding type, holder type, and product code that define the characteristics of cards that can be created using that product. ### The Issuing Product object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing product. | | `network` | STRING | Card network. Options: "mastercard", "visa". | | `fundingType` | STRING | Funding type of the card. Options: "credit", "debit". | | `holderType` | STRING | Holder type for the card. Options: "individual", "business". | | `code` | STRING | Product code that identifies the specific card product. | | `settlement` | STRING | Same as fundingType. Kept for backward compatibility. | | `client` | STRING | Same as holderType. Kept for backward compatibility. | | `customerType` | STRING | Same as holderType. Kept for backward compatibility. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Products `GET /v2/issuing-product` Get a list of available issuing products for your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | **Request** ```python import starkinfra products = starkinfra.issuingproduct.query() for product in products: print(product) ``` **Response** ```python IssuingProduct( id=5715709195239424, network=Mastercard, funding_type=credit, holder_type=individual, code=ABC, settlement=credit, client=individual, customer_type=individual, created=2022-01-01 00:00:00 ) ``` ## Issuing Holder The Issuing Holder resource represents the card holder entity in your workspace. A holder is associated with one or more issuing cards and defines who can use the cards issued. You can set rules on the holder level to control spending limits and merchant restrictions. ### The Issuing Holder object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing holder. | | `name` | STRING | Full name of the holder. | | `taxId` | STRING | Holder CPF (11 digits) or CNPJ (14 digits). | | `externalId` | STRING | Your external reference for this holder. Must be unique per workspace to prevent duplicates. | | `status` | STRING | Current holder status. Options: "active", "blocked", "canceled". | | `tags` | LIST OF STRINGS | Tags associated with the holder. | | `rules` | LIST OF OBJECTS | List of spending rule objects applied to the holder. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Issuing Holders `POST /v2/issuing-holder` Use this route to create up to 100 new issuing holders at a time. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | Full name of the holder. Example: "Tony Stark". | | `taxId` | REQUIRED | Holder CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: "012.345.678-90". | | `externalId` | REQUIRED | Your unique identifier for this holder, used to prevent duplicates. Example: "my-holder-id-1234". | | `rules` | OPTIONAL | List of spending rule objects to apply to the holder. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | | `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules". | **Request** ```python import starkinfra holders = starkinfra.issuingholder.create([ starkinfra.IssuingHolder( name="Tony Stark", tax_id="012.345.678-90", external_id="my-holder-id-1234", tags=["department: tech", "team: backend"], rules=[ starkinfra.IssuingRule( name="max-spend", interval="day", amount=10000, currency_code="BRL" ) ] ) ]) for holder in holders: print(holder) ``` **Response** ```python IssuingHolder( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, external_id=my-holder-id-1234, status=active, tags=['department: tech'], rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Holders `GET /v2/issuing-holder` Get a list of issuing holders in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter holders by the specified status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules". | **Request** ```python import starkinfra holders = starkinfra.issuingholder.query( limit=10, status="active" ) for holder in holders: print(holder) ``` **Response** ```python IssuingHolder( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, external_id=my-holder-id-1234, status=active, tags=['department: tech'], rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Holder `GET /v2/issuing-holder/:id` Get a single issuing holder by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing holder entity. | | `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules". | **Request** ```python import starkinfra holder = starkinfra.issuingholder.get("5715709195239424") print(holder) ``` **Response** ```python IssuingHolder( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, external_id=my-holder-id-1234, status=active, tags=['department: tech'], rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Update an Issuing Holder `PATCH /v2/issuing-holder/:id` Update the properties of an existing issuing holder. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing holder entity. | | `status` | OPTIONAL | Status to update the holder to. Options: "active", "blocked". | | `name` | OPTIONAL | New full name of the holder. | | `rules` | OPTIONAL | New list of spending rule objects to apply to the holder. | | `tags` | OPTIONAL | New array of strings to tag the holder. | **Request** ```python import starkinfra holder = starkinfra.issuingholder.update( "5715709195239424", status="blocked" ) print(holder) ``` **Response** ```python IssuingHolder( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, external_id=my-holder-id-1234, status=blocked, tags=['department: tech'], rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### Cancel an Issuing Holder `DELETE /v2/issuing-holder/:id` Cancel an issuing holder. This action is irreversible. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing holder entity to cancel. | **Request** ```python import starkinfra holder = starkinfra.issuingholder.cancel("5715709195239424") print(holder) ``` **Response** ```python IssuingHolder( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, external_id=my-holder-id-1234, status=canceled, tags=['department: tech'], rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### List Issuing Holder Logs `GET /v2/issuing-holder/log` Get a paged list of issuing holder logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `holderIds` | OPTIONAL | Array of holder ids to filter logs. | | `ids` | OPTIONAL | List of strings to get specific log entities by ids. | **Request** ```python import starkinfra logs = starkinfra.issuingholder.log.query(limit=10) for log in logs: print(log) ``` **Response** ```python Log( id=5715709195239424, type=created, holder=IssuingHolder(id=5715709195239424, name=Tony Stark, status=active), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Holder Log `GET /v2/issuing-holder/log/:id` Get a single issuing holder log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingholder.log.get("5715709195239424") print(log) ``` **Response** ```python Log( id=5715709195239424, type=created, holder=IssuingHolder(id=5715709195239424, name=Tony Stark, status=active), created=2022-01-01 00:00:00 ) ``` ## Issuing Card The Issuing Card resource represents a physical or virtual card issued to a holder. Cards can be created as virtual (immediately available) or physical (requires embossing and shipping). You can set rules on the card level to control spending limits, merchant restrictions, and other card behaviors. ### The Issuing Card object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing card. | | `holderId` | STRING | Id of the IssuingHolder associated with this card. | | `holderName` | STRING | Name of the holder printed on the card. | | `holderTaxId` | STRING | Tax id of the IssuingHolder associated with this card. | | `holderExternalId` | STRING | External id of the IssuingHolder associated with this card. | | `displayName` | STRING | Name displayed on the card face. Example: "TONY STARK". | | `rules` | LIST OF OBJECTS | List of spending rule objects applied to the card. | | `productId` | STRING | Id of the IssuingProduct associated with this card. | | `tags` | LIST OF STRINGS | Tags associated with the card. | | `streetLine1` | STRING | Primary line of the billing address. | | `streetLine2` | STRING | Secondary line of the billing address. | | `district` | STRING | District of the billing address. | | `city` | STRING | City of the billing address. | | `stateCode` | STRING | State code of the billing address. Example: "SP". | | `zipCode` | STRING | ZIP code of the billing address. Example: "01311-000". | | `type` | STRING | Card type. Options: "virtual", "physical". | | `status` | STRING | Current card status. Options: "pending", "active", "blocked", "canceled", "expired". | | `number` | STRING | Card number (PAN). Masked unless "expand=number" is informed in the request. | | `securityCode` | STRING | Card security code (CVV). Masked unless "expand=securityCode" is informed in the request. | | `expiration` | STRING | Card expiration datetime. Masked unless "expand=expiration" is informed in the request. | | `isPinDefined` | BOOLEAN | Whether the card has a PIN defined. Returned only when "expand=isPinDefined" is informed in the request. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Issuing Cards `POST /v2/issuing-card` Use this route to create up to 100 new issuing cards at a time. The billing address parameters (streetLine1, streetLine2, district, city, stateCode and zipCode) default to the sub-issuer's registered address when omitted. **Parameters** | Name | Required | Description | | --- | --- | --- | | `holderName` | REQUIRED | Name of the card holder. Example: "Tony Stark". | | `holderTaxId` | REQUIRED | Tax id (CPF/CNPJ) of the card holder. Example: "012.345.678-90". | | `holderExternalId` | REQUIRED | Unique id of the card holder in your system. Example: "my-holder-id-1234". | | `productId` | OPTIONAL | Id of the IssuingProduct to use for this card. If omitted, a product is chosen automatically for the sub-issuer. | | `type` | OPTIONAL | Card type. Options: "virtual", "physical". Default: "virtual". | | `displayName` | OPTIONAL | Name to be displayed on the card. Example: "TONY STARK". | | `rules` | OPTIONAL | List of spending rule objects to apply to the card. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | | `streetLine1` | OPTIONAL | Primary line of the billing address. | | `streetLine2` | OPTIONAL | Secondary line of the billing address. | | `district` | OPTIONAL | District of the billing address. | | `city` | OPTIONAL | City of the billing address. | | `stateCode` | OPTIONAL | State code of the billing address. Example: "SP". | | `zipCode` | OPTIONAL | ZIP code of the billing address. Example: "01311-000". | | `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "securityCode", "number", "expiration", "isPinDefined". | **Request** ```python import starkinfra cards = starkinfra.issuingcard.create([ starkinfra.IssuingCard( holder_name="Tony Stark", holder_tax_id="012.345.678-90", holder_external_id="my-holder-id-1234", product_id="654321", type="virtual", display_name="TONY STARK", tags=["department: tech", "team: backend"] ) ]) for card in cards: print(card) ``` **Response** ```python IssuingCard( id=5715709195239424, holder_id=5155165527080960, holder_name=Tony Stark, holder_tax_id=012.345.678-90, holder_external_id=my-holder-id-1234, display_name=TONY STARK, product_id=654321, type=virtual, status=active, rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], street_line_1=Av. Faria Lima, 1844, street_line_2=10 andar, district=Itaim Bibi, city=Sao Paulo, state_code=SP, zip_code=01311-000, tags=['department: tech', 'team: backend'], number=**** **** **** 1234, security_code=***, expiration=****-**-**T**:**:**.******+00:00, is_pin_defined=False, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Cards `GET /v2/issuing-card` Get a list of issuing cards in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter cards by the specified status. Options: "pending", "active", "blocked", "canceled", "expired". | | `types` | OPTIONAL | Filter cards by type. Options: "virtual", "physical". | | `holderIds` | OPTIONAL | Filter cards by holder ids. | | `endings` | OPTIONAL | List of strings to filter cards by their last 4 digits. Max 30. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "securityCode", "number", "expiration", "isPinDefined". | **Request** ```python import starkinfra cards = starkinfra.issuingcard.query( limit=10, status="active" ) for card in cards: print(card) ``` **Response** ```python IssuingCard( id=5715709195239424, holder_id=5155165527080960, holder_name=Tony Stark, holder_tax_id=012.345.678-90, holder_external_id=my-holder-id-1234, display_name=TONY STARK, product_id=654321, type=virtual, status=active, rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], street_line_1=Av. Faria Lima, 1844, street_line_2=10 andar, district=Itaim Bibi, city=Sao Paulo, state_code=SP, zip_code=01311-000, tags=['department: tech', 'team: backend'], number=**** **** **** 1234, security_code=***, expiration=****-**-**T**:**:**.******+00:00, is_pin_defined=False, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Card `GET /v2/issuing-card/:id` Get a single issuing card by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing card entity. | | `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "securityCode", "number", "expiration", "isPinDefined". | **Request** ```python import starkinfra card = starkinfra.issuingcard.get("5715709195239424") print(card) ``` **Response** ```python IssuingCard( id=5715709195239424, holder_id=5155165527080960, holder_name=Tony Stark, holder_tax_id=012.345.678-90, holder_external_id=my-holder-id-1234, display_name=TONY STARK, product_id=654321, type=virtual, status=active, rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], street_line_1=Av. Faria Lima, 1844, street_line_2=10 andar, district=Itaim Bibi, city=Sao Paulo, state_code=SP, zip_code=01311-000, tags=['department: tech', 'team: backend'], number=**** **** **** 1234, security_code=***, expiration=****-**-**T**:**:**.******+00:00, is_pin_defined=False, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Update an Issuing Card `PATCH /v2/issuing-card/:id` Update the properties of an existing issuing card. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing card entity. | | `status` | OPTIONAL | Status to update the card to. Options: "active", "blocked". | | `rules` | OPTIONAL | New list of spending rule objects to apply to the card. | | `tags` | OPTIONAL | New array of strings to tag the card. | | `displayName` | OPTIONAL | New display name for the card. | | `pin` | OPTIONAL | Card PIN. Numeric string of 4 to 6 digits. Write-only — it is never returned; inform "expand=isPinDefined" to check whether a PIN is set. A pending physical card must receive a pin when you activate it (set status to "active"). | **Request** ```python import starkinfra card = starkinfra.issuingcard.update( "5715709195239424", status="blocked", pin="1234", tags=["blocked-reason: fraud"] ) print(card) ``` **Response** ```python IssuingCard( id=5715709195239424, holder_id=5155165527080960, holder_name=Tony Stark, holder_tax_id=012.345.678-90, holder_external_id=my-holder-id-1234, display_name=TONY STARK, product_id=654321, type=virtual, status=blocked, rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], street_line_1=Av. Faria Lima, 1844, street_line_2=10 andar, district=Itaim Bibi, city=Sao Paulo, state_code=SP, zip_code=01311-000, tags=['blocked-reason: fraud'], number=**** **** **** 1234, security_code=***, expiration=****-**-**T**:**:**.******+00:00, is_pin_defined=False, created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### Cancel an Issuing Card `DELETE /v2/issuing-card/:id` Cancel an issuing card. This action is irreversible. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing card entity to cancel. | **Request** ```python import starkinfra card = starkinfra.issuingcard.cancel("5715709195239424") print(card) ``` **Response** ```python IssuingCard( id=5715709195239424, holder_id=5155165527080960, holder_name=Tony Stark, holder_tax_id=012.345.678-90, holder_external_id=my-holder-id-1234, display_name=TONY STARK, product_id=654321, type=virtual, status=canceled, rules=[ IssuingRule( id=5155165527080960, name=General BRL, amount=100000, interval=day, currency_code=BRL, schedule=, purposes=[], categories=[], countries=[], methods=[], merchants=[] ) ], street_line_1=Av. Faria Lima, 1844, street_line_2=10 andar, district=Itaim Bibi, city=Sao Paulo, state_code=SP, zip_code=01311-000, tags=['department: tech', 'team: backend'], number=**** **** **** 1234, security_code=***, expiration=****-**-**T**:**:**.******+00:00, is_pin_defined=False, created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### List Issuing Card Logs `GET /v2/issuing-card/log` Get a paged list of issuing card logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `cardIds` | OPTIONAL | Array of card ids to filter logs. | | `ids` | OPTIONAL | List of strings to get specific log entities by ids. | **Request** ```python import starkinfra logs = starkinfra.issuingcard.log.query( limit=10, types=["blocked"] ) for log in logs: print(log) ``` **Response** ```python Log( id=6724771005489152, type=blocked, card=IssuingCard(id=5715709195239424, status=blocked), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Card Log `GET /v2/issuing-card/log/:id` Get a single issuing card log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingcard.log.get("6724771005489152") print(log) ``` **Response** ```python Log( id=6724771005489152, type=blocked, card=IssuingCard(id=5715709195239424, status=blocked), created=2022-01-01 00:00:00 ) ``` ## Issuing Design The Issuing Design resource represents the visual design of a physical card. Designs define the artwork, fonts, and layout used when embossing and printing cards. You can retrieve available designs and download their PDF templates. ### The Issuing Design object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing design. | | `name` | STRING | Name of the design. | | `type` | STRING | Design type. Options: "card", "envelope". | | `embosserIds` | LIST OF STRINGS | List of embosser ids that support this design. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Designs `GET /v2/issuing-design` Get a list of available issuing designs for your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra designs = starkinfra.issuingdesign.query(limit=10) for design in designs: print(design) ``` **Response** ```python IssuingDesign( id=5715709195239424, name=Standard Blue, embosser_ids=['6724771005489152'], type=card, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Design `GET /v2/issuing-design/:id` Get a single issuing design by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing design entity. | **Request** ```python import starkinfra design = starkinfra.issuingdesign.get("5715709195239424") print(design) ``` **Response** ```python IssuingDesign( id=5715709195239424, name=Standard Blue, embosser_ids=['6724771005489152'], type=card, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Design PDF `GET /v2/issuing-design/:id/pdf` Get the PDF file for a specific issuing design. This file can be used to preview the card layout. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing design entity. | **Request** ```python import starkinfra pdf = starkinfra.issuingdesign.pdf("5715709195239424") with open("design.pdf", "wb") as f: f.write(pdf) ``` **Response** ```python b'%PDF-1.4 ...' # Binary PDF content ``` ## Issuing Embossing Kit The Issuing Embossing Kit resource represents a kit used for embossing physical cards. Each kit defines the card design and packaging used during the card personalization process. ### The Issuing Embossing Kit object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing embossing kit. | | `name` | STRING | Name of the embossing kit. | | `designs` | LIST OF OBJECTS | List of objects referencing the designs that compose the kit. Each object contains the design id. Example: [{"id": "6284441486065664"}]. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Embossing Kits `GET /v2/issuing-embossing-kit` Get a list of available issuing embossing kits for your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. Example: "2022-01-20". | | `before` | OPTIONAL | Filter entities created before this date. Example: "2022-02-20". | | `designIds` | OPTIONAL | Filter by IssuingDesign ids. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra kits = starkinfra.issuingembossingkit.query(limit=10) for kit in kits: print(kit) ``` **Response** ```python IssuingEmbossingKit( id=5715709195239424, name=Standard Kit, designs=[ IssuingDesign( id=6284441486065664, name=None, embosser_ids=None, type=None, created=None, updated=None ), IssuingDesign( id=6284441486065665, name=None, embosser_ids=None, type=None, created=None, updated=None ) ], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Embossing Kit `GET /v2/issuing-embossing-kit/:id` Get a single issuing embossing kit by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing embossing kit entity. | **Request** ```python import starkinfra kit = starkinfra.issuingembossingkit.get("5715709195239424") print(kit) ``` **Response** ```python IssuingEmbossingKit( id=5715709195239424, name=Standard Kit, designs=[ IssuingDesign( id=6284441486065664, name=None, embosser_ids=None, type=None, created=None, updated=None ), IssuingDesign( id=6284441486065665, name=None, embosser_ids=None, type=None, created=None, updated=None ) ], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ## Issuing Stock The Issuing Stock resource tracks the inventory of physical card blanks available for embossing. Each stock entry is associated with a specific card design and holder type. Monitor your stock levels to ensure cards are available when needed. ### The Issuing Stock object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing stock. | | `designId` | STRING | Id of the IssuingDesign of the card blanks in stock. | | `embosserId` | STRING | Id of the embosser that holds this stock. | | `embosserName` | STRING | Name of the embosser that holds this stock. | | `balance` | INTEGER | Number of card blanks currently available in stock. Returned when "expand=balance" is informed in the request. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Stocks `GET /v2/issuing-stock` Get a list of issuing stocks in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `designIds` | OPTIONAL | List of strings to filter stocks by specific IssuingDesign ids. | | `embosserIds` | OPTIONAL | List of strings to filter stocks by specific embosser ids. | | `expand` | OPTIONAL | Fields to expand information on the response. Options: "balance". | **Request** ```python import starkinfra stocks = starkinfra.issuingstock.query(limit=10) for stock in stocks: print(stock) ``` **Response** ```python IssuingStock( id=5715709195239424, design_id=6724771005489152, embosser_id=7834882116598271, embosser_name=Stark Embosser, balance=500, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Stock `GET /v2/issuing-stock/:id` Get a single issuing stock entry by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing stock entity. | | `expand` | OPTIONAL | Fields to expand information on the response. Options: "balance". | **Request** ```python import starkinfra stock = starkinfra.issuingstock.get("5715709195239424") print(stock) ``` **Response** ```python IssuingStock( id=5715709195239424, design_id=6724771005489152, embosser_id=7834882116598271, embosser_name=Stark Embosser, balance=500, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Stock Logs `GET /v2/issuing-stock/log` Get a paged list of issuing stock logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `stockIds` | OPTIONAL | Array of stock ids to filter logs. | | `ids` | OPTIONAL | List of strings to get specific log entities by ids. | **Request** ```python import starkinfra logs = starkinfra.issuingstock.log.query( limit=10, types=["created"] ) for log in logs: print(log) ``` **Response** ```python Log( id=6724771005489152, type=created, stock=IssuingStock(id=5715709195239424, balance=500), count=10, created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Stock Log `GET /v2/issuing-stock/log/:id` Get a single issuing stock log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingstock.log.get("6724771005489152") print(log) ``` **Response** ```python Log( id=6724771005489152, type=created, stock=IssuingStock(id=5715709195239424, balance=500), count=10, created=2022-01-01 00:00:00 ) ``` ## Issuing Stock Rule The Issuing Stock Rule resource lets you register low-balance alerts for your card stocks. When the available count of an issuing stock falls below the configured minimum balance, the registered emails and phones are notified. Each issuing stock can have only one active rule at a time. ### The Issuing Stock Rule object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing stock rule. | | `minimumBalance` | INTEGER | Stock count threshold that triggers the alert. Example: 1000. | | `stockId` | STRING | Id of the IssuingStock monitored by this rule. | | `emails` | LIST OF STRINGS | List of email addresses notified when the rule is triggered. Max: 10. | | `phones` | LIST OF STRINGS | List of phone numbers notified when the rule is triggered. Max: 10. | | `tags` | LIST OF STRINGS | Array of strings to tag the entity for future queries. | | `status` | STRING | Current rule status. Options: "active", "canceled". | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Issuing Stock Rules `POST /v2/issuing-stock-rule` Use this route to register stock rules. Send a "rules" array where each element carries the parameters below. At least one email or phone must be informed per rule. **Parameters** | Name | Required | Description | | --- | --- | --- | | `minimumBalance` | REQUIRED | Stock count threshold that triggers the alert. Must be a positive integer. Example: 1000. | | `stockId` | REQUIRED | Id of the IssuingStock to monitor. | | `emails` | OPTIONAL | List of email addresses to notify. Max: 10. | | `phones` | OPTIONAL | List of phone numbers to notify. Max: 10. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra rules = starkinfra.issuingstockrule.create([ starkinfra.IssuingStockRule( minimum_balance=1000, stock_id="6724771005489152", emails=["aria@stark.com"], phones=["+5511999999999"], tags=["stock: black-card"] ) ]) for rule in rules: print(rule) ``` **Response** ```python IssuingStockRule( id=5715709195239424, minimum_balance=1000, stock_id=6724771005489152, emails=['aria@stark.com'], phones=['+5511999999999'], tags=['stock: black-card'], status=active, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Stock Rules `GET /v2/issuing-stock-rule` Get a list of issuing stock rules in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter entities by status. Options: "active", "canceled". | | `stockIds` | OPTIONAL | List of strings to get rules attached to specific IssuingStock ids. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `tags` | OPTIONAL | List of strings to filter entities by tags. | **Request** ```python import starkinfra rules = starkinfra.issuingstockrule.query( limit=10, status="active" ) for rule in rules: print(rule) ``` **Response** ```python IssuingStockRule( id=5715709195239424, minimum_balance=1000, stock_id=6724771005489152, emails=['aria@stark.com'], phones=['+5511999999999'], tags=['stock: black-card'], status=active, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Update an Issuing Stock Rule `PATCH /v2/issuing-stock-rule/:id` Update the properties of an existing issuing stock rule. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing stock rule entity. | | `minimumBalance` | OPTIONAL | New stock count threshold that triggers the alert. | | `emails` | OPTIONAL | New list of email addresses to notify. Max: 10. | | `phones` | OPTIONAL | New list of phone numbers to notify. Max: 10. | | `tags` | OPTIONAL | New array of strings to tag the entity. | **Request** ```python import starkinfra rule = starkinfra.issuingstockrule.update( "5715709195239424", minimum_balance=2000, emails=["aria@stark.com", "tony@stark.com"] ) print(rule) ``` **Response** ```python IssuingStockRule( id=5715709195239424, minimum_balance=2000, stock_id=6724771005489152, emails=['aria@stark.com', 'tony@stark.com'], phones=['+5511999999999'], tags=['stock: black-card'], status=active, created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### Cancel an Issuing Stock Rule `DELETE /v2/issuing-stock-rule/:id` Cancel an issuing stock rule. This action is irreversible. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing stock rule entity to cancel. | **Request** ```python import starkinfra rule = starkinfra.issuingstockrule.cancel("5715709195239424") print(rule) ``` **Response** ```python IssuingStockRule( id=5715709195239424, minimum_balance=2000, stock_id=6724771005489152, emails=['aria@stark.com', 'tony@stark.com'], phones=['+5511999999999'], tags=['stock: black-card'], status=canceled, created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ## Issuing Restock The Issuing Restock resource is used to request additional card blanks when your stock is running low. Each restock request specifies the quantity needed and the stock to replenish. Monitor the status of your restock requests through the log endpoints. ### The Issuing Restock object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing restock. | | `count` | INTEGER | Number of card blanks requested in this restock. | | `stockId` | STRING | Id of the IssuingStock to be replenished. | | `status` | STRING | Current restock status. Options: "created", "processing", "confirmed". | | `tags` | LIST OF STRINGS | Tags associated with the restock. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Issuing Restocks `POST /v2/issuing-restock` Use this route to create up to 100 new issuing restock requests at a time. **Parameters** | Name | Required | Description | | --- | --- | --- | | `count` | REQUIRED | Number of card blanks to request. Example: 100. | | `stockId` | REQUIRED | Id of the IssuingStock to be replenished. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra restocks = starkinfra.issuingrestock.create([ starkinfra.IssuingRestock( count=100, stock_id="5715709195239424" ) ]) for restock in restocks: print(restock) ``` **Response** ```python IssuingRestock( id=6724771005489152, count=100, stock_id=5715709195239424, status=created, tags=[], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Restocks `GET /v2/issuing-restock` Get a list of issuing restock requests in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter for status of retrieved entities. Options: "created", "processing", "confirmed". | | `stockIds` | OPTIONAL | List of IssuingStock ids to filter retrieved entities. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `tags` | OPTIONAL | List of strings to filter retrieved entities by tags. | **Request** ```python import starkinfra restocks = starkinfra.issuingrestock.query(limit=10) for restock in restocks: print(restock) ``` **Response** ```python IssuingRestock( id=6724771005489152, count=100, stock_id=5715709195239424, status=confirmed, tags=[], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Restock `GET /v2/issuing-restock/:id` Get a single issuing restock by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing restock entity. | **Request** ```python import starkinfra restock = starkinfra.issuingrestock.get("6724771005489152") print(restock) ``` **Response** ```python IssuingRestock( id=6724771005489152, count=100, stock_id=5715709195239424, status=confirmed, tags=[], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Restock Logs `GET /v2/issuing-restock/log` Get a paged list of issuing restock logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `restockIds` | OPTIONAL | Array of restock ids to filter logs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra logs = starkinfra.issuingrestock.log.query( limit=10, types=["confirmed"] ) for log in logs: print(log) ``` **Response** ```python Log( id=7834882116598271, type=confirmed, restock=IssuingRestock(id=6724771005489152, status=confirmed), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Restock Log `GET /v2/issuing-restock/log/:id` Get a single issuing restock log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingrestock.log.get("7834882116598271") print(log) ``` **Response** ```python Log( id=7834882116598271, type=confirmed, restock=IssuingRestock(id=6724771005489152, status=confirmed), created=2022-01-01 00:00:00 ) ``` ## Issuing Embossing Request The Issuing Embossing Request resource is used to initiate the personalization and delivery of a physical card. Each request specifies the card, kit, display name, and shipping address for card delivery. Track the embossing and shipping status through the log endpoints. ### The Issuing Embossing Request object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing embossing request. | | `cardId` | STRING | Id of the IssuingCard to be embossed. | | `kitId` | STRING | Id of the IssuingEmbossingKit to be used. | | `displayName1` | STRING | First line of the name to be printed on the card face. Example: "TONY STARK". | | `displayName2` | STRING | Second line of the name to be printed on the card face. | | `displayName3` | STRING | Third line of the name to be printed on the card face. | | `shippingCity` | STRING | City for card delivery. | | `shippingCountryCode` | STRING | Country code for card delivery. Example: "BRA". | | `shippingDistrict` | STRING | District for card delivery. | | `shippingService` | STRING | Shipping service type. Options: "loggi", "conveyor". | | `shippingStateCode` | STRING | State code for card delivery. Example: "SP". | | `shippingStreetLine1` | STRING | Primary street line for card delivery. | | `shippingStreetLine2` | STRING | Secondary street line for card delivery. | | `shippingTrackingNumber` | STRING | Tracking number for the card shipment. | | `shippingZipCode` | STRING | ZIP code for card delivery. Example: "01311-000". | | `embosserId` | STRING | Id of the embosser responsible for this request. | | `shippingPhone` | STRING | Phone number for delivery contact. Example: "+5511999999999". | | `status` | STRING | Current status of the embossing request. Options: "created", "processing", "success", "failed". | | `tags` | LIST OF STRINGS | Tags associated with the embossing request. | | `fee` | INTEGER | Fee charged in cents for the embossing request. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Issuing Embossing Requests `POST /v2/issuing-embossing-request` Use this route to create up to 100 new issuing embossing requests at a time. **Parameters** | Name | Required | Description | | --- | --- | --- | | `cardId` | REQUIRED | Id of the IssuingCard to be embossed. | | `kitId` | REQUIRED | Id of the IssuingEmbossingKit to use. | | `displayName1` | REQUIRED | First line of the name to be printed on the card. Example: "TONY STARK". | | `displayName2` | OPTIONAL | Second line of the name to be printed on the card. | | `displayName3` | OPTIONAL | Third line of the name to be printed on the card. | | `shippingCity` | REQUIRED | City for card delivery. | | `shippingCountryCode` | REQUIRED | Country code for card delivery. Example: "BRA". | | `shippingDistrict` | REQUIRED | District for card delivery. | | `shippingService` | REQUIRED | Shipping service type. Options: "loggi", "conveyor". | | `shippingStateCode` | REQUIRED | State code for card delivery. Example: "SP". | | `shippingStreetLine1` | REQUIRED | Primary street line for card delivery. | | `shippingStreetLine2` | REQUIRED | Secondary street line for card delivery. | | `shippingZipCode` | REQUIRED | ZIP code for card delivery. Example: "01311-000". | | `shippingTrackingNumber` | REQUIRED | Tracking number for the card shipment. | | `shippingPhone` | OPTIONAL | Phone number for delivery contact. Example: "+5511999999999". | | `embosserId` | OPTIONAL | Id of the embosser to handle this request. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra requests = starkinfra.issuingembossingrequest.create([ starkinfra.IssuingEmbossingRequest( card_id="5715709195239424", kit_id="6724771005489152", display_name_1="TONY STARK", shipping_city="Sao Paulo", shipping_country_code="BRA", shipping_district="Bela Vista", shipping_service="loggi", shipping_state_code="SP", shipping_street_line_1="Av. Paulista, 1000", shipping_street_line_2="Apto 101", shipping_tracking_number="BR1234567890", shipping_zip_code="01311-000", embosser_id="5656565656565656", tags=["department: tech"] ) ]) for request in requests: print(request) ``` **Response** ```python IssuingEmbossingRequest( id=7834882116598271, card_id=5715709195239424, kit_id=6724771005489152, display_name_1=TONY STARK, display_name_2=None, display_name_3=None, shipping_city=Sao Paulo, shipping_country_code=BRA, shipping_district=Bela Vista, shipping_phone=+5511999999999, shipping_service=loggi, shipping_state_code=SP, shipping_street_line_1=Av. Paulista, 1000, shipping_street_line_2=Apto 101, shipping_tracking_number=BR1234567890, shipping_zip_code=01311-000, embosser_id=5656565656565656, fee=0, status=created, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Embossing Requests `GET /v2/issuing-embossing-request` Get a list of issuing embossing requests in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter requests by the specified status. | | `cardIds` | OPTIONAL | List of IssuingCard ids to filter the retrieved entities. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra requests = starkinfra.issuingembossingrequest.query( limit=10, status="created" ) for request in requests: print(request) ``` **Response** ```python IssuingEmbossingRequest( id=7834882116598271, card_id=5715709195239424, kit_id=6724771005489152, display_name_1=TONY STARK, display_name_2=None, display_name_3=None, shipping_city=Sao Paulo, shipping_country_code=BRA, shipping_district=Bela Vista, shipping_phone=+5511999999999, shipping_service=loggi, shipping_state_code=SP, shipping_street_line_1=Av. Paulista, 1000, shipping_street_line_2=Apto 101, shipping_tracking_number=BR1234567890, shipping_zip_code=01311-000, embosser_id=5656565656565656, fee=0, status=created, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Embossing Request `GET /v2/issuing-embossing-request/:id` Get a single issuing embossing request by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing embossing request entity. | **Request** ```python import starkinfra request = starkinfra.issuingembossingrequest.get("7834882116598271") print(request) ``` **Response** ```python IssuingEmbossingRequest( id=7834882116598271, card_id=5715709195239424, kit_id=6724771005489152, display_name_1=TONY STARK, display_name_2=None, display_name_3=None, shipping_city=Sao Paulo, shipping_country_code=BRA, shipping_district=Bela Vista, shipping_phone=+5511999999999, shipping_service=loggi, shipping_state_code=SP, shipping_street_line_1=Av. Paulista, 1000, shipping_street_line_2=Apto 101, shipping_tracking_number=BR1234567890, shipping_zip_code=01311-000, embosser_id=5656565656565656, fee=0, status=created, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Embossing Request Logs `GET /v2/issuing-embossing-request/log` Get a paged list of issuing embossing request logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `requestIds` | OPTIONAL | Array of embossing request ids to filter logs. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra logs = starkinfra.issuingembossingrequest.log.query( limit=10, types=["sent"] ) for log in logs: print(log) ``` **Response** ```python Log( id=8945993227707382, type=sent, request=IssuingEmbossingRequest(id=7834882116598271, status=processing), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Embossing Request Log `GET /v2/issuing-embossing-request/log/:id` Get a single issuing embossing request log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingembossingrequest.log.get("8945993227707382") print(log) ``` **Response** ```python Log( id=8945993227707382, type=sent, request=IssuingEmbossingRequest(id=7834882116598271, status=processing), created=2022-01-01 00:00:00 ) ``` ## Issuing Token The Issuing Token resource represents a tokenized version of a card stored in a digital wallet. Tokens allow cardholders to make purchases using digital wallets without exposing the actual card number. You can manage token status and monitor token activity through the log endpoints. ### The Issuing Token object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing token. | | `cardId` | STRING | Id of the IssuingCard this token is associated with. | | `walletId` | STRING | Id of the digital wallet where the token is stored. | | `walletName` | STRING | Name of the digital wallet. Example: "Apple Pay", "Google Pay". | | `merchantId` | STRING | Id of the merchant if the token is merchant-specific. | | `externalId` | STRING | Unique external identifier of the token. | | `walletDeviceScore` | FLOAT | Device score informed by the digital wallet. | | `walletAccountScore` | FLOAT | Account score informed by the digital wallet. | | `status` | STRING | Current token status. Options: "active", "blocked", "canceled", "frozen", "pending", "denied". | | `tags` | LIST OF STRINGS | Tags associated with the token. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Tokens `GET /v2/issuing-token` Get a list of issuing tokens in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter tokens by the specified status. | | `cardIds` | OPTIONAL | Filter tokens by card ids. | | `externalIds` | OPTIONAL | Filter tokens by external ids. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra tokens = starkinfra.issuingtoken.query( limit=10, status="active" ) for token in tokens: print(token) ``` **Response** ```python IssuingToken( id=5715709195239424, card_id=6724771005489152, wallet_id=apple, wallet_name=Apple Pay, merchant_id=5656565656565656, external_id=DNITHE301234567890123456789012345678, wallet_device_score=None, wallet_account_score=None, status=active, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Token `GET /v2/issuing-token/:id` Get a single issuing token by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing token entity. | **Request** ```python import starkinfra token = starkinfra.issuingtoken.get("5715709195239424") print(token) ``` **Response** ```python IssuingToken( id=5715709195239424, card_id=6724771005489152, wallet_id=apple, wallet_name=Apple Pay, merchant_id=5656565656565656, external_id=DNITHE301234567890123456789012345678, wallet_device_score=None, wallet_account_score=None, status=active, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Update an Issuing Token `PATCH /v2/issuing-token/:id` Update the status or tags of an existing issuing token. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing token entity. | | `status` | OPTIONAL | Status to update the token to. Options: "active", "blocked". | | `tags` | OPTIONAL | New array of strings to tag the token. | **Request** ```python import starkinfra token = starkinfra.issuingtoken.update( "5715709195239424", status="blocked", tags=["blocked-reason: lost"] ) print(token) ``` **Response** ```python IssuingToken( id=5715709195239424, card_id=6724771005489152, wallet_id=apple, wallet_name=Apple Pay, merchant_id=5656565656565656, external_id=DNITHE301234567890123456789012345678, wallet_device_score=None, wallet_account_score=None, status=blocked, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### Cancel an Issuing Token `DELETE /v2/issuing-token/:id` Cancel an issuing token. This action is irreversible. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing token entity to cancel. | **Request** ```python import starkinfra token = starkinfra.issuingtoken.cancel("5715709195239424") print(token) ``` **Response** ```python IssuingToken( id=5715709195239424, card_id=6724771005489152, wallet_id=apple, wallet_name=Apple Pay, merchant_id=5656565656565656, external_id=DNITHE301234567890123456789012345678, wallet_device_score=None, wallet_account_score=None, status=canceled, tags=['department: tech'], created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### List Issuing Token Logs `GET /v2/issuing-token/log` Get a paged list of issuing token logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `tokenIds` | OPTIONAL | Array of token ids to filter logs. | | `tokenTags` | OPTIONAL | Filter logs by the tags of their tokens. | **Request** ```python import starkinfra logs = starkinfra.issuingtoken.log.query( limit=10, types=["created"] ) for log in logs: print(log) ``` **Response** ```python Log( id=6724771005489152, type=created, errors=[], token=IssuingToken(id=5715709195239424, status=active), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Token Log `GET /v2/issuing-token/log/:id` Get a single issuing token log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingtoken.log.get("6724771005489152") print(log) ``` **Response** ```python Log( id=6724771005489152, type=created, errors=[], token=IssuingToken(id=5715709195239424, status=active), created=2022-01-01 00:00:00 ) ``` ## Issuing Token Request The Issuing Token Request resource is used to initiate the tokenization of a card for digital wallets. When a cardholder attempts to add a card to a digital wallet (e.g., Apple Pay, Google Pay), a token request is generated. Process the token request to approve or decline the card tokenization. ### The Issuing Token Request object **Attributes** | Name | Type | Description | | --- | --- | --- | | `cardId` | STRING | Id of the IssuingCard to be tokenized. | | `walletId` | STRING | Id of the digital wallet requesting tokenization. Options: "apple", "google", "merchant". | | `methodCode` | STRING | Provisioning method. Options: "app", "manual". | | `content` | STRING | Processed content of the tokenization request. | | `signature` | STRING | Digital signature of the content. | | `metadata` | OBJECT | Additional data passed along with the tokenization request. | ### Create an Issuing Token Request `POST /v2/issuing-token-request` Use this route to process a tokenization request from a digital wallet provider. **Parameters** | Name | Required | Description | | --- | --- | --- | | `cardId` | REQUIRED | Id of the IssuingCard to be tokenized. | | `walletId` | REQUIRED | Id of the digital wallet making the tokenization request. Options: "apple", "google", "merchant". | | `methodCode` | REQUIRED | Provisioning method. Options: "app", "manual". | | `metadata` | OPTIONAL | Additional data to pass along with the tokenization request. | **Request** ```python import starkinfra token_request = starkinfra.issuingtokenrequest.create( starkinfra.IssuingTokenRequest( card_id="5715709195239424", wallet_id="apple", method_code="app" ) ) print(token_request) ``` **Response** ```python IssuingTokenRequest( card_id=5715709195239424, wallet_id=apple, method_code=app, content=eyJhcHBsaWNhdGlvbklkIjoiY29tLmFwcGxl..., signature=MEUCIQDp3GTGqsqDeKLN9aLhxAZ..., metadata={} ) ``` ## Issuing Token Design The Issuing Token Design resource represents the visual design used to display a tokenized card in a digital wallet. Designs include the card artwork shown in the wallet app. You can retrieve available token designs and download their PDF files. ### The Issuing Token Design object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing token design. | | `name` | STRING | Name of the token design. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Token Designs `GET /v2/issuing-token-design` Get a list of available issuing token designs for your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra designs = starkinfra.issuingtokendesign.query(limit=10) for design in designs: print(design) ``` **Response** ```python IssuingTokenDesign( id=5715709195239424, name=Apple Pay Card Art, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Token Design `GET /v2/issuing-token-design/:id` Get a single issuing token design by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing token design entity. | **Request** ```python import starkinfra design = starkinfra.issuingtokendesign.get("5715709195239424") print(design) ``` **Response** ```python IssuingTokenDesign( id=5715709195239424, name=Apple Pay Card Art, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Token Design PDF `GET /v2/issuing-token-design/:id/pdf` Get the PDF file for a specific issuing token design. This file is used to represent the card in digital wallets. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing token design entity. | **Request** ```python import starkinfra pdf = starkinfra.issuingtokendesign.pdf("5715709195239424") with open("token-design.pdf", "wb") as f: f.write(pdf) ``` **Response** ```python b'%PDF-1.4 ...' # Binary PDF content ``` ## Issuing Invoice The Issuing Invoice resource is used to add funds to your issuing balance. Generate a Pix invoice (brcode) to receive deposits directly into your issuing wallet. Once paid, the funds become available in your issuing balance for card spending. ### The Issuing Invoice object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing invoice. | | `amount` | INTEGER | Invoice amount in cents. Example: 10000 (R$100.00). | | `taxId` | STRING | Payer CPF (11 digits) or CNPJ (14 digits). | | `name` | STRING | Payer full name. | | `tags` | LIST OF STRINGS | Tags associated with the invoice. | | `metadata` | OBJECT | Free-form map you can attach to the invoice. | | `status` | STRING | Current invoice status. Options: "created", "paid", "overdue", "expired", "canceled". | | `brcode` | STRING | Pix brcode string for payment. | | `due` | STRING | Invoice due datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `link` | STRING | Public URL to the invoice payment page. | | `issuingTransactionId` | STRING | Id of the IssuingTransaction created when the invoice is paid. Null until payment. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an Issuing Invoice `POST /v2/issuing-invoice` Use this route to create a new issuing invoice to fund your issuing balance. **Parameters** | Name | Required | Description | | --- | --- | --- | | `amount` | REQUIRED | Amount in cents to be deposited. Example: 10000 (R$100.00). | | `taxId` | OPTIONAL | Payer CPF or CNPJ. Example: "012.345.678-90". | | `name` | OPTIONAL | Payer full name. Example: "Tony Stark". | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | | `metadata` | OPTIONAL | Free-form map you can attach to the invoice. | **Request** ```python import starkinfra invoice = starkinfra.issuinginvoice.create( starkinfra.IssuingInvoice( amount=10000, tax_id="012.345.678-90", name="Tony Stark", tags=["department: tech"] ) ) print(invoice) ``` **Response** ```python IssuingInvoice( id=5715709195239424, amount=10000, tax_id=012.345.678-90, name=Tony Stark, tags=['department: tech'], metadata={}, status=created, brcode=00020101021226870014br.gov.bcb.pix2565..., due=2022-02-10 00:00:00, link=https://sandbox.api.starkinfra.com/invoicelink/5715709195239424, issuing_transaction_id=None, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Invoices `GET /v2/issuing-invoice` Get a list of issuing invoices in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter invoices by the specified status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | **Request** ```python import starkinfra invoices = starkinfra.issuinginvoice.query( limit=10, status="created" ) for invoice in invoices: print(invoice) ``` **Response** ```python IssuingInvoice( id=5715709195239424, amount=10000, tax_id=012.345.678-90, name=Tony Stark, tags=['department: tech'], metadata={}, status=created, brcode=00020101021226870014br.gov.bcb.pix2565..., due=2022-02-10 00:00:00, link=https://sandbox.api.starkinfra.com/invoicelink/5715709195239424, issuing_transaction_id=None, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Invoice `GET /v2/issuing-invoice/:id` Get a single issuing invoice by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing invoice entity. | **Request** ```python import starkinfra invoice = starkinfra.issuinginvoice.get("5715709195239424") print(invoice) ``` **Response** ```python IssuingInvoice( id=5715709195239424, amount=10000, tax_id=012.345.678-90, name=Tony Stark, tags=['department: tech'], metadata={}, status=created, brcode=00020101021226870014br.gov.bcb.pix2565..., due=2022-02-10 00:00:00, link=https://sandbox.api.starkinfra.com/invoicelink/5715709195239424, issuing_transaction_id=None, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Invoice Logs `GET /v2/issuing-invoice/log` Get a paged list of issuing invoice logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `ids` | OPTIONAL | Array of invoice ids to filter logs. | **Request** ```python import starkinfra logs = starkinfra.issuinginvoice.log.query( limit=10, types=["paid"] ) for log in logs: print(log) ``` **Response** ```python Log( id=6724771005489152, type=paid, invoice=IssuingInvoice(id=5715709195239424, amount=10000, status=paid), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Invoice Log `GET /v2/issuing-invoice/log/:id` Get a single issuing invoice log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuinginvoice.log.get("6724771005489152") print(log) ``` **Response** ```python Log( id=6724771005489152, type=paid, invoice=IssuingInvoice(id=5715709195239424, amount=10000, status=paid), created=2022-01-01 00:00:00 ) ``` ## Issuing Billing Invoice The Issuing Billing Invoice resource represents the invoice that settles the postpaid usage of your issuing operation in a billing period. Each invoice consolidates the purchases and withdrawals settled in the billing period and can be paid via its brcode or link. Fine and interest are applied when the invoice is paid after the due date. ### The Issuing Billing Invoice object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing billing invoice. | | `taxId` | STRING | Tax id (CPF or CNPJ) of the invoice payer. Example: "012.345.678-90". | | `name` | STRING | Name of the invoice payer. | | `amount` | INTEGER | Current invoice amount in cents, including fine and interest when overdue. Example: 100000 (= R$ 1,000.00). | | `nominalAmount` | INTEGER | Original invoice amount in cents, before fine and interest. Example: 100000 (= R$ 1,000.00). | | `fine` | FLOAT | Fine percentage applied when paid after the due date. Example: 2.0. | | `interest` | FLOAT | Monthly interest percentage applied when paid after the due date. Example: 1.0. | | `status` | STRING | Current invoice status. Options: "created", "pending", "overdue", "expired", "paid". | | `brcode` | STRING | Pix BR Code that can be used to pay the invoice. | | `link` | STRING | Link to the invoice payment page. | | `due` | STRING | Invoice due datetime. Example: "2022-02-10T00:00:00.000000+00:00". | | `start` | STRING | Start datetime of the billing period. Example: "2022-01-01T00:00:00.000000+00:00". | | `end` | STRING | End datetime of the billing period. Example: "2022-01-31T23:59:59.999999+00:00". | | `created` | STRING | Creation datetime. Example: "2022-02-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-02-01T00:00:00.000000+00:00". | ### List Issuing Billing Invoices `GET /v2/issuing-billing-invoice` Get a list of issuing billing invoices in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter entities by status. Options: "created", "pending", "overdue", "expired", "paid". | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra from datetime import date billing_invoices = starkinfra.issuingbillinginvoice.query( after=date(2023, 1, 1), before=date(2024, 3, 1), limit=10 ) for billing_invoice in billing_invoices: print(billing_invoice) ``` **Response** ```python IssuingBillingInvoice( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, fine=2.0, interest=1.0, status=pending, amount=100000, nominal_amount=100000, brcode=00020101021226930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/d6a916beba1c41a5bbe31d63a93553c35204000053039865802BR5925Stark Bank S.A.6009Sao Paulo62070503***6304811B, link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978, due=2022-02-10 00:00:00, start=2022-01-01 00:00:00, end=2022-01-31 23:59:59, created=2022-02-01 00:00:00, updated=2022-02-01 00:00:00 ) ``` ### Get an Issuing Billing Invoice `GET /v2/issuing-billing-invoice/:id` Get a single issuing billing invoice by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing billing invoice entity. | **Request** ```python import starkinfra billing_invoice = starkinfra.issuingbillinginvoice.get("5715709195239424") print(billing_invoice) ``` **Response** ```python IssuingBillingInvoice( id=5715709195239424, name=Tony Stark, tax_id=012.345.678-90, fine=2.0, interest=1.0, status=pending, amount=100000, nominal_amount=100000, brcode=00020101021226930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/d6a916beba1c41a5bbe31d63a93553c35204000053039865802BR5925Stark Bank S.A.6009Sao Paulo62070503***6304811B, link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978, due=2022-02-10 00:00:00, start=2022-01-01 00:00:00, end=2022-01-31 23:59:59, created=2022-02-01 00:00:00, updated=2022-02-01 00:00:00 ) ``` ## Issuing Billing Transaction The Issuing Billing Transaction resource represents an entry that composes an issuing billing invoice. Each purchase or withdrawal settled in a billing period generates billing transactions, including the installments of installment purchases. ### The Issuing Billing Transaction object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing billing transaction. | | `installment` | INTEGER | Number of this installment. Example: 1. | | `installmentCount` | INTEGER | Total number of installments of the source purchase. Example: 3. | | `amount` | INTEGER | Transaction amount in cents. Example: 30000 (= R$ 300.00). | | `balance` | INTEGER | Invoice balance in cents after this transaction. | | `source` | STRING | Entity that originated the transaction. Example: "issuing-purchase/5155165527080960". | | `externalId` | STRING | Unique external identifier of the transaction. | | `description` | STRING | Transaction description, usually the merchant name. | | `cardEnding` | STRING | Last 4 digits of the card that originated the transaction. Example: "1234". | | `holderName` | STRING | Name of the holder of the card that originated the transaction. | | `tax` | INTEGER | IOF amount in cents applied to the transaction. | | `rate` | FLOAT | Conversion rate applied to international transactions. | | `merchantAmount` | INTEGER | Amount in cents in the merchant currency. Example: 30000. | | `merchantCurrencyCode` | STRING | Currency code of the merchant amount. Example: "BRL". | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Billing Transactions `GET /v2/issuing-billing-transaction` Get a list of issuing billing transactions in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `invoiceId` | OPTIONAL | Filter transactions that compose a specific IssuingBillingInvoice. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `tags` | OPTIONAL | List of strings to filter entities by tags. | **Request** ```python import starkinfra transactions = starkinfra.issuingbillingtransaction.query( limit=10, invoice_id="5715709195239424" ) for transaction in transactions: print(transaction) ``` **Response** ```python IssuingBillingTransaction( id=5715709195239424, installment=1, installment_count=3, amount=30000, balance=60000, source=issuing-purchase/5155165527080960, external_id=5155165527080960-1, description=Stark Coffee Shop, card_ending=1234, holder_name=Tony Stark, tax=0, rate=1.0, merchant_amount=30000, merchant_currency_code=BRL, created=2022-01-01 00:00:00 ) ``` ## Issuing Purchase The Issuing Purchase resource represents a purchase transaction made with an issuing card. Purchases are created when a cardholder makes a payment at a merchant using an issued card. You can list, retrieve, and update purchases, as well as monitor purchase events through the log endpoints. ### The Issuing Purchase object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing purchase. | | `productId` | STRING | Id of the IssuingProduct of the card used in the purchase. | | `holderName` | STRING | Name of the cardholder. | | `cardId` | STRING | Id of the IssuingCard used for the purchase. | | `amount` | INTEGER | Purchase amount in cents in the issuer currency. | | `tax` | INTEGER | Tax amount in cents charged on the purchase. | | `issuerAmount` | INTEGER | Amount in cents in the issuer currency. | | `issuerCurrencyCode` | STRING | ISO 4217 currency code of the issuer. Example: "BRL". | | `issuerCurrencySymbol` | STRING | Currency symbol of the issuer. Example: "R$". | | `merchantAmount` | INTEGER | Amount in cents in the merchant currency. | | `merchantCurrencyCode` | STRING | ISO 4217 currency code of the merchant. Example: "USD". | | `merchantCurrencySymbol` | STRING | Currency symbol of the merchant. Example: "$". | | `merchantCategoryCode` | STRING | Merchant category code (MCC) for the purchase. | | `merchantCategoryNumber` | INTEGER | MCC number of the merchant category. Example: 5814. | | `merchantCategoryType` | STRING | Type of the merchant category. Example: "food". | | `merchantCountryCode` | STRING | ISO 3166 country code of the merchant. Example: "BRA". | | `acquirerId` | STRING | Id of the payment acquirer. | | `merchantId` | STRING | Id of the merchant. | | `merchantName` | STRING | Name of the merchant. | | `merchantFee` | INTEGER | Merchant fee in cents. | | `walletId` | STRING | Id of the digital wallet used if this was a token purchase. | | `methodCode` | STRING | Payment method code. Options: "chip", "token", "server", "manual", "magstripe", "contactless". | | `score` | FLOAT | Fraud risk score from 0 to 1. Higher values indicate higher risk. | | `endToEndId` | STRING | End-to-end transaction identifier. | | `tags` | LIST OF STRINGS | Tags associated with the purchase. | | `zipCode` | STRING | ZIP code of the merchant location. | | `issuingTransactionIds` | LIST OF STRINGS | Ids of the IssuingTransactions linked to this purchase. | | `purpose` | STRING | Purchase purpose. Options: "purchase", "withdrawal", "verification", "purchaseRefund", "cashbackPurchase", "paymentTransaction". | | `installmentCount` | INTEGER | Number of installments of the purchase. Example: 1. | | `cardEnding` | STRING | Last 4 digits of the card number used. | | `metadata` | OBJECT | Additional data related to the purchase, such as the authorizationId. | | `description` | STRING | Purchase description provided by the merchant. | | `confirmed` | STRING | Confirmation datetime. Null until the purchase is confirmed. | | `status` | STRING | Current purchase status. Options: "approved", "canceled", "denied", "confirmed", "voided". | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Purchases `GET /v2/issuing-purchase` Get a list of issuing purchases in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `status` | OPTIONAL | Filter purchases by the specified status. | | `cardIds` | OPTIONAL | Filter purchases by card ids. | | `holderIds` | OPTIONAL | Filter purchases by holder ids. | | `endToEndIds` | OPTIONAL | Filter purchases by their end-to-end transaction ids. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | **Request** ```python import starkinfra purchases = starkinfra.issuingpurchase.query( limit=10, status="approved" ) for purchase in purchases: print(purchase) ``` **Response** ```python IssuingPurchase( id=5715709195239424, holder_name=Tony Stark, product_id=654321, card_id=7834882116598271, card_ending=1234, purpose=purchase, installment_count=1, amount=5000, tax=0, issuer_amount=5000, issuer_currency_code=BRL, issuer_currency_symbol=R$, merchant_amount=5000, merchant_currency_code=BRL, merchant_currency_symbol=R$, merchant_category_code=fastFoodRestaurants, merchant_category_number=5814, merchant_category_type=food, merchant_country_code=BRA, acquirer_id=5656565656565656, merchant_id=5656565656565656, merchant_name=Stark Store, merchant_fee=0, wallet_id=None, method_code=chip, score=0.9775689825217906, end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0, tags=[], issuing_transaction_ids=['5155165527080960'], status=approved, description=, metadata={}, zip_code=01311-000, confirmed=2022-01-01 00:00:02, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Purchase `GET /v2/issuing-purchase/:id` Get a single issuing purchase by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing purchase entity. | **Request** ```python import starkinfra purchase = starkinfra.issuingpurchase.get("5715709195239424") print(purchase) ``` **Response** ```python IssuingPurchase( id=5715709195239424, holder_name=Tony Stark, product_id=654321, card_id=7834882116598271, card_ending=1234, purpose=purchase, installment_count=1, amount=5000, tax=0, issuer_amount=5000, issuer_currency_code=BRL, issuer_currency_symbol=R$, merchant_amount=5000, merchant_currency_code=BRL, merchant_currency_symbol=R$, merchant_category_code=fastFoodRestaurants, merchant_category_number=5814, merchant_category_type=food, merchant_country_code=BRA, acquirer_id=5656565656565656, merchant_id=5656565656565656, merchant_name=Stark Store, merchant_fee=0, wallet_id=None, method_code=chip, score=0.9775689825217906, end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0, tags=[], issuing_transaction_ids=['5155165527080960'], status=approved, description=, metadata={}, zip_code=01311-000, confirmed=2022-01-01 00:00:02, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Update an Issuing Purchase `PATCH /v2/issuing-purchase/:id` Update the tags of an existing issuing purchase. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing purchase entity. | | `tags` | OPTIONAL | New array of strings to tag the purchase. | | `description` | OPTIONAL | New description for the purchase. Max of 140 characters. | **Request** ```python import starkinfra purchase = starkinfra.issuingpurchase.update( "5715709195239424", tags=["reconciled", "month: january"] ) print(purchase) ``` **Response** ```python IssuingPurchase( id=5715709195239424, holder_name=Tony Stark, product_id=654321, card_id=7834882116598271, card_ending=1234, purpose=purchase, installment_count=1, amount=5000, tax=0, issuer_amount=5000, issuer_currency_code=BRL, issuer_currency_symbol=R$, merchant_amount=5000, merchant_currency_code=BRL, merchant_currency_symbol=R$, merchant_category_code=fastFoodRestaurants, merchant_category_number=5814, merchant_category_type=food, merchant_country_code=BRA, acquirer_id=5656565656565656, merchant_id=5656565656565656, merchant_name=Stark Store, merchant_fee=0, wallet_id=None, method_code=chip, score=0.9775689825217906, end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0, tags=['reconciled', 'month: january'], issuing_transaction_ids=['5155165527080960'], status=approved, description=, metadata={}, zip_code=01311-000, confirmed=2022-01-01 00:00:02, created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### List Issuing Purchase Logs `GET /v2/issuing-purchase/log` Get a paged list of issuing purchase logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `types` | OPTIONAL | Filter logs by log types. | | `purchaseIds` | OPTIONAL | Array of purchase ids to filter logs. | **Request** ```python import starkinfra logs = starkinfra.issuingpurchase.log.query( limit=10, types=["approved"] ) for log in logs: print(log) ``` **Response** ```python Log( id=6724771005489152, type=approved, purchase=IssuingPurchase(id=5715709195239424, amount=5000, status=approved), created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Purchase Log `GET /v2/issuing-purchase/log/:id` Get a single issuing purchase log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | **Request** ```python import starkinfra log = starkinfra.issuingpurchase.log.get("6724771005489152") print(log) ``` **Response** ```python Log( id=6724771005489152, type=approved, purchase=IssuingPurchase(id=5715709195239424, amount=5000, status=approved), created=2022-01-01 00:00:00 ) ``` ## Issuing Preview Installment The Issuing Preview Installment resource represents an upcoming installment of an installment purchase that has not been billed yet. Use it to preview the amounts that will compose your future issuing billing invoices. ### The Issuing Preview Installment object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing preview installment. | | `description` | STRING | Installment description, usually the merchant name. | | `amount` | INTEGER | Installment amount in cents. Example: 30000 (= R$ 300.00). | | `totalAmount` | INTEGER | Total amount in cents of the source purchase. Example: 90000 (= R$ 900.00). | | `source` | STRING | Entity that originated the installment. Example: "issuing-purchase/5155165527080960". | | `number` | INTEGER | Number of this installment. Example: 2. | | `count` | INTEGER | Total number of installments of the source purchase. Example: 3. | | `due` | STRING | Datetime when the installment will be billed. Example: "2022-02-01T00:00:00.000000+00:00". | | `tags` | LIST OF STRINGS | Array of strings to tag the entity for future queries. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Preview Installments `GET /v2/issuing-preview-installment` Get a list of issuing preview installments in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `sort` | OPTIONAL | Sort order for the results. Options: "created", "-created", "due", "-due". Default: "-created". | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `tags` | OPTIONAL | List of strings to filter entities by tags. | **Request** ```python import starkinfra installments = starkinfra.issuingpreviewinstallment.query( limit=10, sort="due" ) for installment in installments: print(installment) ``` **Response** ```python IssuingPreviewInstallment( id=6724771005489152, description=Stark Coffee Shop, amount=30000, total_amount=90000, source=issuing-purchase/5155165527080960, number=2, count=3, due=2022-02-01 00:00:00, tags=[], created=2022-01-01 00:00:00 ) ``` ## Issuing Transaction The Issuing Transaction resource represents a change in your issuing balance. Each purchase, invoice payment, withdrawal, or fee generates an issuing transaction. Use transactions to reconcile your issuing balance and understand fund movements. ### The Issuing Transaction object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing transaction. | | `amount` | INTEGER | Transaction amount in cents. Positive for credits, negative for debits. | | `balance` | INTEGER | Issuing balance in cents after this transaction. | | `description` | STRING | Description of the transaction. | | `source` | STRING | Source entity that generated this transaction. | | `tags` | LIST OF STRINGS | Tags associated with the transaction. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### List Issuing Transactions `GET /v2/issuing-transaction` Get a list of issuing transactions in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `externalIds` | OPTIONAL | List of strings to get specific entities by their external ids. | | `source` | OPTIONAL | Filter entities by the source entity that generated the transaction. | **Request** ```python import starkinfra transactions = starkinfra.issuingtransaction.query( limit=10, after="2022-01-01", before="2022-12-31", tags=["tony", "stark"] ) for transaction in transactions: print(transaction) ``` **Response** ```python IssuingTransaction( id=5715709195239424, amount=-1500, balance=5000000, description=Issuing purchase 6724771005489152, source=issuingPurchase/6724771005489152, tags=['tony', 'stark'], created=2022-01-01 00:00:00 ) ``` ### Get an Issuing Transaction `GET /v2/issuing-transaction/:id` Get a single issuing transaction by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing transaction entity. | **Request** ```python import starkinfra transaction = starkinfra.issuingtransaction.get("5715709195239424") print(transaction) ``` **Response** ```python IssuingTransaction( id=5715709195239424, amount=-1500, balance=5000000, description=Issuing purchase 6724771005489152, source=issuingPurchase/6724771005489152, tags=['tony', 'stark'], created=2022-01-01 00:00:00 ) ``` ## Issuing Withdrawal The Issuing Withdrawal resource is used to transfer funds from your issuing balance back to your main balance. Use withdrawals to move excess funds from your issuing wallet to your regular Stark Infra account. ### The Issuing Withdrawal object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique identifier for the issuing withdrawal. | | `amount` | INTEGER | Amount in cents to be withdrawn. Example: 10000 (R$100.00). | | `externalId` | STRING | Your unique identifier for this withdrawal. Must be unique per workspace to prevent duplicates. | | `description` | STRING | Description of the withdrawal. | | `tags` | LIST OF STRINGS | Tags associated with the withdrawal. | | `transactionId` | STRING | Id of the bank transaction linked to this withdrawal. | | `issuingTransactionId` | STRING | Id of the issuing transaction linked to this withdrawal. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an Issuing Withdrawal `POST /v2/issuing-withdrawal` Use this route to create a new issuing withdrawal and move funds from your issuing balance. **Parameters** | Name | Required | Description | | --- | --- | --- | | `amount` | REQUIRED | Amount in cents to withdraw. The minimum is 0, so any non-negative amount is accepted. Example: 10000 (R$100.00). | | `externalId` | REQUIRED | Your unique identifier for this withdrawal, used to prevent duplicates. Example: "withdrawal-2024-001". | | `description` | REQUIRED | Description of the withdrawal purpose. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | **Request** ```python import starkinfra withdrawal = starkinfra.issuingwithdrawal.create( starkinfra.IssuingWithdrawal( amount=10000, external_id="withdrawal-2022-001", description="Excess funds withdrawal", tags=["tony", "stark"] ) ) print(withdrawal) ``` **Response** ```python IssuingWithdrawal( id=5715709195239424, amount=10000, external_id=withdrawal-2022-001, description=Excess funds withdrawal, tags=['tony', 'stark'], transaction_id=6724771005489152, issuing_transaction_id=7834882116598271, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### List Issuing Withdrawals `GET /v2/issuing-withdrawal` Get a list of issuing withdrawals in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `externalIds` | OPTIONAL | List of strings to get specific entities by their external ids. | **Request** ```python import starkinfra withdrawals = starkinfra.issuingwithdrawal.query( limit=10, after="2022-01-01", before="2022-12-31", tags=["tony", "stark"] ) for withdrawal in withdrawals: print(withdrawal) ``` **Response** ```python IssuingWithdrawal( id=5715709195239424, amount=10000, external_id=withdrawal-2022-001, description=Excess funds withdrawal, tags=['tony', 'stark'], transaction_id=6724771005489152, issuing_transaction_id=7834882116598271, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get an Issuing Withdrawal `GET /v2/issuing-withdrawal/:id` Get a single issuing withdrawal by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the issuing withdrawal entity. | **Request** ```python import starkinfra withdrawal = starkinfra.issuingwithdrawal.get("5715709195239424") print(withdrawal) ``` **Response** ```python IssuingWithdrawal( id=5715709195239424, amount=10000, external_id=withdrawal-2022-001, description=Excess funds withdrawal, tags=['tony', 'stark'], transaction_id=6724771005489152, issuing_transaction_id=7834882116598271, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ## Card Method The Card Method resource is used to query the card purchase methods available in the Stark Infra API. Card Method codes are used to define purchase method filters in the IssuingRules of your [Issuing Holder](#issuing-holder) resource and [Issuing Card](#issuing-card) resource. Not every method can be used in every rule: a rule on a virtual card accepts only the "token", "server", "manual" and "contactless" codes, while a rule on a physical card accepts all of them. **Note:** Card Methods are never created by you. They are an enum served by the API, so this resource is query-only. ### The Card Method object **Attributes** | Name | Type | Description | | --- | --- | --- | | `code` | STRING | Method's code. Options: "chip", "token", "server", "manual", "magstripe", "contactless". Example: "token". | | `name` | STRING | Method's name, translated to the language of the Accept-Language header. Example: "token". | | `number` | STRING | Method's number. Example: "81". | ### List Card Methods `GET /v2/card-method` Use this route to list the card purchase methods available in the Stark Infra API. **NOTE:** This route returns the full enum in a single response. It is not paginated, so it accepts no limit or cursor parameters and returns no cursor. **Parameters** | Name | Required | Description | | --- | --- | --- | | `search` | OPTIONAL | Keyword to search for code, name or number. The match is case- and accent-insensitive. Example: "token". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra methods = starkinfra.cardmethod.query( search="token" ) for method in methods: print(method) ``` **Response** ```python CardMethod( code=token, name=token, number=81 ) ``` ## Merchant Category The Merchant Category resource is used to query the merchant categories available in the Stark Infra API. A category is identified either by its code, which specifies a single MCC, or by its type, which defines an entire group of merchant codes, such as "food" or "services". Use these codes and types to define the category filters of the issuing rules of your [Issuing Holder](#issuing-holder) resource and [Issuing Card](#issuing-card) resource. A category filter must define exactly one parameter between code and type. **Note:** Merchant categories are never created by you. They are an enum served by the API, so this resource is query-only. ### The Merchant Category object **Attributes** | Name | Type | Description | | --- | --- | --- | | `code` | STRING | Category's code, which specifies a single MCC. Example: "fastFoodRestaurants". | | `type` | STRING | Category's type, which defines an entire group of merchant codes. Options: "unknown", "pets", "food", "fuel", "retail", "health", "hotels", "leisure", "services", "clothing", "gambling", "airlines", "carRental", "education", "groceries", "financial", "government", "organizations", "transportation". Example: "food". | | `name` | STRING | Category's name, translated to the language of the Accept-Language header. Example: "Fast food restaurants". | | `number` | STRING | Category's number. Example: "5814". | ### List Merchant Categories `GET /v2/merchant-category` Get a list of the merchant categories available in the Stark Infra API. Either codes, which specify single MCCs, or types, which define entire groups of merchant codes, will be accepted as category filters in your issuing rules. **NOTE:** This route returns the full enum in a single response. It is not paginated, so it accepts no limit or cursor parameters and returns no cursor. **Parameters** | Name | Required | Description | | --- | --- | --- | | `search` | OPTIONAL | Keyword to search for code, type, name or number. The match is case- and accent-insensitive. Example: "food" | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra categories = starkinfra.merchantcategory.query( search="food" ) for category in categories: print(category) ``` **Response** ```python MerchantCategory( code=fastFoodRestaurants, type=food, name=Fast food restaurants, number=5814 ) ``` ## Merchant Country The Merchant Country resource is used to query the merchant countries available in the Stark Infra API. A country is identified by its code, which is the only field you send when you use a country in an issuing rule. Use these codes to define the country filters of the spending rules of your [Issuing Holder](#issuing-holder) resource and [Issuing Card](#issuing-card) resource. **Note:** Merchant countries are never created by you. They are an enum served by the API, so this resource is query-only. ### The Merchant Country object **Attributes** | Name | Type | Description | | --- | --- | --- | | `code` | STRING | Country's code. This is the only field you send when you use a country in an issuing rule. Example: "BRA". | | `name` | STRING | Country's name. Example: "Brazil". | | `number` | STRING | Country's number. Example: "076". | | `shortCode` | STRING | Country's short code. Example: "BR". | ### List Merchant Countries `GET /v2/merchant-country` Use this route to list the merchant countries available in the Stark Infra API. Their codes will be accepted as country filters in your issuing rules. **NOTE:** This route returns the full enum in a single response. It is not paginated, so it accepts no limit and no cursor parameters and returns no cursor. **Parameters** | Name | Required | Description | | --- | --- | --- | | `search` | OPTIONAL | Keyword to search for code, name, number or shortCode. The match is case- and accent-insensitive. Example: "brazil" | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. Example: "code,name" | **Request** ```python import starkinfra countries = starkinfra.merchantcountry.query( search="brazil" ) for country in countries: print(country) ``` **Response** ```python MerchantCountry( code=BRA, name=Brazil, number=076, short_code=BR ) ``` # Lending ## Credit Note Credit Notes represent credit operations issued to individuals or businesses as Bank Credit Bills (Cédula de Crédito Bancário - CCB). They carry all the information needed to formalize a lending operation, including signers, installment invoices and the disbursement payment details. Once created, the credit note generates a contract that must be digitally signed by all signers. After signing, the disbursement is transferred via Pix to the borrower's account and each installment is tracked through invoices. Here we will show you how to create and manage them. ### The CreditNote object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the credit note. | | `templateId` | STRING | ID of the credit note template used. Templates are enabled for your workspace through your credit profile. | | `name` | STRING | Borrower full name. | | `taxId` | STRING | Borrower CPF or CNPJ. | | `nominalAmount` | INTEGER | Nominal amount in cents of the credit note, before taxes. Example: 100000 (R$1,000.00). | | `rebateAmount` | INTEGER | Amount in cents discounted from the disbursed amount. Example: 100 (R$1.00). | | `taxAmount` | INTEGER | Tax amount in cents (IOF) embedded in the operation, computed from the borrower type (individual or business) and the operation duration. | | `amount` | INTEGER | Net amount in cents disbursed to the borrower. | | `interest` | FLOAT | Effective interest rate of the credit operation, in % per year, computed from the disbursed amount and the invoice schedule. Example: 27.5. | | `nominalInterest` | FLOAT | Nominal interest rate of the credit operation, in % per year, computed from the nominal amount and the invoice schedule. Example: 25.2. | | `rules` | LIST OF OBJECTS | List of rules modifying the credit note behavior, as {"key", "value"} objects. Currently available key: "invoiceCreationMode", with values "scheduled" (default - each installment invoice is issued a few days before its due date), "instant" (all invoices are issued as soon as the note is disbursed) or "never" (invoices are not issued automatically). | | `scheduled` | STRING | Datetime when the credit note will be disbursed after signing. Example: "2022-06-28T00:00:00.000000+00:00". | | `expiration` | INTEGER | Time span, in seconds, counted from the scheduled datetime, for the borrower and signers to sign the contract before the credit note expires. Default: 604800 (7 days). | | `externalId` | STRING | Unique external ID that prevents the creation of duplicate credit notes on unintended retries. | | `tags` | LIST OF STRINGS | Tags associated with the credit note. | | `status` | STRING | Current status of the credit note. Options: "created" (awaiting signatures), "signed" (contract signed by all signers), "processing" (disbursement in progress), "success" (disbursement settled), "failed" (disbursement failed), "canceled" and "expired" (not signed before the expiration). | | `signers` | LIST OF OBJECTS | List of CreditSigner objects representing every person or entity that must sign the contract, as {"id", "name", "contact", "method", "signed"} objects. Signers registered in your credit profile and the SCD signature are appended automatically. | | `invoices` | LIST OF OBJECTS | List of Invoice objects representing the installments to be paid by the borrower, with their "id", "amount", "due", "fine", "interest", "expiration", "descriptions" and "tags". | | `payment` | OBJECT | Transfer object used to disburse the credit amount to the borrower, including its "id" and "status" once the disbursement is initiated. | | `paymentType` | STRING | Type of the payment object. Options: "transfer". | | `streetLine1` | STRING | Borrower main address street line. | | `streetLine2` | STRING | Borrower complement address street line. | | `district` | STRING | Borrower address district. | | `city` | STRING | Borrower address city. | | `stateCode` | STRING | Borrower address state code. Example: "SP". | | `zipCode` | STRING | Borrower address zip code. Example: "01310-100". | | `documentId` | STRING | Unique id of the digital signing document attached to this credit note. | | `workspaceId` | STRING | ID of the workspace that issued the credit note. | | `debtorWorkspaceId` | STRING | ID of the borrower's workspace, when it differs from the issuing workspace. | | `transactionIds` | LIST OF STRINGS | Ledger transaction ids linked to the disbursement and its chargebacks. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Credit Notes `POST /v2/credit-note` Create credit notes in bulk. You can create up to 100 credit notes in a single request. Provide either the nominalAmount (pre-tax) or the amount (net disbursed value) - the other one, along with the taxAmount (IOF) and the interest rates, is computed from the invoice schedule. **Parameters** | Name | Required | Description | | --- | --- | --- | | `templateId` | REQUIRED | ID of the credit note template to be used. Templates are enabled for your workspace through your credit profile. | | `name` | REQUIRED | Borrower full name. Example: "Jamie Lannister" | | `taxId` | REQUIRED | Borrower CPF (11 digits) or CNPJ (14 digits). Example: "012.345.678-90" | | `scheduled` | REQUIRED | Datetime when the credit note should be disbursed after signing. Example: "2022-06-28" | | `invoices` | REQUIRED | List of up to 100 Invoice objects representing the installments to be paid by the borrower. Each invoice takes a required "amount" (in cents) and optional "due", "fine" (default 2.0), "interest" (default 1.0), "expiration", "descriptions" and "tags". All invoices must share the same fine and interest. | | `payment` | REQUIRED | Transfer object used to disburse the credit amount to the borrower's account, with required "name", "taxId", "bankCode" (receiver institution ISPB, 8 digits), "branchCode" and "accountNumber", and optional "accountType" ("checking", "payment", "salary" or "savings") and "tags". Do not send an "amount" in the payment object - the disbursed amount is computed by the API. | | `paymentType` | REQUIRED | Type of the payment object. Options: "transfer". | | `signers` | REQUIRED | List of up to 10 CreditSigner objects representing every person or entity that must sign the contract, each with required "name", "contact" and "method". Methods: "link" (signing link sent to an email or phone contact), "token" (signing token sent to an email or phone contact), "server" and "organization" (automatic signatures over URL contacts). Signers registered in your credit profile and the SCD signature are appended automatically. | | `externalId` | REQUIRED | Unique external ID to prevent the creation of duplicate credit notes on unintended retries. Example: "my-internal-id-123456" | | `streetLine1` | REQUIRED | Borrower main address street line. | | `streetLine2` | REQUIRED | Borrower complement address street line. | | `district` | REQUIRED | Borrower address district. | | `city` | REQUIRED | Borrower address city. | | `stateCode` | REQUIRED | Borrower address state code. Example: "SP". | | `zipCode` | REQUIRED | Borrower address zip code. Example: "01310-100". | | `nominalAmount` | OPTIONAL | Nominal amount in cents to be lent, before taxes. Provide either nominalAmount or amount. Example: 100000 (R$1,000.00). | | `amount` | OPTIONAL | Net amount in cents to be disbursed to the borrower. Provide either nominalAmount or amount. Example: 100000 (R$1,000.00). | | `rebateAmount` | OPTIONAL | Amount in cents to be discounted from the disbursed amount. Default is 0. Example: 100 (R$1.00). | | `expiration` | OPTIONAL | Time span, in seconds, counted from the scheduled datetime, for the contract to be signed before the credit note expires. Default: 604800 (7 days). | | `rules` | OPTIONAL | List of rules modifying the credit note behavior, as {"key", "value"} objects. Currently available key: "invoiceCreationMode", with values "scheduled" (default), "instant" or "never". | | `tags` | OPTIONAL | List of strings to tag the credit note for future queries. | **Request** ```python import starkinfra notes = starkinfra.creditnote.create([ starkinfra.CreditNote( template_id="5745297609744384", name="Jamie Lannister", tax_id="012.345.678-90", nominal_amount=100000, scheduled="2022-06-28", invoices=[ starkinfra.creditnote.Invoice( amount=102612, due="2022-07-28" ) ], payment=starkinfra.creditnote.Transfer( bank_code="20018183", branch_code="1234", account_number="129340-1", name="Jamie Lannister", tax_id="012.345.678-90" ), payment_type="transfer", signers=[ starkinfra.creditsigner.CreditSigner( name="Jamie Lannister", contact="jamie.lannister@gmail.com", method="link" ) ], external_id="my-internal-id-123456", street_line_1="Av. Paulista, 200", street_line_2="Apto. 51", district="Bela Vista", city="Sao Paulo", state_code="SP", zip_code="01310-100" ) ]) for note in notes: print(note) ``` **Response** ```python CreditNote( id=5745297609744385, template_id=5745297609744384, name=Jamie Lannister, tax_id=012.345.678-90, nominal_amount=100000, tax_amount=626, amount=99374, interest=38.61, nominal_interest=30.69, status=created, external_id=my-internal-id-123456, scheduled=2022-06-28T00:00:00.000000+00:00, expiration=604800, payment_type=transfer, created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-01T00:00:00.000000+00:00 ) ``` ### List Credit Notes `GET /v2/credit-note` List and filter all credit notes created in your workspace. Results are returned paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter credit notes by the specified status. Options: "created", "signed", "processing", "success", "failed", "canceled", "expired". | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra notes = starkinfra.creditnote.query( limit=10, status="signed", after="2022-06-01", before="2022-06-30" ) for note in notes: print(note) ``` **Response** ```python CreditNote( id=5745297609744385, template_id=5745297609744384, name=Jamie Lannister, tax_id=012.345.678-90, nominal_amount=100000, tax_amount=626, amount=99374, interest=38.61, nominal_interest=30.69, status=signed, external_id=my-internal-id-123456, scheduled=2022-06-28T00:00:00.000000+00:00, expiration=604800, payment_type=transfer, created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-02T00:00:00.000000+00:00 ) ``` ### Get a Credit Note `GET /v2/credit-note/:id` Get a single credit note by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit note entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra note = starkinfra.creditnote.get("5745297609744385") print(note) ``` **Response** ```python CreditNote( id=5745297609744385, template_id=5745297609744384, name=Jamie Lannister, tax_id=012.345.678-90, nominal_amount=100000, tax_amount=626, amount=99374, interest=38.61, nominal_interest=30.69, status=signed, signers=[{id: 6306107546853376, name: Jamie Lannister, method: link, contact: jamie.lannister@gmail.com, signed: 2022-06-02T00:00:00.000000+00:00}], document_id=07d05b14-9d83-4439-9622-d2b313b05a10, external_id=my-internal-id-123456, scheduled=2022-06-28T00:00:00.000000+00:00, expiration=604800, payment_type=transfer, created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-02T00:00:00.000000+00:00 ) ``` ### Cancel a Credit Note `DELETE /v2/credit-note/:id` Cancel a credit note that has not reached a final status yet. Credit notes with status "created", "signed" or "processing" can be canceled, which also cancels the signing document. Credit notes with status "success", "failed", "expired" or already "canceled" are returned unchanged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit note entity. | **Request** ```python import starkinfra note = starkinfra.creditnote.cancel("5745297609744385") print(note) ``` **Response** ```python CreditNote( id=5745297609744385, template_id=5745297609744384, name=Jamie Lannister, tax_id=012.345.678-90, nominal_amount=100000, status=canceled, external_id=my-internal-id-123456, created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-03T00:00:00.000000+00:00 ) ``` ### Get a Credit Note PDF `GET /v2/credit-note/:id/pdf` Get the CCB contract PDF file of a credit note. After all signers have signed, the returned file carries the digital signatures. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit note entity. | **Request** ```python import starkinfra pdf = starkinfra.creditnote.pdf("5745297609744385") with open("credit-note.pdf", "wb") as file: file.write(pdf) ``` **Response** ```python (binary PDF file content) ``` ### Get a Credit Note Payment PDF `GET /v2/credit-note/:id/payment/pdf` Get the disbursement transfer receipt PDF file of a credit note. Only available for credit notes with status "success". **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit note entity. | **Request** ```python import starkinfra pdf = starkinfra.request.get( path="/credit-note/5745297609744385/payment/pdf" ).content with open("credit-note-payment.pdf", "wb") as file: file.write(pdf) ``` **Response** ```python (binary PDF file content) ``` ### List Credit Note Logs `GET /v2/credit-note/log` Get a paged list of all credit note logs. A log tracks a change in the credit note entity according to its life cycle, as {"id", "type", "errors", "note", "created"} objects. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `noteIds` | OPTIONAL | List of credit note ids linked to the desired logs. Max = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "signing", "signed", "sending", "sent", "success", "failed", "refunded", "canceled", "expired", "updated", "registered". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra logs = starkinfra.creditnote.log.query( limit=10, note_ids=["5745297609744385"], types=["signed"] ) for log in logs: print(log) ``` **Response** ```python Log( id=6532638269505536, type=signed, errors=[], note=CreditNote( id=5745297609744385, name=Jamie Lannister, status=signed ), created=2022-06-02T00:00:00.000000+00:00 ) ``` ### Get a Credit Note Log `GET /v2/credit-note/log/:id` Get a single credit note log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit note log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.creditnote.log.get("6532638269505536") print(log) ``` **Response** ```python Log( id=6532638269505536, type=signed, errors=[], note=CreditNote( id=5745297609744385, name=Jamie Lannister, status=signed ), created=2022-06-02T00:00:00.000000+00:00 ) ``` ## Credit Signer Credit Signers represent every person or entity that must sign the CCB contract of a [Credit Note](#credit-note). Signers are created together with the Credit Note, through its "signers" parameter, and are returned embedded in the CreditNote object. Signers registered in your credit profile and the SCD signature are appended automatically. When the method is "link" or "token", the signer receives the signing link or token on the registered contact (email or phone). If a signer misses it, you can trigger a new delivery. ### The CreditSigner object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the credit signer. | | `name` | STRING | Signer full name. | | `contact` | STRING | Signer contact that receives the signing link or token. Can be an email, a phone number or, for the "server" and "organization" methods, a URL. | | `method` | STRING | Signing method. Options: "link" (signing link sent to the contact), "token" (signing token sent to the contact), "server" and "organization" (automatic signatures over URL contacts). | | `signed` | STRING | Datetime when the signer signed the contract. Empty until the signature happens. Example: "2022-06-02T00:00:00.000000+00:00". | ### Update a Credit Signer `PATCH /v2/credit-signer/:id` Update the delivery state of a credit signer's signing token or link. Setting "isSent" to false marks it as not delivered, causing it to be sent again to the signer's contact. Use it when a signer misses the original email or SMS. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit signer entity, as returned in the "signers" field of the CreditNote object. | | `isSent` | REQUIRED | Delivery state of the signing token or link. Set to false to trigger a new delivery. | **Request** ```python import starkinfra signer = starkinfra.creditsigner.resend_token("6306107546853376") print(signer) ``` **Response** ```python CreditSigner( id=6306107546853376, name=Jamie Lannister, contact=jamie.lannister@gmail.com, method=link, signed= ) ``` ## Credit Preview CreditPreviews are used to preview a credit operation before creating it. You can simulate the installment schedule, the IOF tax amount, the disbursed amount and the effective interest rates of a [Credit Note](#credit-note) without persisting anything. Previews are computed on the fly and are not saved. ### The CreditPreview object **Attributes** | Name | Type | Description | | --- | --- | --- | | `type` | STRING | Type of the credit preview. Options: "credit-note". | | `credit` | OBJECT | CreditNotePreview object with the simulation parameters and, in the response, the computed results. Its "type" defines the amortization schedule: "sac" (constant amortization), "price" (fixed installments), "american" (periodic interest and principal at maturity), "bullet" (principal and interest at maturity) or "custom" (you provide the invoices and the rates are computed). Input fields: "taxId", "scheduled" (disbursement datetime), "nominalInterest" (% per year), "initialDue" (first installment due datetime), "count" (number of installments), "initialAmount" (installment amount in cents), "interval" ("day", "week", "month", "quarter", "semester" or "year" - default "month"), "nominalAmount" or "amount" (in cents), "rebateAmount" and, for the "custom" type, "invoices" as {"amount", "due"} objects. Computed fields returned: "amount" (net disbursed amount), "taxAmount" (IOF), "interest" (effective rate, % per year), "nominalInterest", "count", "initialDue", "initialAmount" and the full "invoices" schedule. | ### Create Credit Previews `POST /v2/credit-preview` Create credit previews to simulate credit notes before actually creating them. You can create up to 100 previews in a single request. For the "sac" and "price" types, provide exactly one of "count" or "initialAmount" - the other one is computed. For every preview type - sac, price, american, bullet or custom - provide exactly one of "nominalAmount" or "amount"; the other value, along with taxAmount and the interest rates, is computed from the invoice schedule. **Parameters** | Name | Required | Description | | --- | --- | --- | | `type` | REQUIRED | Type of the credit preview. Options: "credit-note". | | `credit` | REQUIRED | CreditNotePreview object with the simulation parameters. Required fields by credit type: "sac" and "price" take "nominalInterest", "scheduled", "initialDue", "taxId" and one of "count" or "initialAmount"; "american" takes "nominalInterest", "scheduled", "initialDue", "count" and "taxId"; "bullet" takes "nominalInterest", "scheduled", "initialDue" and "taxId"; "custom" takes "scheduled", "taxId" and "invoices". Optional fields: "nominalAmount" or "amount" (exactly one of them is required, "custom" included), "rebateAmount" and "interval". | **Request** ```python import starkinfra previews = starkinfra.creditpreview.create([ starkinfra.CreditPreview( type="credit-note", credit=starkinfra.creditpreview.CreditNotePreview( type="sac", nominal_amount=100000, nominal_interest=15.0, scheduled="2022-06-28", initial_due="2022-07-28", count=12, tax_id="012.345.678-90" ) ) ]) for preview in previews: print(preview) ``` **Response** ```python CreditPreview( type=credit-note, credit=CreditNotePreview( type=sac, nominal_amount=100000, rebate_amount=0, tax_amount=1126, amount=98874, interest=17.34, nominal_interest=15.0, scheduled=2022-06-28T00:00:00.000000+00:00, initial_due=2022-07-28T00:00:00.000000+00:00, initial_amount=9583, count=12, invoices=[Invoice(amount=9583, due=2022-07-28), ..., Invoice(amount=8438, due=2023-06-28)] ) ) ``` ## Credit Holmes CreditHolmes are used to request the credit analysis of a tax ID. The analysis retrieves credit information from official sources for a given CPF or CNPJ, helping you evaluate the creditworthiness of a borrower. ### The CreditHolmes object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the credit holmes. | | `taxId` | STRING | CPF or CNPJ of the entity to be analyzed. | | `competence` | STRING | Month and year of the credit analysis in YYYY-MM format. Example: "2022-06". | | `status` | STRING | Current status of the credit analysis. Options: "created", "success", "failed". | | `result` | OBJECT | Credit analysis result containing financial and credit data for the tax ID. | | `tags` | LIST OF STRINGS | Tags associated with the credit holmes. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Credit Holmes `POST /v2/credit-holmes` Create credit holmes requests to analyze the credit profile of a tax ID. You can create up to 100 requests in a single call. Before you create a Credit Holmes, make sure you have your customer's express authorization to verify their information in the Central Bank's SCR. **Parameters** | Name | Required | Description | | --- | --- | --- | | `taxId` | REQUIRED | CPF (11 digits) or CNPJ (14 digits) of the entity to analyze. Example: "012.345.678-90" | | `competence` | OPTIONAL | Month and year of analysis in YYYY-MM format. Defaults to two months before the current date. Example: "2022-06" | | `tags` | OPTIONAL | List of strings to tag the entity for future queries. | **Request** ```python import starkinfra holmes = starkinfra.creditholmes.create([ starkinfra.CreditHolmes( tax_id="012.345.678-90", competence="2022-06", tags=["credit-analysis"] ) ]) for sherlock in holmes: print(sherlock) ``` **Response** ```python CreditHolmes( id=5719405850615809, tax_id=012.345.678-90, competence=2022-06, status=created, result=None, tags=['credit-analysis'], created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-01T00:00:00.000000+00:00 ) ``` ### List Credit Holmes `GET /v2/credit-holmes` List and filter all credit holmes requests in your workspace. Results are returned paged. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter credit holmes by the specified status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra holmes = starkinfra.creditholmes.query(limit=10) for sherlock in holmes: print(sherlock) ``` **Response** ```python CreditHolmes( id=5719405850615809, tax_id=012.345.678-90, competence=2022-06, status=solved, result={...}, tags=['credit-analysis'], created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-01T00:00:00.000000+00:00 ) ``` ### Get a Credit Holmes `GET /v2/credit-holmes/:id` Get a single credit holmes by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit holmes entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra sherlock = starkinfra.creditholmes.get("5719405850615809") print(sherlock) ``` **Response** ```python CreditHolmes( id=5719405850615809, tax_id=012.345.678-90, competence=2022-06, status=solved, result={...}, tags=['credit-analysis'], created=2022-06-01T00:00:00.000000+00:00, updated=2022-06-01T00:00:00.000000+00:00 ) ``` ### List Credit Holmes Logs `GET /v2/credit-holmes/log` Get a paged list of all credit holmes logs. A log tracks a change in the credit holmes entity according to its life cycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `ids` | OPTIONAL | List of credit holmes ids linked to the desired logs. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "failed", "success". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra logs = starkinfra.creditholmes.log.query(limit=10) for log in logs: print(log) ``` **Response** ```python Log( id=5155165527080961, type=created, created=2022-06-01T00:00:00.000000+00:00, holmes=CreditHolmes(id=5719405850615809, status=created, ...) ) ``` ### Get a Credit Holmes Log `GET /v2/credit-holmes/log/:id` Get a single credit holmes log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the credit holmes log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.creditholmes.log.get("5155165527080961") print(log) ``` **Response** ```python Log( id=5155165527080961, type=created, created=2022-06-01T00:00:00.000000+00:00, holmes=CreditHolmes(id=5719405850615809, status=created, ...) ) ``` # Ledger ## Ledger The Ledger resource is used to track the balance of a given amount by inserting LedgerTransactions to it. A Ledger can represent a bank account, a digital wallet, an inventory product, or any other entity whose balance you need to keep track of. You can attach rules to a Ledger to limit its balance, such as a minimum or maximum balance, which are validated whenever a LedgerTransaction is created. ### The Ledger object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Ledger. | | `externalId` | STRING | Unique external id to prevent duplicates. | | `rules` | LIST OF OBJECTS | List of rule objects applied to the Ledger. | | `tags` | LIST OF STRINGS | Tags associated with the Ledger. | | `metadata` | OBJECT | Dictionary of additional information about the Ledger. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Ledgers `POST /v2/ledger` Use this route to create up to 100 new ledgers at a time. **Parameters** | Name | Required | Description | | --- | --- | --- | | `externalId` | REQUIRED | Unique string to prevent duplicates. Repeated externalIds will cause failures. | | `rules` | OPTIONAL | List of rule objects to apply to the Ledger. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | | `metadata` | OPTIONAL | Dictionary of additional information about the Ledger. | **Request** ```python import starkinfra ledgers = starkinfra.ledger.create([ starkinfra.Ledger( external_id="my-internal-id-123456", rules=[ starkinfra.ledger.Rule( key="minimumBalance", value=0 ) ], tags=["account/123", "savings"], metadata={"accountId": "123", "accountType": "savings"} ) ]) for ledger in ledgers: print(ledger) ``` **Response** ```python [ Ledger( id=5656565656565656, external_id=my-internal-id-123456, rules=[ Rule( key=minimumBalance, value=0 ) ], tags=['account/123', 'savings'], metadata={'accountId': '123', 'accountType': 'savings'}, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ] ``` ### List Ledgers `GET /v2/ledger` Get a list of ledgers in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `externalIds` | OPTIONAL | Filter by external IDs. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra ledgers = starkinfra.ledger.query( limit=10, tags=["savings"] ) for ledger in ledgers: print(ledger) ``` **Response** ```python Ledger( id=5656565656565656, external_id=my-internal-id-123456, rules=[ Rule( key=minimumBalance, value=0 ) ], tags=['account/123', 'savings'], metadata={'accountId': '123', 'accountType': 'savings'}, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Get a Ledger `GET /v2/ledger/:id` Get a single ledger by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the ledger entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra ledger = starkinfra.ledger.get("5656565656565656") print(ledger) ``` **Response** ```python Ledger( id=5656565656565656, external_id=my-internal-id-123456, rules=[ Rule( key=minimumBalance, value=0 ) ], tags=['account/123', 'savings'], metadata={'accountId': '123', 'accountType': 'savings'}, created=2022-01-01 00:00:00, updated=2022-01-01 00:00:00 ) ``` ### Update a Ledger `PATCH /v2/ledger/:id` Update the rules, tags or metadata of an existing ledger. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the ledger entity. | | `rules` | OPTIONAL | New list of rule objects to apply to the Ledger. | | `tags` | OPTIONAL | New array of strings to tag the Ledger. | | `metadata` | OPTIONAL | New dictionary of additional information about the Ledger. | **Request** ```python import starkinfra ledger = starkinfra.ledger.update( "5656565656565656", tags=["account/123", "closed"] ) print(ledger) ``` **Response** ```python Ledger( id=5656565656565656, external_id=my-internal-id-123456, rules=[ Rule( key=minimumBalance, value=0 ) ], tags=['account/123', 'closed'], metadata={'accountId': '123', 'accountType': 'savings'}, created=2022-01-01 00:00:00, updated=2022-06-01 00:00:00 ) ``` ### List Ledger Logs `GET /v2/ledger/log` Get a paged list of ledger logs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `ledgerId` | OPTIONAL | Filter logs by ledger id. Only a single ledger id can be informed per query. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra logs = starkinfra.ledger.log.query( limit=10, ledger_id="5656565656565656" ) for log in logs: print(log) ``` **Response** ```python Log( id=5656565656565656, type=created, ledger=Ledger(id=5656565656565656, external_id=my-internal-id-123456), created=2022-01-01 00:00:00 ) ``` ### Get a Ledger Log `GET /v2/ledger/log/:id` Get a single ledger log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.ledger.log.get("5656565656565656") print(log) ``` **Response** ```python Log( id=5656565656565656, type=created, ledger=Ledger(id=5656565656565656, external_id=my-internal-id-123456), created=2022-01-01 00:00:00 ) ``` ## Ledger Transaction The LedgerTransaction resource is used to move balance in or out of a [Ledger](#ledger). Each transaction carries an amount that is added to (or subtracted from) the Ledger balance, producing a new running balance that is returned in the response. Transactions are validated against the rules of their Ledger, so a transaction that would push the balance beyond a configured minimum or maximum balance is rejected. ### The LedgerTransaction object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the Ledger Transaction. | | `ledgerId` | STRING | Id of the Ledger associated with this transaction. | | `externalId` | STRING | Unique external id to prevent duplicates. | | `source` | STRING | Source of the Ledger Transaction. Example: "bank-transfer/123". | | `amount` | INTEGER | Amount in cents of the Ledger Transaction. Example: 100 (R$1.00). | | `fee` | INTEGER | Fee charged in cents for this Ledger Transaction. | | `balance` | INTEGER | Balance in cents of the Ledger after this transaction. Example: 100 (R$1.00). | | `rules` | LIST OF OBJECTS | List of rule objects applied to the Ledger Transaction. | | `tags` | LIST OF STRINGS | Tags associated with the Ledger Transaction. | | `metadata` | OBJECT | Dictionary of additional information about the Ledger Transaction. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create Ledger Transactions `POST /v2/ledger-transaction` Use this route to create up to 500 new ledger transactions at a time. A single request may contain transactions targeting different ledgers. Each transaction is applied to its [Ledger](#ledger) in the order it is sent and the resulting balance is returned for each one. **Parameters** | Name | Required | Description | | --- | --- | --- | | `amount` | REQUIRED | Amount in cents of the Ledger Transaction. Example: 100 (R$1.00). | | `ledgerId` | REQUIRED | Id of the Ledger associated with this transaction. | | `externalId` | REQUIRED | Unique string to prevent duplicates. Repeated externalIds within the same ledger will cause failures. | | `source` | REQUIRED | Source of the Ledger Transaction. Example: "bank-transfer/123". | | `fee` | OPTIONAL | Fee charged in cents for this Ledger Transaction. | | `created` | OPTIONAL | Datetime of the Ledger Transaction, used to import an existing transaction history. Must be in ISO format (Example: "2022-01-01T00:00:00.000000+00:00") and cannot be in the future. When creating multiple transactions in a single request, their created datetimes must be informed in chronological order. If omitted, the current datetime is used. | | `rules` | OPTIONAL | List of rule objects that momentarily overwrite the Ledger's rules for this transaction. | | `tags` | OPTIONAL | Array of strings to tag the entity for future queries. | | `metadata` | OPTIONAL | Dictionary of additional information about the Ledger Transaction. | **Request** ```python import starkinfra transactions = starkinfra.ledgertransaction.create([ starkinfra.LedgerTransaction( amount=11234, ledger_id="5656565656565656", external_id="my-internal-id-123456", source="bank-transfer/123", fee=100, created="2022-01-01T03:00:00.000000+00:00", tags=["transfer/123", "savings"], metadata={"orderId": "123", "orderType": "purchase"} ) ]) for transaction in transactions: print(transaction) ``` **Response** ```python [ LedgerTransaction( id=5656565656565656, ledger_id=5656565656565656, external_id=my-internal-id-123456, source=bank-transfer/123, amount=11234, fee=100, balance=11134, tags=['transfer/123', 'savings'], metadata={'orderId': '123', 'orderType': 'purchase'}, created=2022-01-01 03:00:00 ) ] ``` ### List Ledger Transactions `GET /v2/ledger-transaction` Get a list of ledger transactions in chunks of at most 1000. Either "ledgerId" or "ids" must be provided. If both are sent, results are filtered by both. When filtering by "ids", the informed ids may reference transactions across different ledgers. **Parameters** | Name | Required | Description | | --- | --- | --- | | `ledgerId` | CONDITIONALLY REQUIRED | Id of the Ledger associated with the transactions. Either "ledgerId" or "ids" must be provided. | | `ids` | CONDITIONALLY REQUIRED | List of strings to get specific entities by ids. The informed ids may belong to transactions in different ledgers. Either "ledgerId" or "ids" must be provided. | | `flow` | OPTIONAL | Direction of the Ledger Transaction. Options: "in" (credit), "out" (debit). | | `externalIds` | OPTIONAL | Filter by external IDs. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `limit` | OPTIONAL | Number of results per cursor. Max = 1000. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra transactions = starkinfra.ledgertransaction.query( ledger_id="5656565656565656", limit=10 ) for transaction in transactions: print(transaction) ``` **Response** ```python LedgerTransaction( id=5656565656565656, ledger_id=5656565656565656, external_id=my-internal-id-123456, source=bank-transfer/123, amount=11234, fee=100, balance=11134, tags=['transfer/123', 'savings'], metadata={'orderId': '123', 'orderType': 'purchase'}, created=2022-01-01 00:00:00 ) ``` ### Get a Ledger Transaction `GET /v2/ledger-transaction/:id` Get a single ledger transaction by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the ledger transaction entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra transaction = starkinfra.ledgertransaction.get("5656565656565656") print(transaction) ``` **Response** ```python LedgerTransaction( id=5656565656565656, ledger_id=5656565656565656, external_id=my-internal-id-123456, source=bank-transfer/123, amount=11234, fee=100, balance=11134, tags=['transfer/123', 'savings'], metadata={'orderId': '123', 'orderType': 'purchase'}, created=2022-01-01 00:00:00 ) ``` # AI ## AI Agent An AI Agent is the configuration of an assistant: the model it runs on, the instructions that shape its persona, the knowledge bases it may consult and the voice it speaks with. Agents hold no conversation state. To talk to one, open an [AI Chat](#ai-chat) that points at the agent and post [AI Messages](#ai-message) to that chat. Attach a `metadataSchema` to make the agent return structured data alongside every reply — an intent label, a sentiment score, an extracted order number — so your backend can act on the conversation without parsing prose. ### The AI Agent object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Agent. | | `name` | STRING | Name of the agent. Example: "Support Assistant". | | `model` | STRING | AI model the agent runs on. Options: "bender-1.0", "prime-1.0". | | `systemPrompt` | STRING | Instructions that define the agent's persona, tone and domain behavior. Empty string when none was set. | | `voiceId` | STRING | Id of the AI Voice the agent speaks with. Empty string when the agent is text-only. | | `knowledgeBaseIds` | LIST OF STRINGS | Ids of the AI Knowledge Bases the agent may consult before answering. | | `metadataSchema` | OBJECT | Schema of the structured data the agent must extract on every reply. `null` when none was set. | | `knowledgeBases` | LIST OF OBJECTS | Id and name of each attached knowledge base. Only returned when `expand=knowledgeBases` is sent. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an AI Agent `POST /v2/ai-agent` Create a single agent. Only `name` and `model` are mandatory — an agent with no knowledge base, no voice and no schema is a plain chat assistant running on the default instructions. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | Name of the agent. Between 1 and 100 characters. | | `model` | REQUIRED | AI model the agent runs on. Options: `bender-1.0` for everyday conversations, `prime-1.0` for harder reasoning. | | `systemPrompt` | OPTIONAL | Instructions that define the agent's persona, tone and domain behavior. Up to 100000 characters. Falls back to Stark Infra's default assistant prompt when omitted. | | `voiceId` | OPTIONAL | Id of the AI Voice the agent speaks with. When set, every reply also carries a `speech` string ready to be sent to `POST /v2/ai-speech`. | | `knowledgeBaseIds` | OPTIONAL | List of up to 100 AI Knowledge Base ids. Before answering, the agent retrieves the passages most relevant to the question from these bases. | | `metadataSchema` | OPTIONAL | Flat object whose keys are the fields the agent must extract on every reply. Each field takes a `type` (`string`, `integer`, `number`, `boolean` or `array`), an optional `description` of up to 2000 characters, an optional `enum` of up to 20 strings for `string` fields, and a mandatory `items` element type for `array` fields. At most 20 fields and 8192 bytes. | **Request** ```python import starkinfra agent = starkinfra.aiagent.create( starkinfra.AiAgent( name="Support Assistant", model="bender-1.0", system_prompt="You are the support assistant of an online store. Answer in the customer language, never invent policies and always offer the next practical step.", voice_id="5656565656565656", knowledge_base_ids=["6767676767676767"], metadata_schema={ "intent": { "type": "string", "enum": ["order", "refund", "shipping", "other"], "description": "What the customer is trying to do." }, "isEscalation": { "type": "boolean", "description": "Whether the conversation should be handed to a human." } } ) ) print(agent) ``` **Response** ```python AiAgent( created=2022-01-01 00:00:00, id=4242424242424242, knowledge_base_ids=['6767676767676767'], knowledge_bases=None, metadata_schema={'intent': {'description': 'What the customer is trying to do.', 'enum': ['order', 'refund', 'shipping', 'other'], 'type': 'string'}, 'isEscalation': {'description': 'Whether the conversation should be handed to a human.', 'type': 'boolean'}}, model=bender-1.0, name=Support Assistant, system_prompt=You are the support assistant of an online store. Answer in the customer language, never invent policies and always offer the next practical step., updated=2022-01-01 00:00:00, voice_id=5656565656565656 ) ``` ### List AI Agents `GET /v2/ai-agent` Get every agent in your workspace. Agents are not paginated — a workspace holds few of them by design. **Parameters** | Name | Required | Description | | --- | --- | --- | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `knowledgeBases`. When `fields` is also sent, the expanded attribute must be listed there too. | **Request** ```python import starkinfra agents = starkinfra.aiagent.query(expand=["knowledge_bases"]) for agent in agents: print(agent) ``` **Response** ```python AiAgent( created=2022-01-01 00:00:00, id=4242424242424242, knowledge_base_ids=['6767676767676767'], knowledge_bases=[AiKnowledgeBase[6767676767676767]], metadata_schema=None, model=bender-1.0, name=Support Assistant, system_prompt=, updated=2022-01-01 00:00:00, voice_id=5656565656565656 ) ``` ### Get an AI Agent `GET /v2/ai-agent/:id` Get a single agent by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the agent entity. | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `knowledgeBases`. | **Request** ```python import starkinfra agent = starkinfra.aiagent.get("4242424242424242") print(agent) ``` **Response** ```python AiAgent( created=2022-01-01 00:00:00, id=4242424242424242, knowledge_base_ids=['6767676767676767'], knowledge_bases=None, metadata_schema=None, model=bender-1.0, name=Support Assistant, system_prompt=, updated=2022-01-01 00:00:00, voice_id=5656565656565656 ) ``` ### Update an AI Agent `PATCH /v2/ai-agent/:id` Change an agent's configuration. Chats already pointing at the agent pick up the new configuration on their next message. **Send `knowledgeBaseIds` on every update.** Unlike the other parameters, leaving it out does not preserve the current list — it clears it. Renaming an agent without resending its `knowledgeBaseIds` silently detaches every knowledge base it had. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the agent entity. | | `name` | OPTIONAL | New name for the agent. Between 1 and 100 characters. | | `model` | OPTIONAL | New AI model. Options: `bender-1.0`, `prime-1.0`. | | `systemPrompt` | OPTIONAL | New instructions for the agent. Up to 100000 characters. | | `voiceId` | OPTIONAL | New AI Voice id. | | `knowledgeBaseIds` | OPTIONAL | List of AI Knowledge Base ids the agent should end up with. Replaces the current list, and omitting it clears the list, so always send the full set you want to keep. | | `metadataSchema` | OPTIONAL | New schema of the structured data the agent must extract. | **Request** ```python import starkinfra agent = starkinfra.aiagent.update( "4242424242424242", model="prime-1.0", knowledge_base_ids=["6767676767676767", "7878787878787878"] ) print(agent) ``` **Response** ```python AiAgent( created=2022-01-01 00:00:00, id=4242424242424242, knowledge_base_ids=['6767676767676767', '7878787878787878'], knowledge_bases=None, metadata_schema=None, model=prime-1.0, name=Support Assistant, system_prompt=, updated=2022-01-02 00:00:00, voice_id=5656565656565656 ) ``` ### Delete AI Agents `DELETE /v2/ai-agent` Delete up to 100 agents at once. The ids travel in the query string, not in the body. Deleting an agent does not delete the chats that used it, but those chats can no longer receive new messages. **Parameters** | Name | Required | Description | | --- | --- | --- | | `ids` | REQUIRED | Comma-separated list of agent ids to delete. Between 1 and 100 ids. | **Request** ```python import starkinfra agents = starkinfra.aiagent.delete(ids=["4242424242424242"]) for agent in agents: print(agent) ``` **Response** ```python AiAgent( created=2022-01-01 00:00:00, id=4242424242424242, knowledge_base_ids=['6767676767676767'], knowledge_bases=None, metadata_schema=None, model=bender-1.0, name=Support Assistant, system_prompt=, updated=2022-01-02 00:00:00, voice_id=5656565656565656 ) ``` ## AI Chat An AI Chat is a conversation thread with one [AI Agent](#ai-agent). It carries the message history the agent reads before answering and the title shown in your interface. Open a chat once per conversation and keep posting [AI Messages](#ai-message) to it. The agent reads the last 20 messages of the thread as context, so the same chat gives you continuity and a new chat gives you a clean slate. The first message you post names the chat automatically: the title is generated from what the user wrote, unless you set one yourself at creation time. ### The AI Chat object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Chat. | | `agentId` | STRING | Id of the AI Agent that answers in this chat. | | `title` | STRING | Title of the conversation, set by you or generated from the first message. | | `agentName` | STRING | Name of the agent that answers in this chat. Only returned when `expand=agentName` is sent. | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an AI Chat `POST /v2/ai-chat` Open a conversation thread against an agent. Save the returned `id` — every message you post afterwards references it as `chatId`. **Parameters** | Name | Required | Description | | --- | --- | --- | | `agentId` | REQUIRED | Id of the AI Agent that will answer in this chat. | | `title` | OPTIONAL | Title of the conversation. Up to 100 characters. When omitted, the first message posted to the chat generates one. | **Request** ```python import starkinfra chat = starkinfra.aichat.create( starkinfra.AiChat( agent_id="4242424242424242", title="Order 1234 not delivered" ) ) print(chat) ``` **Response** ```python AiChat( agent_id=4242424242424242, agent_name=None, id=3131313131313131, title=Order 1234 not delivered, updated=2022-01-01 00:00:00 ) ``` ### List AI Chats `GET /v2/ai-chat` Get every chat in your workspace. **Parameters** | Name | Required | Description | | --- | --- | --- | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `agentName`. When `fields` is also sent, the expanded attribute must be listed there too. | **Request** ```python import starkinfra chats = starkinfra.aichat.query(expand=["agent_name"]) for chat in chats: print(chat) ``` **Response** ```python AiChat( agent_id=4242424242424242, agent_name=Support Assistant, id=3131313131313131, title=Order 1234 not delivered, updated=2022-01-01 00:00:00 ) ``` ### Get an AI Chat `GET /v2/ai-chat/:id` Get a single chat by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the chat entity. | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `agentName`. | **Request** ```python import starkinfra chat = starkinfra.aichat.get("3131313131313131") print(chat) ``` **Response** ```python AiChat( agent_id=4242424242424242, agent_name=None, id=3131313131313131, title=Order 1234 not delivered, updated=2022-01-01 00:00:00 ) ``` ### Update an AI Chat `PATCH /v2/ai-chat/:id` Rename a chat or hand it to another agent. Handing over keeps the message history, so the new agent reads everything that was said before. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the chat entity. | | `title` | OPTIONAL | New title for the conversation. Up to 100 characters. | | `agentId` | OPTIONAL | Id of the AI Agent that should answer from now on. | **Request** ```python import starkinfra chat = starkinfra.aichat.update( "3131313131313131", agent_id="5050505050505050" ) print(chat) ``` **Response** ```python AiChat( agent_id=5050505050505050, agent_name=None, id=3131313131313131, title=Order 1234 not delivered, updated=2022-01-02 00:00:00 ) ``` ### Delete AI Chats `DELETE /v2/ai-chat` Delete up to 100 chats at once. The ids travel in the query string, not in the body. **Parameters** | Name | Required | Description | | --- | --- | --- | | `ids` | REQUIRED | Comma-separated list of chat ids to delete. Between 1 and 100 ids. | **Request** ```python import starkinfra chats = starkinfra.aichat.delete(ids=["3131313131313131"]) for chat in chats: print(chat) ``` **Response** ```python AiChat( agent_id=4242424242424242, agent_name=None, id=3131313131313131, title=Order 1234 not delivered, updated=2022-01-02 00:00:00 ) ``` ## AI Message An AI Message is one turn of an [AI Chat](#ai-chat). Posting a message is how you talk to an agent: you send the user's text and the same call returns both the message you sent and the agent's answer. Every answer carries three payloads. `text` is the full reply, in Markdown. `speech` is a short spoken version of it, ready for [AI Speech](#ai-speech), and is only filled when the agent has a voice. `metadata` holds the structured fields declared in the agent's `metadataSchema`. The agent reads the last 20 messages of the chat before answering. When the agent has knowledge bases attached, it also retrieves the passages most relevant to the question and answers from them. ### The AI Message object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Message. | | `chatId` | STRING | Id of the AI Chat this message belongs to. | | `sender` | STRING | Who wrote the message. Options: "user", "system". The agent's answers are sent by "system". | | `text` | STRING | Full content of the message. Agent replies may contain Markdown. | | `speech` | STRING | Short spoken version of `text`: plain conversational text, no Markdown, no URLs, at most two sentences. Empty string when the agent has no voice. For user messages, it mirrors `text`. | | `metadata` | OBJECT | Structured fields extracted by the agent, following its `metadataSchema`. Empty object when the agent declares no schema. | | `model` | STRING | AI model that produced this turn. Options: "bender-1.0", "prime-1.0". | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Send an AI Message `POST /v2/ai-message` Post the user's text to a chat and get the agent's answer back in the same response. The `messages` array holds two entries in order: the message you sent and the reply the agent produced. This call is synchronous and runs the model, so it is slower than the rest of the API. Size your client timeouts accordingly. **Parameters** | Name | Required | Description | | --- | --- | --- | | `chatId` | REQUIRED | Id of the AI Chat to post to. | | `text` | REQUIRED | Content of the user's message. Between 1 and 50000 characters. | | `model` | OPTIONAL | AI model to use for this turn only. Options: `bender-1.0`, `prime-1.0`. Defaults to the agent's own model. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `chatName`, which returns the chat title alongside the messages — useful on the first turn, when the title is generated. | **Request** ```python import starkinfra messages = starkinfra.aimessage.create( starkinfra.AiMessage( chat_id="3131313131313131", text="My order 1234 was supposed to arrive yesterday and it did not. What can I do?" ), expand=["chat_name"] ) for message in messages: print(message) ``` **Response** ```python AiMessage( chat_id=3131313131313131, chat_name=Order 1234 not delivered, created=2022-01-01 00:00:00, id=2020202020202020, metadata={}, model=bender-1.0, sender=user, speech=My order 1234 was supposed to arrive yesterday and it did not. What can I do?, text=My order 1234 was supposed to arrive yesterday and it did not. What can I do? ) AiMessage( chat_id=3131313131313131, chat_name=Order 1234 not delivered, created=2022-01-01 00:00:00.001000, id=2121212121212121, metadata={'intent': 'shipping', 'isEscalation': False}, model=bender-1.0, sender=system, speech=I am sorry about the delay. I can open a delivery check for order 1234 right now., text=I am sorry about the delay on order **1234**. Here is what we can do: - Open a delivery check with the carrier, which takes up to 2 business days. - Reship the order at no cost if the carrier confirms the package was lost. Would you like me to open the delivery check now? ) ``` ### List AI Messages `GET /v2/ai-message` Get the messages of a chat, newest first, in chunks of at most 100. **Parameters** | Name | Required | Description | | --- | --- | --- | | `chatId` | REQUIRED | Id of the AI Chat whose messages you want. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `cursor` | OPTIONAL | String used to get the next batch of results, returned by the previous call. | **Request** ```python import starkinfra messages = starkinfra.aimessage.query( "3131313131313131", limit=10 ) for message in messages: print(message) ``` **Response** ```python AiMessage( chat_id=3131313131313131, chat_name=None, created=2022-01-01 00:00:00.001000, id=2121212121212121, metadata={'intent': 'shipping', 'isEscalation': False}, model=bender-1.0, sender=system, speech=I am sorry about the delay. I can open a delivery check for order 1234 right now., text=I am sorry about the delay on order **1234**. ) AiMessage( chat_id=3131313131313131, chat_name=None, created=2022-01-01 00:00:00, id=2020202020202020, metadata={}, model=bender-1.0, sender=user, speech=My order 1234 was supposed to arrive yesterday and it did not. What can I do?, text=My order 1234 was supposed to arrive yesterday and it did not. What can I do? ) ``` ## AI Knowledge Base An AI Knowledge Base turns a website into material an agent can read. You give it a root URL; Stark Infra crawls the page, follows its links, converts everything to Markdown and indexes it for retrieval. Crawling is asynchronous. The base is created in `processing` status and moves to `success` once the index is ready, or to `failed` when the crawl could not produce one. Poll the base until it leaves `processing`. Attach the base to an [AI Agent](#ai-agent) through `knowledgeBaseIds` and the agent consults it before answering: on every message it retrieves the passages most relevant to the question and answers from those. ### The AI Knowledge Base object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Knowledge Base. | | `name` | STRING | Name of the knowledge base. Example: "Product Documentation". | | `rootUrl` | STRING | URL the crawl starts from. Example: "https://docs.starkinfra.com". | | `isRecursive` | BOOLEAN | Whether the crawl may follow links into other subdomains of the root URL's registered domain. | | `status` | STRING | Current status of the knowledge base. Options: "processing", "success", "failed". An agent retrieves from a base only once it reaches "success". | | `tags` | LIST OF STRINGS | Tags associated with the knowledge base. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an AI Knowledge Base `POST /v2/ai-knowledge-base` Create a base and start crawling it. The call returns immediately with the base in `processing` status. The crawler seeds itself from the root page, and from the site's `llms.txt` and `sitemap.xml` when they exist. Pages are re-crawled daily, so the index tracks the site as it changes. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | Name of the knowledge base. Between 1 and 100 characters. | | `rootUrl` | REQUIRED | URL the crawl starts from. Must be an absolute `http` or `https` URL. | | `isRecursive` | OPTIONAL | Whether the crawl may leave the root URL's host. Defaults to `true`, which lets it follow links into other subdomains of the same registered domain. Send `false` to index the root host only. | | `tags` | OPTIONAL | List of up to 100 strings to tag the entity for future queries. | **Request** ```python import starkinfra knowledge_base = starkinfra.aiknowledgebase.create( starkinfra.AiKnowledgeBase( name="Product Documentation", root_url="https://docs.starkinfra.com", is_recursive=True, tags=["support", "public"] ) ) print(knowledge_base) ``` **Response** ```python AiKnowledgeBase( created=2022-01-01 00:00:00, id=6767676767676767, is_recursive=True, name=Product Documentation, root_url=https://docs.starkinfra.com, status=processing, tags=['support', 'public'], updated=2022-01-01 00:00:00 ) ``` ### List AI Knowledge Bases `GET /v2/ai-knowledge-base` Get the knowledge bases in your workspace, optionally filtered by name, status or id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `ids` | OPTIONAL | Comma-separated list of ids to get specific entities. | | `name` | OPTIONAL | Case-insensitive substring of the name to filter by. Example: `docs` matches "Product Docs". | | `status` | OPTIONAL | Filter by status. Options: `processing`, `success`, `failed`. | **Request** ```python import starkinfra knowledge_bases = starkinfra.aiknowledgebase.query( status="success", name="documentation" ) for knowledge_base in knowledge_bases: print(knowledge_base) ``` **Response** ```python AiKnowledgeBase( created=2022-01-01 00:00:00, id=6767676767676767, is_recursive=True, name=Product Documentation, root_url=https://docs.starkinfra.com, status=success, tags=['support', 'public'], updated=2022-01-01 00:10:00 ) ``` ### Get an AI Knowledge Base `GET /v2/ai-knowledge-base/:id` Get a single knowledge base by its id. This is the call to poll while the crawl runs. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the knowledge base entity. | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. | **Request** ```python import starkinfra knowledge_base = starkinfra.aiknowledgebase.get("6767676767676767") print(knowledge_base) ``` **Response** ```python AiKnowledgeBase( created=2022-01-01 00:00:00, id=6767676767676767, is_recursive=True, name=Product Documentation, root_url=https://docs.starkinfra.com, status=success, tags=['support', 'public'], updated=2022-01-01 00:10:00 ) ``` ### Update an AI Knowledge Base `PATCH /v2/ai-knowledge-base/:id` Rename a base, retag it or change whether its crawl is recursive. The root URL cannot be changed — point a new base at a new site. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the knowledge base entity. | | `name` | OPTIONAL | New name for the knowledge base. Between 1 and 100 characters. | | `isRecursive` | OPTIONAL | Whether the next crawl may follow links into other subdomains of the root URL's registered domain. | | `tags` | OPTIONAL | New list of up to 100 strings to tag the entity. Replaces the current list. | **Request** ```python import starkinfra knowledge_base = starkinfra.aiknowledgebase.update( "6767676767676767", name="Public Documentation", tags=["support"] ) print(knowledge_base) ``` **Response** ```python AiKnowledgeBase( created=2022-01-01 00:00:00, id=6767676767676767, is_recursive=True, name=Public Documentation, root_url=https://docs.starkinfra.com, status=success, tags=['support'], updated=2022-01-02 00:00:00 ) ``` ### List AI Knowledge Base Hosts `GET /v2/ai-knowledge-base/:id/hosts` Get every page the crawler has seen, grouped by host. Each entry carries the page's original URL, the URL of the Markdown file stored for it, and its status: `pending` while the page is still queued, `success` once it has been stored, `failed` when it could not be read. While a crawl is running this returns the live picture, merged with the last finished one, so you can watch the base fill up page by page. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the knowledge base entity. | **Request** ```python import starkinfra hosts = starkinfra.aiknowledgebase.hosts("6767676767676767") for host, pages in hosts.items(): print(host) for page in pages: print(page) ``` **Response** ```python docs.starkinfra.com {'original_url': 'https://docs.starkinfra.com/get-started', 'status': 'success', 'storage_url': 'https://storage.googleapis.com/ai-knowledge/6767676767676767/get-started.md'} {'original_url': 'https://docs.starkinfra.com/api', 'status': 'success', 'storage_url': 'https://storage.googleapis.com/ai-knowledge/6767676767676767/api.md'} ``` ### Delete AI Knowledge Bases `DELETE /v2/ai-knowledge-base` Delete up to 100 knowledge bases at once. The ids travel in the query string, not in the body. Agents still referencing a deleted base simply retrieve nothing from it. **Parameters** | Name | Required | Description | | --- | --- | --- | | `ids` | REQUIRED | Comma-separated list of knowledge base ids to delete. Up to 100 ids. | **Request** ```python import starkinfra knowledge_bases = starkinfra.aiknowledgebase.delete(ids=["6767676767676767"]) for knowledge_base in knowledge_bases: print(knowledge_base) ``` **Response** ```python AiKnowledgeBase( created=2022-01-01 00:00:00, id=6767676767676767, is_recursive=True, name=Public Documentation, root_url=https://docs.starkinfra.com, status=success, tags=['support'], updated=2022-01-02 00:00:00 ) ``` ## AI Voice An AI Voice is a cloned voice built from a recording you upload. Once cloned, it can read any text out loud through [AI Speech](#ai-speech), and it can be attached to an [AI Agent](#ai-agent) so every reply comes back with a spoken version ready to be synthesized. Cloning is asynchronous. The voice is created in `processing` status and moves to `success` when it is ready to speak, or to `failed` when the recording could not be cloned. Poll the list until it leaves `processing`. Send a clean sample of the speaker talking naturally. The audio travels as a base64 string and the format is detected from its own header — MP3, WAV, OGG, FLAC and WebM are all accepted. ### The AI Voice object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Voice. This is the `voiceId` you send to other AI resources. | | `name` | STRING | Name of the voice. Example: "Helena". | | `status` | STRING | Current status of the voice. Options: "processing", "success", "failed". Only a voice in "success" can speak. | | `description` | STRING | Free-text description of the voice. | | `language` | STRING | Language the voice speaks. Options: "portuguese", "english". | | `gender` | STRING | Gender of the voice. Options: "male", "female", "neutral". Empty string when none was set. | | `errors` | LIST OF STRINGS | Reasons the cloning failed. Empty while the voice is healthy. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an AI Voice `POST /v2/ai-voice` Upload a recording and start cloning it. The call returns immediately with the voice in `processing` status. **Parameters** | Name | Required | Description | | --- | --- | --- | | `audio` | REQUIRED | Base64-encoded recording of the speaker. Up to 10000000 characters. | | `name` | OPTIONAL | Name of the voice. Up to 100 characters. Defaults to the voice's own id. | | `description` | OPTIONAL | Free-text description of the voice. Up to 1000 characters. | | `language` | OPTIONAL | Language the voice speaks. Options: `portuguese`, `english`. Defaults to `portuguese`. | | `gender` | OPTIONAL | Gender of the voice. Options: `male`, `female`, `neutral`. | **Request** ```python import base64 import starkinfra with open("helena.wav", "rb") as recording: audio = base64.b64encode(recording.read()).decode() voice = starkinfra.aivoice.create( starkinfra.AiVoice( name="Helena", description="Calm Brazilian Portuguese voice for customer support", language="portuguese", gender="female", audio=audio ) ) print(voice) ``` **Response** ```python AiVoice( audio=None, created=2022-01-01 00:00:00, description=Calm Brazilian Portuguese voice for customer support, errors=[], gender=female, id=5656565656565656, language=portuguese, name=Helena, status=processing, updated=2022-01-01 00:00:00 ) ``` ### List AI Voices `GET /v2/ai-voice` Get every voice in your workspace. This is the call to poll while a clone is being built. **Request** ```python import starkinfra voices = starkinfra.aivoice.query() for voice in voices: print(voice) ``` **Response** ```python AiVoice( audio=None, created=2022-01-01 00:00:00, description=Calm Brazilian Portuguese voice for customer support, errors=[], gender=female, id=5656565656565656, language=portuguese, name=Helena, status=success, updated=2022-01-01 00:02:00 ) ``` ### Delete AI Voices `DELETE /v2/ai-voice` Delete up to 100 voices at once. The ids travel in the query string, not in the body. The clone is removed from the provider and the stored recording is erased. Speeches already synthesized with the voice are kept. **Parameters** | Name | Required | Description | | --- | --- | --- | | `ids` | REQUIRED | Comma-separated list of voice ids to delete. Up to 100 ids. | **Request** ```python import starkinfra voices = starkinfra.aivoice.delete(ids=["5656565656565656"]) for voice in voices: print(voice) ``` **Response** ```python AiVoice( audio=None, created=2022-01-01 00:00:00, description=Calm Brazilian Portuguese voice for customer support, errors=[], gender=female, id=5656565656565656, language=portuguese, name=Helena, status=success, updated=2022-01-02 00:00:00 ) ``` ## AI Speech An AI Speech is text read out loud by one of your [AI Voices](#ai-voice). You send the text and the voice id; the response carries the synthesized audio as a base64 MP3. Synthesis is synchronous: by the time the call returns, the speech is either in `success` status with its audio attached, or the request failed and nothing was produced. Every speech is stored, so you can fetch its audio again later by id without paying for a second synthesis. ### The AI Speech object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Speech. | | `voiceId` | STRING | Id of the AI Voice that read the text. | | `text` | STRING | Text that was read out loud. | | `status` | STRING | Current status of the speech. Options: "processing", "success", "failed". | | `audio` | STRING | Base64-encoded MP3 of the synthesized speech. Returned on creation and when the speech is fetched by its id, not in the list. | | `voiceName` | STRING | Name of the voice that read the text. Only returned when `expand=voiceName` is sent. | | `errors` | LIST OF STRINGS | Reasons the synthesis failed. Empty while the speech is healthy. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an AI Speech `POST /v2/ai-speech` Read a text out loud with one of your voices. The voice must be in `success` status — a clone that is still processing cannot speak yet. To give an agent a voice, feed it the reply's `speech` field rather than its `text`: `speech` is already stripped of Markdown, URLs and code, which is what makes it sound natural. **Parameters** | Name | Required | Description | | --- | --- | --- | | `voiceId` | REQUIRED | Id of the AI Voice that should read the text. | | `text` | REQUIRED | Text to read out loud. Between 1 and 100000 characters. | **Request** ```python import starkinfra speech = starkinfra.aispeech.create( starkinfra.AiSpeech( voice_id="5656565656565656", text="I am sorry about the delay. I can open a delivery check for order 1234 right now." ) ) print(speech) ``` **Response** ```python AiSpeech( audio=SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA..., created=2022-01-01 00:00:00, errors=[], id=1212121212121212, status=success, text=I am sorry about the delay. I can open a delivery check for order 1234 right now., updated=2022-01-01 00:00:01, voice_id=5656565656565656, voice_name=None ) ``` ### List AI Speeches `GET /v2/ai-speech` Get every speech in your workspace. The audio is not included — fetch a speech by its id to get it. **Parameters** | Name | Required | Description | | --- | --- | --- | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `voiceName`. When `fields` is also sent, the expanded attribute must be listed there too. | **Request** ```python import starkinfra speeches = starkinfra.aispeech.query(expand=["voice_name"]) for speech in speeches: print(speech) ``` **Response** ```python AiSpeech( audio=None, created=2022-01-01 00:00:00, errors=[], id=1212121212121212, status=success, text=I am sorry about the delay. I can open a delivery check for order 1234 right now., updated=2022-01-01 00:00:01, voice_id=5656565656565656, voice_name=Helena ) ``` ### Get an AI Speech `GET /v2/ai-speech/:id` Get a single speech by its id, with its audio attached as a base64 MP3. Send `fields` without `audio` to read the speech's metadata without downloading the file. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the speech entity. | | `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. The audio is only attached when `fields` is omitted or lists `audio`. | | `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `voiceName`. | **Request** ```python import starkinfra speech = starkinfra.aispeech.get("1212121212121212") print(speech) ``` **Response** ```python AiSpeech( audio=SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA..., created=2022-01-01 00:00:00, errors=[], id=1212121212121212, status=success, text=I am sorry about the delay. I can open a delivery check for order 1234 right now., updated=2022-01-01 00:00:01, voice_id=5656565656565656, voice_name=None ) ``` ## AI Transcript An AI Transcript is the text of an audio file you upload. It is the other half of [AI Speech](#ai-speech): speech turns text into audio, transcript turns audio into text. Transcription is synchronous. The call returns the finished transcript in `success` status with its `text` filled, or fails and produces nothing. Pair it with an [AI Agent](#ai-agent) to close the voice loop: transcribe what the caller said, post that text as a message, then synthesize the reply's `speech`. ### The AI Transcript object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the AI Transcript. | | `text` | STRING | Text transcribed from the audio. | | `status` | STRING | Current status of the transcript. Options: "processing", "success", "failed". | | `errors` | LIST OF STRINGS | Reasons the transcription failed. Empty while the transcript is healthy. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". | ### Create an AI Transcript `POST /v2/ai-transcript` Upload an audio file and get its text back. The format is detected from the audio's own header — MP3, WAV, OGG, FLAC and WebM are all accepted. No voice is involved: transcription reads any speaker, not only the ones you cloned. **Parameters** | Name | Required | Description | | --- | --- | --- | | `audio` | REQUIRED | Base64-encoded audio to transcribe. Up to 10000000 characters. | **Request** ```python import base64 import starkinfra with open("call.wav", "rb") as recording: audio = base64.b64encode(recording.read()).decode() transcript = starkinfra.aitranscript.create( starkinfra.AiTranscript( audio=audio ) ) print(transcript) ``` **Response** ```python AiTranscript( audio=None, created=2022-01-01 00:00:00, errors=[], id=9898989898989898, status=success, text=My order 1234 was supposed to arrive yesterday and it did not. What can I do?, updated=2022-01-01 00:00:02 ) ``` ### List AI Transcripts `GET /v2/ai-transcript` Get every transcript in your workspace. **Request** ```python import starkinfra transcripts = starkinfra.aitranscript.query() for transcript in transcripts: print(transcript) ``` **Response** ```python AiTranscript( audio=None, created=2022-01-01 00:00:00, errors=[], id=9898989898989898, status=success, text=My order 1234 was supposed to arrive yesterday and it did not. What can I do?, updated=2022-01-01 00:00:02 ) ``` # Identity ## Business Identity BusinessIdentities validate the identity of a legal entity (CNPJ) and feed its corporate documents into the Contract AI model. After creating an identity, upload one or more [Business Attachments](#business-attachment) referencing the returned `id` and PATCH the identity to `processing`. The structured signing rules extracted by the AI Model are delivered through the `business-identity` webhook when the identity reaches `success`. ### The BusinessIdentity object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the business identity. | | `taxId` | STRING | CNPJ of the legal entity. Example: "20.018.183/0001-80". | | `name` | STRING | Legal name of the company, fetched from the official bureau on creation. | | `taxIdStatus` | STRING | Bureau status of the CNPJ, normalized from the Receita Federal value. Mapping: "active" = "ATIVA", "blocked" = "SUSPENSA", "pending" = "INAPTA", "canceled" = "BAIXADA", "voided" = "NULA". | | `insightTaxId` | STRING | CNPJ extracted from the corporate documents by the AI Model. Empty until the analysis completes. | | `insightDocumentType` | STRING | Document type detected by the AI Model. Empty until the analysis completes. | | `representatives` | STRING | JSON string with the company's representatives (sócios) fetched from the bureau. Decode it to access each entry's `name`, `qualification` and `taxId`. | | `attachments` | LIST OF STRINGS | List of `attachment/` strings referencing the Business Attachments uploaded for this identity. | | `numPages` | INTEGER | Number of pages of the attached documents, extracted by the AI Model. 0 until the analysis completes. | | `rules` | STRING | JSON string with the signing rules extracted by the AI Model. Decode it to access each entry's `reference`, `content`, `signaturesRequired` and `eligibles[]` with `name`, `taxId`, `role`, `isSignatureRequired` and `isRepresentative`. Empty string (not an empty list) until the analysis completes. | | `tags` | LIST OF STRINGS | Tags associated with the business identity. | | `status` | STRING | Current status of the business identity. Options: "created", "pending", "processing", "canceled", "success", "failed". | | `created` | STRING | Creation datetime. Example: "2026-06-12T12:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2026-06-12T12:00:00.000000+00:00". | ### Create Business Identities `POST /v2/business-identity` Create one or more BusinessIdentities to start the Contract AI flow. Each entry is created in `pending` status. Save the returned `id` — you'll use it as `identityId` when uploading the [Business Attachments](#business-attachment) and as the path parameter on subsequent calls. **Validations:** the CNPJ must be valid, must be active in the official bureau and must return non-empty `representatives` (sócios). **Parameters** | Name | Required | Description | | --- | --- | --- | | `taxId` | REQUIRED | CNPJ of the legal entity, with or without punctuation. Example: "20.018.183/0001-80". | | `tags` | OPTIONAL | List of strings to tag the entity for future queries. | **Request** ```python import starkinfra identities = starkinfra.businessidentity.create([ starkinfra.BusinessIdentity( tax_id="20.018.183/0001-80", tags=["onboarding-123"] ) ]) for identity in identities: print(identity) ``` **Response** ```python [ BusinessIdentity( id="5740539971076096", tax_id="20.018.183/0001-80", name="STARK BANK S.A.", tax_id_status="active", insight_tax_id="", insight_document_type="", representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}], attachments=[], rules=[], tags=["onboarding-123"], status="pending", created="2026-06-12T12:00:00+00:00", updated="2026-06-12T12:00:00+00:00" ) ] ``` ### List Business Identities `GET /v2/business-identity` List and filter all business identities in your workspace. Results are returned paged via cursor. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. | | `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter identities by the specified status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `taxIds` | OPTIONAL | List of CNPJs to filter the response by. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra identities = starkinfra.businessidentity.query( after="2026-06-01", before="2026-06-30", status="success", tags=["onboarding-123"], limit=10 ) for identity in identities: print(identity) ``` **Response** ```python [ BusinessIdentity( id="5740539971076096", tax_id="20.018.183/0001-80", name="STARK BANK S.A.", tax_id_status="active", insight_tax_id="20.018.183/0001-80", insight_document_type="articles-of-incorporation", representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}], attachments=["attachment/5104320788332544"], rules=[{"reference": "Artigo 16, item (a)", "content": "pela assinatura isolada do Diretor Presidente", "signaturesRequired": 1, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": True, "isRepresentative": True}]}], tags=["onboarding-123"], status="success", created="2026-06-12T12:00:00+00:00", updated="2026-06-12T12:10:00+00:00" ) ] ``` ### Get a Business Identity `GET /v2/business-identity/:id` Get a single business identity by its id. When `status=success`, the response includes the populated `rules` string with the signing combinations extracted by the AI Model. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business identity entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra identity = starkinfra.businessidentity.get("5740539971076096") print(identity) ``` **Response** ```python BusinessIdentity( id="5740539971076096", tax_id="20.018.183/0001-80", name="STARK BANK S.A.", tax_id_status="active", insight_tax_id="20.018.183/0001-80", insight_document_type="articles-of-incorporation", representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}], attachments=["attachment/5104320788332544"], rules=[{"reference": "Artigo 16, item (a)", "content": "pela assinatura isolada do Diretor Presidente", "signaturesRequired": 1, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": True, "isRepresentative": True}]}, {"reference": "Artigo 16, item (b)", "content": "pela assinatura de quaisquer 2 (dois) diretores em conjunto", "signaturesRequired": 2, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": False, "isRepresentative": True}, {"name": "Jon Snow", "taxId": "098.765.432-10", "role": "Diretor de Riscos e Compliance", "isSignatureRequired": False, "isRepresentative": True}]}], tags=["onboarding-123"], status="success", created="2026-06-12T12:00:00+00:00", updated="2026-06-12T12:10:00+00:00" ) ``` ### Update a Business Identity `PATCH /v2/business-identity/:id` Send a business identity to processing or replace its tags. To trigger the AI Model analysis, set `status=processing`. The identity must be in `created`/`pending` status and must already have at least one [Business Attachment](#business-attachment) associated with it. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business identity entity. | | `status` | OPTIONAL | Only `processing` is accepted. Triggers the AI Model analysis. | | `tags` | OPTIONAL | Replace the current list of tags. | **Request** ```python import starkinfra identity = starkinfra.businessidentity.update( id="5740539971076096", status="processing" ) print(identity) ``` **Response** ```python BusinessIdentity( id="5740539971076096", tax_id="20.018.183/0001-80", name="STARK BANK S.A.", tax_id_status="active", insight_tax_id="", insight_document_type="", representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}], attachments=["attachment/5104320788332544"], rules=[], tags=["onboarding-123"], status="processing", created="2026-06-12T12:00:00+00:00", updated="2026-06-12T12:05:00+00:00" ) ``` ### Cancel a Business Identity `DELETE /v2/business-identity/:id` Cancel a business identity. Only identities in `created` or `pending` status can be canceled. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business identity entity. | **Request** ```python import starkinfra identity = starkinfra.businessidentity.cancel("5740539971076096") print(identity) ``` **Response** ```python BusinessIdentity( id="5740539971076096", tax_id="20.018.183/0001-80", name="STARK BANK S.A.", tax_id_status="active", insight_tax_id="", insight_document_type="", representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}], attachments=[], rules=[], tags=["onboarding-123"], status="canceled", created="2026-06-12T12:00:00+00:00", updated="2026-06-12T12:03:00+00:00" ) ``` ### List Business Identity Logs `GET /v2/business-identity/log` Get a paged list of all business identity logs. A log tracks a change in the business identity entity according to its lifecycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `identityIds` | OPTIONAL | List of business identity ids linked to the desired logs. Max = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "updated", "processing", "canceled", "success", "failed". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra logs = starkinfra.businessidentity.log.query( types=["success", "failed"], identity_ids=["5740539971076096"], limit=10 ) for log in logs: print(log) ``` **Response** ```python [ BusinessIdentityLog( id="6248173092645824", type="success", identity=BusinessIdentity(id="5740539971076096", status="success"), errors=[], created="2026-06-12T12:10:00+00:00" ) ] ``` ### Get a Business Identity Log `GET /v2/business-identity/log/:id` Get a single business identity log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business identity log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.businessidentity.log.get("6248173092645824") print(log) ``` **Response** ```python BusinessIdentityLog( id="6248173092645824", type="success", identity=BusinessIdentity(id="5740539971076096", status="success"), errors=[], created="2026-06-12T12:10:00+00:00" ) ``` ## Business Attachment BusinessAttachments are corporate documents (articles of incorporation, amendments, board minutes) uploaded against a [Business Identity](#business-identity). Each Business Identity accepts up to two attachments. The attachment goes through OCR and document validation; once both attachments are `approved`, the parent identity can be sent to `processing` to run the AI Model analysis. ### The BusinessAttachment object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the business attachment. | | `name` | STRING | File name as provided on upload. Unique among the identity's other `created` attachments. | | `businessIdentityId` | STRING | Id of the Business Identity that owns this attachment. | | `attachmentId` | STRING | External attachment id in the document repository. Used internally to track approval. | | `tags` | LIST OF STRINGS | Tags associated with the business attachment. | | `status` | STRING | Current status of the attachment. Options: "created", "canceled", "approved", "denied". | | `content` | STRING | Base64-encoded file content. Returned only when the GET request includes `expand=content`. | | `created` | STRING | Creation datetime. Example: "2026-06-12T12:02:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2026-06-12T12:02:00.000000+00:00". | ### Upload a Business Attachment `POST /v2/business-attachment` Upload a single corporate document tied to a previously created [Business Identity](#business-identity). Limit of **1 attachment per request** and **2 attachments per identity**. **Validations:** only PDF, JPG and PNG are accepted, ≤ 8 MB per attachment; the `name` must be unique among the identity's other `created` attachments; the identity must be in `created`/`pending` status and have fewer than 2 attachments. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | File name. Must be unique among the identity's other `created` attachments. | | `content` | REQUIRED | File payload encoded as a base64 string (e.g., `data:application/pdf;base64,...`). | | `identityId` | REQUIRED | Id of the Business Identity that owns the attachment. | | `tags` | OPTIONAL | List of strings to tag the entity for future queries. | **Request** ```python import starkinfra attachments = starkinfra.businessattachment.create([ starkinfra.BusinessAttachment( name="contrato-social.pdf", content="data:application/pdf;base64,JVBERi0xLjQK...", business_identity_id="5740539971076096", tags=["doc-principal"] ) ]) for attachment in attachments: print(attachment) ``` **Response** ```python [ BusinessAttachment( id="6710539971076096", name="contrato-social.pdf", business_identity_id="5740539971076096", attachment_id="5104320788332544", tags=["doc-principal"], status="created", created="2026-06-12T12:02:00+00:00", updated="2026-06-12T12:02:00+00:00" ) ] ``` ### List Business Attachments `GET /v2/business-attachment` List and filter all business attachments in your workspace. Results are returned paged via cursor. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter attachments by status. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra attachments = starkinfra.businessattachment.query( after="2026-06-01", before="2026-06-30", status="approved", tags=["doc-principal"], limit=10 ) for attachment in attachments: print(attachment) ``` **Response** ```python [ BusinessAttachment( id="6710539971076096", name="contrato-social.pdf", business_identity_id="5740539971076096", attachment_id="5104320788332544", tags=["doc-principal"], status="approved", created="2026-06-12T12:02:00+00:00", updated="2026-06-12T12:08:00+00:00" ) ] ``` ### Get a Business Attachment `GET /v2/business-attachment/:id` Get a single business attachment by its id. Pass `expand=content` to include the base64 file payload in the response. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business attachment entity. | | `expand` | OPTIONAL | List of fields to expand. Currently only `content` is supported — when present, the response includes the base64-encoded file payload. | **Request** ```python import starkinfra attachment = starkinfra.businessattachment.get( "6710539971076096", expand=["content"] ) print(attachment) ``` **Response** ```python BusinessAttachment( id="6710539971076096", name="contrato-social.pdf", business_identity_id="5740539971076096", attachment_id="5104320788332544", tags=["doc-principal"], status="approved", content="data:application/pdf;base64,JVBERi0xLjQK...", created="2026-06-12T12:02:00+00:00", updated="2026-06-12T12:08:00+00:00" ) ``` ### Cancel a Business Attachment `DELETE /v2/business-attachment/:id` Cancel a business attachment. Only attachments in `created` status can be canceled. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business attachment entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra attachment = starkinfra.businessattachment.cancel("6710539971076096") print(attachment) ``` **Response** ```python BusinessAttachment( id="6710539971076096", name="contrato-social.pdf", business_identity_id="5740539971076096", attachment_id="5104320788332544", tags=["doc-principal"], status="canceled", created="2026-06-12T12:02:00+00:00", updated="2026-06-12T12:03:30+00:00" ) ``` ### List Business Attachment Logs `GET /v2/business-attachment/log` Get a paged list of all business attachment logs. A log tracks a change in the business attachment entity according to its lifecycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `attachmentIds` | OPTIONAL | List of business attachment ids linked to the desired logs. Max = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "canceled", "approved", "denied". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra logs = starkinfra.businessattachment.log.query( types=["approved", "denied"], attachment_ids=["6710539971076096"], limit=10 ) for log in logs: print(log) ``` **Response** ```python [ BusinessAttachmentLog( id="5719045286731328", type="approved", attachment=BusinessAttachment(id="6710539971076096", status="approved"), errors=[], created="2026-06-12T12:08:00+00:00" ) ] ``` ### Get a Business Attachment Log `GET /v2/business-attachment/log/:id` Get a single business attachment log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business attachment log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.businessattachment.log.get("5719045286731328") print(log) ``` **Response** ```python BusinessAttachmentLog( id="5719045286731328", type="approved", attachment=BusinessAttachment(id="6710539971076096", status="approved"), errors=[], created="2026-06-12T12:08:00+00:00" ) ``` ## Individual Account Attachment Individual Account Attachments are the document images you attach to an [Individual Account Request](#individual-account-request) so the account-approval flow can verify the holder. Each attachment references its parent request by `accountRequestId`. An attachment is created in `created` status. When the parent Individual Account Request is patched to `processing`, every `created` attachment of that request moves to `processing`; once the approval pipeline finishes, they move to `success`. Every transition produces an Individual Account Attachment Log. **NOTE:** One attachment per request, and the same `type` cannot be sent twice for the same Individual Account Request. Document types of different sets cannot be mixed on the same request: send either the identity pair (`identity-front` and `identity-back`) or the driver's license pair (`drivers-license-front` and `drivers-license-back`). ### The IndividualAccountAttachment object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the individual account attachment. Example: "5949351771144192". | | `type` | STRING | Type of document attached. Options: "identity-front", "identity-back", "drivers-license-front", "drivers-license-back". | | `accountRequestId` | STRING | Id of the Individual Account Request that owns this attachment. Example: "5189530608992256". | | `tags` | LIST OF STRINGS | Tags associated with the individual account attachment. | | `status` | STRING | Current status of the attachment. Options: "created", "canceled", "processing", "success", "failed", "deleted". | | `created` | STRING | Creation datetime. Example: "2026-06-12T12:02:00.000000+00:00". | ### Create an Individual Account Attachment `POST /v2/individual-account-attachment` Use this route to attach one document image to a previously created [Individual Account Request](#individual-account-request). **Validations:** the `attachments` array accepts exactly **1 element per request**; `content` must be a base64 data url whose MIME type is `image/png` or `image/jpeg` and whose decoded payload is smaller than 64 MB; the parent Individual Account Request must exist in your workspace and be in `created` status; the `type` must not already be attached to that request, and must belong to the same document set as the types already attached. **Parameters** | Name | Required | Description | | --- | --- | --- | | `type` | REQUIRED | Type of document being attached. Options: "identity-front", "identity-back", "drivers-license-front", "drivers-license-back". Example: "identity-front". | | `content` | REQUIRED | Document image encoded as a base64 data url. Example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...". | | `accountRequestId` | REQUIRED | Id of the Individual Account Request that owns the attachment. Example: "5189530608992256". | | `tags` | OPTIONAL | List of strings to tag the entity for future queries. Max = 100 tags of up to 100 characters each. Example: ["employees", "monthly"]. | **Request** ```python import starkinfra attachments = starkinfra.individualaccountattachment.create([ starkinfra.IndividualAccountAttachment( type="identity-front", content=open("identity-front.png", "rb").read(), content_type="image/png", account_request_id="5189530608992256", tags=["employees", "monthly"] ) ]) for attachment in attachments: print(attachment) ``` **Response** ```python [ IndividualAccountAttachment( id="5949351771144192", type="identity-front", account_request_id="5189530608992256", tags=["employees", "monthly"], status="created", created="2026-06-12T12:02:00.000000+00:00" ) ] ``` ### List Individual Account Attachments `GET /v2/individual-account-attachment` List and filter the individual account attachments in your workspace. Results are returned paged via cursor, newest first. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Example: "2026-06-01". | | `before` | OPTIONAL | Filter entities created before this date. Example: "2026-06-30". | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter attachments by status. Options: "created", "canceled", "processing", "success", "failed", "deleted". | | `tags` | OPTIONAL | Filter entities that contain the specified tags. Example: ["employees", "monthly"]. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100. Example: ["5949351771144192", "4545454545454545"]. | | `accountRequestIds` | OPTIONAL | List of Individual Account Request ids to filter the attachments. Max = 100. Not available in the SDKs. Example: ["5189530608992256"]. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra from datetime import date attachments = starkinfra.individualaccountattachment.query( limit=10, after=date(2026, 6, 1), before=date(2026, 6, 30), status="success", tags=["employees", "monthly"] ) for attachment in attachments: print(attachment) ``` **Response** ```python IndividualAccountAttachment( id="5949351771144192", type="identity-front", account_request_id="5189530608992256", tags=["employees", "monthly"], status="success", created="2026-06-12T12:02:00.000000+00:00" ) IndividualAccountAttachment( id="6304472403935232", type="identity-back", account_request_id="5189530608992256", tags=["employees", "monthly"], status="success", created="2026-06-12T12:04:00.000000+00:00" ) ``` ### Get an Individual Account Attachment `GET /v2/individual-account-attachment/:id` Get a single individual account attachment by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual account attachment entity. Example: "5949351771144192". | **Request** ```python import starkinfra attachment = starkinfra.individualaccountattachment.get("5949351771144192") print(attachment) ``` **Response** ```python IndividualAccountAttachment( id="5949351771144192", type="identity-front", account_request_id="5189530608992256", tags=["employees", "monthly"], status="success", created="2026-06-12T12:02:00.000000+00:00" ) ``` ### Cancel an Individual Account Attachment `DELETE /v2/individual-account-attachment/:id` Cancel an individual account attachment. The returned entity has status `deleted`. Only attachments whose parent [Individual Account Request](#individual-account-request) is still in `created` status can be deleted. **Note:** This action cannot be undone. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual account attachment entity. Example: "5949351771144192". | **Request** ```python import starkinfra attachment = starkinfra.individualaccountattachment.cancel("5949351771144192") print(attachment) ``` **Response** ```python IndividualAccountAttachment( id="5949351771144192", type="identity-front", account_request_id="5189530608992256", tags=["employees", "monthly"], status="deleted", created="2026-06-12T12:02:00.000000+00:00" ) ``` ### List Individual Account Attachment Logs `GET /v2/individual-account-attachment/log` Get a paged list of individual account attachment logs. A log tracks a change in the individual account attachment entity according to its lifecycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Example: "2026-06-01". | | `before` | OPTIONAL | Filter entities created before this date. Example: "2026-06-30". | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "canceled", "deleted", "processing", "sent", "success", "failed". | | `attachmentIds` | OPTIONAL | List of individual account attachment ids linked to the desired logs. Max = 100. Example: ["5949351771144192"]. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra from datetime import date logs = starkinfra.individualaccountattachment.log.query( limit=50, after=date(2026, 6, 1), before=date(2026, 6, 30), types=["created", "success"], attachment_ids=["5949351771144192"] ) for log in logs: print(log) ``` **Response** ```python Log( id="6172091654176768", type="created", errors=[], attachment=IndividualAccountAttachment( id="5949351771144192", type="identity-front", account_request_id="5189530608992256", tags=["employees", "monthly"], status="created", created="2026-06-12T12:02:00.000000+00:00" ), created="2026-06-12T12:02:00.000000+00:00" ) ``` ### Get an Individual Account Attachment Log `GET /v2/individual-account-attachment/log/:id` Get a single individual account attachment log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual account attachment log entity. Example: "6172091654176768". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.individualaccountattachment.log.get("6172091654176768") print(log) ``` **Response** ```python Log( id="6172091654176768", type="created", errors=[], attachment=IndividualAccountAttachment( id="5949351771144192", type="identity-front", account_request_id="5189530608992256", tags=["employees", "monthly"], status="created", created="2026-06-12T12:02:00.000000+00:00" ), created="2026-06-12T12:02:00.000000+00:00" ) ``` ## Individual Identity Individual Identities run an end-to-end identity verification on a Brazilian individual. Each entry wraps the proofs (document and/or facial biometrics) the holder must submit; Stark Infra orchestrates the collection, validates each proof and delivers the result through the `individual-identity` webhook subscription. Identities are created in `created` status and are walked through `processing`, `pending` and finally `success` or `failed` by private workers. Every transition produces an Individual Identity Log. ### The IndividualIdentity object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the individual identity. | | `name` | STRING | Full name of the holder being verified. | | `taxId` | STRING | CPF of the holder. Optional at creation; can be patched later. Example: "012.345.678-90". | | `email` | STRING | E-mail used to deliver the `validatorLink` when `deliveryMethod = automatic`. | | `phone` | STRING | Holder's phone in international format. Optional. | | `tags` | LIST OF STRINGS | Tags associated with the individual identity. | | `proofs` | LIST OF STRINGS | List of proof types required by the identity. Options: `identity`, `biometric`. | | `deliveryMethod` | STRING | How the `validatorLink` reaches the holder. Options: `automatic`, `manual`. | | `validatorLink` | STRING | URL the holder opens to submit each proof. Carries the `identityId` encoded in the `info` query parameter. | | `sourceId` | STRING | Id of the entity that triggered this verification. Filled automatically with the workspace id for external callers. | | `sourceType` | STRING | Origin of the verification. Options: `onboarding`, `reboarding`, `external`. | | `workspaceId` | STRING | Id of the workspace that owns this identity. | | `status` | STRING | Current status of the individual identity. Options: "created", "processing", "pending", "success", "failed". | | `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2026-06-23T12:05:30.000000+00:00". | ### Create Individual Identities `POST /v2/individual-identity` Create one or more Individual Identities. Each entry is returned in `created` status and already carries the `validatorLink` the holder will use to submit each proof. **Validations:** the workspace must have an Identity Profile; every value in `proofs` must be enabled on that profile. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | Full name of the holder being verified. | | `email` | REQUIRED | E-mail used to deliver the `validatorLink` when `deliveryMethod = automatic`. | | `deliveryMethod` | REQUIRED | How the `validatorLink` reaches the holder. Options: `automatic`, `manual`. | | `proofs` | REQUIRED | List of proof types to collect. Each item must be one of `identity`, `biometric` and must be enabled on your workspace's Identity Profile. | | `taxId` | OPTIONAL | CPF of the holder, with or without punctuation. Example: "012.345.678-90". | | `phone` | OPTIONAL | Holder's phone in international format. Example: "+5511987654321". | | `tags` | OPTIONAL | List of strings to tag the entity for future queries. | **Request** ```python import starkinfra identities = starkinfra.individualidentity.create([ starkinfra.IndividualIdentity( name="Daenerys Targaryen Stormborn", email="daenerys@example.com", delivery_method="automatic", proofs=["identity", "biometric"], tax_id="012.345.678-90", phone="+5511987654321", tags=["onboarding-123"] ) ]) for identity in identities: print(identity) ``` **Response** ```python [ IndividualIdentity( id="5740977003561984", name="Daenerys Targaryen Stormborn", tax_id="012.345.678-90", email="daenerys@example.com", phone="+5511987654321", tags=["onboarding-123"], proofs=["identity", "biometric"], delivery_method="automatic", validator_link="https://starkbank.com/validator-link?info=eyJpZGVudGl0eUlkIjoiNTc0MDk3NzAwMzU2MTk4NCJ9", source_id="6480539068923904", source_type="external", workspace_id="6480539068923904", status="created", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:00:00.000000+00:00" ) ] ``` ### List Individual Identities `GET /v2/individual-identity` List and filter all individual identities in your workspace. Results are returned paged via cursor. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. | | `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `status` | OPTIONAL | Filter identities by the specified status. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. | | `taxIds` | OPTIONAL | List of CPFs to filter the response by. | | `email` | OPTIONAL | Filter identities by holder e-mail. | | `tags` | OPTIONAL | Filter entities that contain the specified tags. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra identities = starkinfra.individualidentity.query( status=["pending", "success"], tags=["onboarding-123"], limit=10 ) for identity in identities: print(identity) ``` **Response** ```python [ IndividualIdentity( id="5740977003561984", name="Daenerys Targaryen Stormborn", tax_id="012.345.678-90", status="pending", proofs=["identity", "biometric"], delivery_method="automatic", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:00:10.000000+00:00" ) ] ``` ### Get an Individual Identity `GET /v2/individual-identity/:id` Get a single individual identity by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual identity entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra identity = starkinfra.individualidentity.get("5740977003561984") print(identity) ``` **Response** ```python IndividualIdentity( id="5740977003561984", name="Daenerys Targaryen Stormborn", tax_id="012.345.678-90", email="daenerys@example.com", phone="+5511987654321", tags=["onboarding-123"], proofs=["identity", "biometric"], delivery_method="automatic", validator_link="https://starkbank.com/validator-link?info=eyJpZGVudGl0eUlkIjoiNTc0MDk3NzAwMzU2MTk4NCJ9", source_id="6480539068923904", source_type="external", workspace_id="6480539068923904", status="success", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:05:30.000000+00:00" ) ``` ### Update an Individual Identity `PATCH /v2/individual-identity/:id` Update the `taxId` of an individual identity after it has been created. Useful when the CPF is unknown at creation time and is only collected during the proof submission flow. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual identity entity. | | `taxId` | OPTIONAL | CPF to assign to the identity, with or without punctuation. | **Request** ```python import starkinfra identity = starkinfra.individualidentity.update( id="5740977003561984", tax_id="012.345.678-90" ) print(identity) ``` **Response** ```python IndividualIdentity( id="5740977003561984", name="Daenerys Targaryen Stormborn", tax_id="012.345.678-90", status="pending", proofs=["identity", "biometric"], delivery_method="automatic", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:02:00.000000+00:00" ) ``` ### Cancel an Individual Identity `DELETE /v2/individual-identity/:id` Cancel an individual identity (soft delete). The identity transitions to `failed`, every pending proof is canceled and a `canceled` log is delivered through the webhook. Only identities in `created` or `pending` status can be canceled. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual identity entity. | **Request** ```python import starkinfra identity = starkinfra.individualidentity.cancel("5740977003561984") print(identity) ``` **Response** ```python IndividualIdentity( id="5740977003561984", name="Daenerys Targaryen Stormborn", status="failed", proofs=["identity", "biometric"], delivery_method="automatic", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:03:00.000000+00:00" ) ``` ### List Individual Identity Logs `GET /v2/individual-identity/log` Get a paged list of all individual identity logs. A log tracks a change in the individual identity entity according to its lifecycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `identityIds` | OPTIONAL | List of individual identity ids linked to the desired logs. Max = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "processing", "pending", "updated", "success", "failed", "canceled", "expired". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra logs = starkinfra.individualidentity.log.query( types=["success", "failed"], identity_ids=["5740977003561984"], limit=10 ) for log in logs: print(log) ``` **Response** ```python [ IndividualIdentityLog( id="6661702144623308", type="success", identity=IndividualIdentity(id="5740977003561984", status="success"), errors=[], created="2026-06-23T12:05:30.000000+00:00" ) ] ``` ### Get an Individual Identity Log `GET /v2/individual-identity/log/:id` Get a single individual identity log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual identity log entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.individualidentity.log.get("6661702144623308") print(log) ``` **Response** ```python IndividualIdentityLog( id="6661702144623308", type="success", identity=IndividualIdentity(id="5740977003561984", status="success"), errors=[], created="2026-06-23T12:05:30.000000+00:00" ) ``` ## Individual Identity Proof Each Individual Identity Proof represents one piece of evidence required by the parent [Individual Identity](#individual-identity). One proof is generated per `proofType` requested at creation; the holder submits the content via `PATCH /v2/individual-identity-proof/:id`. Proofs go through their own lifecycle (`pending` → `processing` → `success` / `failed` / `canceled` / `expired`). The parent identity transitions to `success` only when every proof reaches `success`. ### The IndividualIdentityProof object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the individual identity proof. | | `proofType` | STRING | Type of evidence required. Options: `identity`, `biometric`. | | `metadata` | DICTIONARY | Raw payload returned by the provider after the proof is validated. Empty until the proof reaches `processing`. | | `status` | STRING | Current status of the proof. Options: "pending", "processing", "success", "failed", "canceled", "expired". | | `individualIdentityId` | STRING | Id of the parent individual identity. | | `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:10.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2026-06-23T12:03:00.000000+00:00". | ### List Individual Identity Proofs `GET /v2/individual-identity-proof` List the proofs tied to an [Individual Identity](#individual-identity). The `identityId` query parameter is required. **Parameters** | Name | Required | Description | | --- | --- | --- | | `identityId` | REQUIRED | Id of the parent individual identity whose proofs you want to list. | | `status` | OPTIONAL | Filter proofs by status. | | `proofType` | OPTIONAL | Filter proofs by `proofType`. Options: `identity`, `biometric`. | | `ids` | OPTIONAL | List of strings to get specific proofs by ids. | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra proofs = starkinfra.request.get( path="/individual-identity-proof", query={ "identityId": "5740977003561984", "status": ["pending", "processing"], "limit": 10 } ).json() print(proofs) ``` **Response** ```python { 'cursor': None, 'proofs': [ { 'id': '4512334302912512', 'proofType': 'biometric', 'metadata': {}, 'status': 'pending', 'individualIdentityId': '5740977003561984', 'created': '2026-06-23T12:00:10.000000+00:00', 'updated': '2026-06-23T12:00:10.000000+00:00' } ] } ``` ### Get an Individual Identity Proof `GET /v2/individual-identity-proof/:id` Get a single individual identity proof by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual identity proof entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra proof = starkinfra.request.get( path="/individual-identity-proof/4512334302912512" ).json() print(proof) ``` **Response** ```python { 'proof': { 'id': '4512334302912512', 'proofType': 'identity', 'metadata': {'documentId': 'doc-abc-123', 'documentType': 'RG'}, 'status': 'success', 'individualIdentityId': '5740977003561984', 'created': '2026-06-23T12:00:10.000000+00:00', 'updated': '2026-06-23T12:03:00.000000+00:00' } } ``` ### Submit an Individual Identity Proof `PATCH /v2/individual-identity-proof/:id` Submit the content of a proof. This is the step in which the holder's document or biometric is uploaded for validation. **biometric** — `content` is a base64 image string with the facial selfie. **identity** — `content` is a JSON-serialised string carrying the provider's `documentId` and/or the document `file` (base64 image). After a successful PATCH the proof transitions from `pending` to `processing` and the provider validates it asynchronously. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual identity proof being submitted. | | `content` | REQUIRED | Content of the proof, encoded according to the `proofType`. | **Request** ```python import starkinfra proof = starkinfra.request.patch( path="/individual-identity-proof/4512334302912512", body={ "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..." } ).json() print(proof) ``` **Response** ```python { 'proof': { 'id': '4512334302912512', 'proofType': 'biometric', 'metadata': {}, 'status': 'processing', 'individualIdentityId': '5740977003561984', 'created': '2026-06-23T12:00:10.000000+00:00', 'updated': '2026-06-23T12:02:00.000000+00:00' } } ``` ## Individual Account Request An Individual Account Request asks Stark Infra to open an account for a natural person. You submit the individual's identifying data and income, upload the required document images as [Individual Account Attachments](#individual-account-attachment), and then send the request to validation by patching its status to `processing`. Requests are created in `created` status. Once sent to validation, a private worker runs the KYC pipeline against the identity bureaus and writes the final `approved` or `denied` status together with any review `flags`. Every transition produces an Individual Account Request Log. ### The IndividualAccountRequest object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id returned when the individual account request is created. Example: "5656565656565656". | | `taxId` | STRING | CPF of the individual, always returned formatted. Example: "012.345.678-90". | | `name` | STRING | Full name of the individual. Example: "Tony Stark". | | `address` | OBJECT | Structured residential address of the individual. Returned as the nested object you sent, with the keys `street`, `number`, `neighborhood`, `city`, `state`, `zipCode` and, when informed, `complement`. Returned as an empty string when no address is stored. | | `income` | INTEGER | Individual's income in cents. Example: 1000000 (R$10,000.00). | | `birthDate` | STRING | Birth date of the individual. Returned as an empty string when it was not informed. Example: "1965-09-07". | | `status` | STRING | Current status of the individual account request. Options: "created", "processing", "denied", "approved". | | `flags` | LIST OF OBJECTS | Review flags raised by the KYC pipeline. Empty until the request is validated, and empty on an approved request with no restriction. Each flag carries a `code` plus the values that describe it. Example: ``` [{"code": "individualSanctions", "parameter": "012.345.678-90"}] ``` | | `tags` | LIST OF STRINGS | Tags associated with the individual account request, always returned lowercased. Example: ["employees", "monthly"]. | | `accountType` | STRING | Type of account requested. Always "individual" for this resource. Options: "individual", "business". | | `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2026-06-23T12:05:30.000000+00:00". | ### Create Individual Account Requests `POST /v2/individual-account-request` Use this route to create up to 100 new individual account requests at a time. Each entry is returned in `created` status. **NOTE:** Creating a request does not start the validation. Attach the required documents first, then patch the request's status to `processing`. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | Full name of the individual. Must be a string of at least 5 characters. Example: "Tony Stark". | | `taxId` | REQUIRED | CPF of the individual, either as 11 bare digits or fully punctuated. Example: "012.345.678-90". | | `income` | REQUIRED | Individual's income in cents. Must be an integer greater than or equal to zero. Example: 1000000 (R$10,000.00). | | `address` | REQUIRED | Structured residential address of the individual. The keys `street`, `number`, `neighborhood`, `city`, `state` and `zipCode` are all required and must be non-empty strings; `complement` is the only other key accepted, and any additional key is rejected. Example: ``` {"street": "Rua do Estilo Barroco", "number": "648", "neighborhood": "Santo Amaro", "city": "Sao Paulo", "state": "SP", "zipCode": "05724005"} ``` | | `birthDate` | OPTIONAL | Birth date of the individual. Expected format: YYYY-MM-DD. Example: "1965-09-07". | | `tags` | OPTIONAL | List of up to 100 strings to tag the entity for future queries. Each tag is limited to 100 characters and is stored lowercased. Example: ["employees", "monthly"]. | **Request** ```python import starkinfra requests = starkinfra.individualaccountrequest.create([ starkinfra.IndividualAccountRequest( name="Tony Stark", tax_id="012.345.678-90", address=starkinfra.individualaccountrequest.Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"] ) ]) for request in requests: print(request) ``` **Response** ```python [ IndividualAccountRequest( id="5656565656565656", name="Tony Stark", tax_id="012.345.678-90", address=Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"], account_type="individual", flags=[], status="created", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:00:00.000000+00:00" ) ] ``` ### List Individual Account Requests `GET /v2/individual-account-request` Use this route to list and filter the individual account requests in your workspace. Results are returned paged via cursor, from the most recently created to the oldest. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-01". | | `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-30". | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. | | `status` | OPTIONAL | Filter requests by the specified statuses. Options: "created", "processing", "denied", "approved". | | `tags` | OPTIONAL | Filter entities that contain any of the specified tags. Max = 30. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100. When informed, every other filter is applied in memory over these ids and no cursor is returned. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra from datetime import date requests = starkinfra.individualaccountrequest.query( limit=10, after=date(2026, 6, 1), before=date(2026, 6, 30), status=["created", "processing"], tags=["employees", "monthly"] ) for request in requests: print(request) ``` **Response** ```python [ IndividualAccountRequest( id="5656565656565656", name="Tony Stark", tax_id="012.345.678-90", address=Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"], account_type="individual", flags=[], status="created", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:00:00.000000+00:00" ) ] ``` ### Get an Individual Account Request `GET /v2/individual-account-request/:id` Use this route to get a single individual account request by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual account request entity. Example: "5656565656565656". | **Request** ```python import starkinfra request = starkinfra.individualaccountrequest.get("5656565656565656") print(request) ``` **Response** ```python IndividualAccountRequest( id="5656565656565656", name="Tony Stark", tax_id="012.345.678-90", address=Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"], account_type="individual", flags=[], status="approved", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:10:45.000000+00:00" ) ``` ### Update an Individual Account Request `PATCH /v2/individual-account-request/:id` Use this route to correct the data of an individual account request, or to send it to validation by patching its status to `processing`. Every parameter is optional, and the ones you omit are left untouched. **NOTE:** `processing` is the only status you may send, it is only accepted for a request currently in `created` status, and it is only accepted once a complete document set has been attached to the request. Sending it also moves every `created` attachment of the request to `processing`. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual account request entity. Example: "5656565656565656". | | `status` | OPTIONAL | Status to send the request to validation. Options: "processing". | | `name` | OPTIONAL | New full name of the individual. Must be a string of at least 5 characters. Example: "Tony Stark". | | `taxId` | OPTIONAL | New CPF of the individual, either as 11 bare digits or fully punctuated. Example: "012.345.678-90". | | `income` | OPTIONAL | New income in cents. Must be an integer greater than or equal to zero. Example: 1500000 (R$15,000.00). | | `address` | OPTIONAL | New structured residential address. Replaces the stored address as a whole, it is not deep-merged, so send every required key again. Example: ``` {"street": "Avenida Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "Sao Paulo", "state": "SP", "zipCode": "01310100"} ``` | | `birthDate` | OPTIONAL | New birth date of the individual. Expected format: YYYY-MM-DD. Example: "1965-09-07". | | `tags` | OPTIONAL | New list of up to 100 strings to tag the entity. Replaces the stored list as a whole. Example: ["employees", "monthly"]. | **Request** ```python import starkinfra request = starkinfra.individualaccountrequest.update( "5656565656565656", status="processing" ) print(request) ``` **Response** ```python IndividualAccountRequest( id="5656565656565656", name="Tony Stark", tax_id="012.345.678-90", address=Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"], account_type="individual", flags=[], status="processing", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:05:30.000000+00:00" ) ``` ### List Individual Account Request Logs `GET /v2/individual-account-request/log` Use this route to get a paged list of individual account request logs. A log tracks a change in the individual account request entity according to its life cycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-01". | | `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-30". | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "processing", "updated", "denied", "approved". | | `accountRequestIds` | OPTIONAL | List of individual account request ids linked to the desired logs. Max = 100. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra from datetime import date logs = starkinfra.individualaccountrequest.log.query( limit=50, after=date(2026, 6, 1), before=date(2026, 6, 30), types=["approved", "denied"], account_request_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="4545454545454545", type="denied", errors=[], request=IndividualAccountRequest( id="5656565656565656", name="Tony Stark", tax_id="012.345.678-90", address=Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"], account_type="individual", flags=[{"code": "individualSanctions", "parameter": "OFAC SDN"}], status="denied", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:10:45.000000+00:00" ), created="2026-06-23T12:10:45.000000+00:00" ) ``` ### Get an Individual Account Request Log `GET /v2/individual-account-request/log/:id` Use this route to get a single individual account request log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the individual account request log entity. Example: "5656565656565656". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.individualaccountrequest.log.get("4545454545454545") print(log) ``` **Response** ```python Log( id="4545454545454545", type="denied", errors=[], request=IndividualAccountRequest( id="5656565656565656", name="Tony Stark", tax_id="012.345.678-90", address=Address( street="Rua do Estilo Barroco", number="648", neighborhood="Santo Amaro", city="Sao Paulo", state="SP", zip_code="05724005" ), income=1000000, birth_date="1965-09-07", tags=["employees", "monthly"], account_type="individual", flags=[{"code": "individualSanctions", "parameter": "OFAC SDN"}], status="denied", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:10:45.000000+00:00" ), created="2026-06-23T12:10:45.000000+00:00" ) ``` ## Business Account Request A Business Account Request asks Stark Infra to open an account for a company. You submit the company's legal name, its CNPJ, its structured address, its annual revenue and the list of its owners, upload the corporate documents, and then send the request to validation by patching its status to `processing`. Requests are created in `created` status. Once sent to validation, a private worker runs the KYC pipeline over the company and each of its owners and writes the final `approved` or `denied` status together with any review `flags`. A request whose bureau lookups keep erroring ends in `failed` instead. Every transition produces a Business Account Request Log. ### The BusinessAccountRequest object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id returned when the business account request is created. Example: "5656565656565656". | | `taxId` | STRING | CNPJ of the company, always returned formatted. Example: "20.018.183/0001-80". | | `name` | STRING | Legal name of the company. Example: "Stark Bank S.A.". | | `address` | OBJECT | Structured address of the company. Returned as the nested object you sent, with the keys `street`, `number`, `neighborhood`, `city`, `state`, `zipCode` and, when informed, `complement`. Returned as null when no address is stored. | | `owners` | LIST OF OBJECTS | Owners of the company, from 1 to 10 entries. Each entry carries the `taxId`, `name` and `role` you sent, plus the return-only `identityId`, `validatorLink` and `status` of that owner's identity verification. Example: ``` [{"taxId": "012.345.678-90", "name": "Jamie Lannister", "role": "partner", "identityId": "5709594221805568", "validatorLink": "https://validator.starkinfra.com/5709594221805568", "status": "created"}] ``` | | `revenue` | INTEGER | Company's annual revenue in cents. Example: 100000000 (R$1,000,000.00). | | `status` | STRING | Current status of the business account request. Options: "created", "processing", "denied", "approved", "failed". | | `flags` | LIST OF OBJECTS | Review flags raised by the KYC pipeline. Empty until the request is validated, and empty on an approved request with no restriction. Each flag carries a `code` and the `message` that describes it. Example: ``` [{"code": "failedIdentityProof", "message": "O representante: 012.345.678-90 falhou na verificacao de identidade."}] ``` | | `tags` | LIST OF STRINGS | Tags associated with the business account request, always returned lowercased. Example: ["employees", "monthly"]. | | `accountType` | STRING | Type of account requested. Always "business" for this resource. Options: "individual", "business". | | `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:00.000000+00:00". | | `updated` | STRING | Last update datetime. Example: "2026-06-23T12:05:30.000000+00:00". | ### Create Business Account Requests `POST /v2/business-account-request` Use this route to create up to 100 new business account requests at a time. Each entry is returned in `created` status. **NOTE:** Creating a request does not start the validation. Attach a corporate document first, deliver each owner's `validatorLink`, then patch the request's status to `processing`. **Parameters** | Name | Required | Description | | --- | --- | --- | | `name` | REQUIRED | Legal name of the company. Must be a string of at least 5 characters. Example: "Stark Bank S.A.". | | `taxId` | REQUIRED | CNPJ of the company, either as 14 bare digits or fully punctuated. Example: "20.018.183/0001-80". | | `revenue` | REQUIRED | Company's annual revenue in cents. Must be an integer greater than or equal to zero. Example: 100000000 (R$1,000,000.00). | | `address` | REQUIRED | Structured address of the company. The keys `street`, `number`, `neighborhood`, `city`, `state` and `zipCode` are all required and must be non-empty strings; `complement` is the only other key accepted, and any additional key is rejected. Example: ``` {"street": "Av. Faria Lima", "number": "2000", "neighborhood": "Itaim Bibi", "city": "Sao Paulo", "state": "SP", "zipCode": "04538-132"} ``` | | `owners` | REQUIRED | List of 1 to 10 owners of the company. Each entry requires `taxId` (CPF), `name` and `role`. Options for `role`: "partner", "representative". Example: ``` [{"taxId": "012.345.678-90", "name": "Jamie Lannister", "role": "partner"}] ``` | | `tags` | OPTIONAL | List of up to 100 strings to tag the entity for future queries. Each tag is limited to 100 characters and is stored lowercased. Example: ["employees", "monthly"]. | **Request** ```python import starkinfra requests = starkinfra.businessaccountrequest.create([ starkinfra.BusinessAccountRequest( name="Stark Bank S.A.", tax_id="20.018.183/0001-80", revenue=100000000, address=starkinfra.businessaccountrequest.Address( street="Av. Faria Lima", number="2000", neighborhood="Itaim Bibi", city="Sao Paulo", state="SP", zip_code="04538-132" ), owners=[ starkinfra.businessaccountrequest.Owner( tax_id="012.345.678-90", name="Jamie Lannister", role="partner" ) ], tags=["employees", "monthly"] ) ]) for request in requests: print(request) ``` **Response** ```python [ BusinessAccountRequest( id="5656565656565656", name="Stark Bank S.A.", tax_id="20.018.183/0001-80", address=Address( street="Av. Faria Lima", number="2000", neighborhood="Itaim Bibi", city="Sao Paulo", state="SP", zip_code="04538-132" ), owners=[ Owner( tax_id="012.345.678-90", name="Jamie Lannister", role="partner", identity_id="5709594221805568", validator_link="https://validator.starkinfra.com/5709594221805568", status="created" ) ], revenue=100000000, tags=["employees", "monthly"], account_type="business", flags=[], status="created", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:00:00.000000+00:00" ) ] ``` ### List Business Account Requests `GET /v2/business-account-request` Use this route to list and filter the business account requests in your workspace. Results are returned paged via cursor, from the most recently created to the oldest. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-01". | | `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-30". | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. | | `status` | OPTIONAL | Filter requests by the specified statuses. Options: "created", "processing", "denied", "approved", "failed". | | `tags` | OPTIONAL | Filter entities that contain any of the specified tags. | | `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100. When informed, every other filter is applied in memory over these ids and no cursor is returned. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra from datetime import date requests = starkinfra.businessaccountrequest.query( limit=10, after=date(2026, 6, 1), before=date(2026, 6, 30), status=["created", "processing"], tags=["employees", "monthly"] ) for request in requests: print(request) ``` **Response** ```python [ BusinessAccountRequest( id="5656565656565656", name="Stark Bank S.A.", tax_id="20.018.183/0001-80", address=Address( street="Av. Faria Lima", number="2000", neighborhood="Itaim Bibi", city="Sao Paulo", state="SP", zip_code="04538-132" ), owners=[ Owner( tax_id="012.345.678-90", name="Jamie Lannister", role="partner", identity_id="5709594221805568", validator_link="https://validator.starkinfra.com/5709594221805568", status="created" ) ], revenue=100000000, tags=["employees", "monthly"], account_type="business", flags=[], status="created", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:00:00.000000+00:00" ) ] ``` ### Get a Business Account Request `GET /v2/business-account-request/:id` Use this route to get a single business account request by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business account request entity. Example: "5656565656565656". | **Request** ```python import starkinfra request = starkinfra.businessaccountrequest.get("5656565656565656") print(request) ``` **Response** ```python BusinessAccountRequest( id="5656565656565656", name="Stark Bank S.A.", tax_id="20.018.183/0001-80", address=Address( street="Av. Faria Lima", number="2000", neighborhood="Itaim Bibi", city="Sao Paulo", state="SP", zip_code="04538-132" ), owners=[ Owner( tax_id="012.345.678-90", name="Jamie Lannister", role="partner", identity_id="5709594221805568", validator_link="https://validator.starkinfra.com/5709594221805568", status="approved" ) ], revenue=100000000, tags=["employees", "monthly"], account_type="business", flags=[], status="approved", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:10:45.000000+00:00" ) ``` ### Update a Business Account Request `PATCH /v2/business-account-request/:id` Use this route to correct the data of a business account request, or to send it to validation by patching its status to `processing`. Every parameter is optional, and the ones you omit are left untouched. **NOTE:** `processing` is the only status you may send, it is only accepted for a request currently in `created` status, and it is only accepted once an `article-of-incorporation` or a `general-meeting-minute` attachment has been attached to the request. Sending it also moves every `created` attachment of the request to `processing`. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business account request entity. Example: "5656565656565656". | | `status` | OPTIONAL | Status to send the request to validation. Options: "processing". | | `name` | OPTIONAL | New legal name of the company. Must be a string of at least 5 characters. Example: "Stark Bank S.A.". | | `taxId` | OPTIONAL | New CNPJ of the company, either as 14 bare digits or fully punctuated. Example: "20.018.183/0001-80". | | `revenue` | OPTIONAL | New annual revenue in cents. Must be an integer greater than or equal to zero. Example: 150000000 (R$1,500,000.00). | | `address` | OPTIONAL | New structured address of the company. Replaces the stored address as a whole, it is not deep-merged, so send every required key again. Example: ``` {"street": "Avenida Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "Sao Paulo", "state": "SP", "zipCode": "01310100"} ``` | | `tags` | OPTIONAL | New list of up to 100 strings to tag the entity. Replaces the stored list as a whole. Example: ["employees", "monthly"]. | **Request** ```python import starkinfra request = starkinfra.request.patch( path="/business-account-request/5656565656565656", body={ "status": "processing" } ).json() print(request) ``` **Response** ```python { 'request': { 'accountType': 'business', 'address': { 'city': 'Sao Paulo', 'neighborhood': 'Itaim Bibi', 'number': '2000', 'state': 'SP', 'street': 'Av. Faria Lima', 'zipCode': '04538-132' }, 'created': '2026-06-23T12:00:00.000000+00:00', 'flags': [], 'id': '5656565656565656', 'name': 'Stark Bank S.A.', 'owners': [ { 'identityId': '5709594221805568', 'name': 'Jamie Lannister', 'role': 'partner', 'status': 'created', 'taxId': '012.345.678-90', 'validatorLink': 'https://validator.starkinfra.com/5709594221805568' } ], 'revenue': 100000000, 'status': 'processing', 'tags': ['employees', 'monthly'], 'taxId': '20.018.183/0001-80', 'updated': '2026-06-23T12:05:30.000000+00:00' } } ``` ### List Business Account Request Logs `GET /v2/business-account-request/log` Use this route to get a paged list of business account request logs. A log tracks a change in the business account request entity according to its life cycle. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-01". | | `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-30". | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. | | `types` | OPTIONAL | Filter logs by log type. Options: "created", "processing", "updated", "denied", "approved", "failed". | | `accountRequestIds` | OPTIONAL | List of business account request ids linked to the desired logs. Max = 100. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra from datetime import date logs = starkinfra.businessaccountrequest.log.query( limit=50, after=date(2026, 6, 1), before=date(2026, 6, 30), types=["approved", "denied"], account_request_ids=["5656565656565656"] ) for log in logs: print(log) ``` **Response** ```python Log( id="4545454545454545", type="denied", errors=[], request=BusinessAccountRequest( id="5656565656565656", name="Stark Bank S.A.", tax_id="20.018.183/0001-80", address=Address( street="Av. Faria Lima", number="2000", neighborhood="Itaim Bibi", city="Sao Paulo", state="SP", zip_code="04538-132" ), owners=[ Owner( tax_id="012.345.678-90", name="Jamie Lannister", role="partner", identity_id="5709594221805568", validator_link="https://validator.starkinfra.com/5709594221805568", status="denied" ) ], revenue=100000000, tags=["employees", "monthly"], account_type="business", flags=[{"code": "failedIdentityProof", "message": "O representante: 012.345.678-90 falhou na verificacao de identidade."}], status="denied", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:10:45.000000+00:00" ), created="2026-06-23T12:10:45.000000+00:00" ) ``` ### Get a Business Account Request Log `GET /v2/business-account-request/log/:id` Use this route to get a single business account request log by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the business account request log entity. Example: "5656565656565656". | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra log = starkinfra.businessaccountrequest.log.get("4545454545454545") print(log) ``` **Response** ```python Log( id="4545454545454545", type="denied", errors=[], request=BusinessAccountRequest( id="5656565656565656", name="Stark Bank S.A.", tax_id="20.018.183/0001-80", address=Address( street="Av. Faria Lima", number="2000", neighborhood="Itaim Bibi", city="Sao Paulo", state="SP", zip_code="04538-132" ), owners=[ Owner( tax_id="012.345.678-90", name="Jamie Lannister", role="partner", identity_id="5709594221805568", validator_link="https://validator.starkinfra.com/5709594221805568", status="denied" ) ], revenue=100000000, tags=["employees", "monthly"], account_type="business", flags=[{"code": "failedIdentityProof", "message": "O representante: 012.345.678-90 falhou na verificacao de identidade."}], status="denied", created="2026-06-23T12:00:00.000000+00:00", updated="2026-06-23T12:10:45.000000+00:00" ), created="2026-06-23T12:10:45.000000+00:00" ) ``` ## Individual Holmes Individual Holmes queries an external bureau or one of Stark Infra's internal datasets to investigate an individual (CPF). Each request targets a single bureau through the `type` path parameter and returns that bureau's payload under a key named after the `type` queried. Use Individual Holmes to run KYC, anti-fraud, judicial, sanctions and federal-revenue checks on a person before onboarding, granting credit or releasing a high-risk operation. Every call is synchronous, scoped to your workspace and logged on Stark Infra's side — there is no resource lifecycle to track. ### Query an Individual Bureau `GET /individual-holmes/:searchKey/:type` Path params identify what to look up. The `searchKey` is a CPF (11 digits, masked or unmasked) for every bureau except `internationalPep`, where it is the person's full name. The `type` selects the bureau and the shape of the response. Query params control paging. Only `civil` and `criminal` (JusBrasil) honour `cursor` — repeat the request with the returned cursor to fetch the next page. **Parameters** | Name | Required | Description | | --- | --- | --- | | `searchKey` | REQUIRED | CPF of the individual being investigated, masked or unmasked. Example: `012.345.678-90`. For the `internationalPep` bureau, send the person's full name instead. | | `type` | REQUIRED | Bureau to query. Options: `civil`, `criminal`, `frauds`, `data`, `dict`, `kyc`, `nationalPep`, `internationalPep`, `jointResolution6`, `csnu`, `federalRevenueRegistry`, `deceased`, `negativeMedia`. | | `limit` | OPTIONAL | Maximum number of items per page for paginated bureaus. Integer in the `1..100` range. Defaults to `100`. | | `cursor` | OPTIONAL | Opaque page token returned by the previous call. Only meaningful for `civil` and `criminal`; ignored by every other bureau. | **Request** ```python import starkinfra result = starkinfra.request.get( path="/individual-holmes/01234567890/kyc" ).json() print(result) ``` **Response** ```python The payload key and its inner shape depend on the bureau "type" queried. For each type (civil, criminal, frauds, data, dict, kyc, nationalPep, internationalPep, jointResolution6, csnu, federalRevenueRegistry, deceased, negativeMedia) the response is documented in the corresponding section of the get-started. ``` ## Business Holmes Business Holmes queries an external bureau or one of Stark Infra's internal datasets to investigate a legal entity (CNPJ). Each request targets a single bureau through the `type` path parameter and returns that bureau's payload under a key named after the `type` queried. Use Business Holmes to run KYB, judicial, anti-fraud, sanctions, QSA (corporate structure) and federal-revenue checks on a company before onboarding it, granting credit or releasing a high-risk operation. Every call is synchronous, scoped to your workspace and logged on Stark Infra's side — there is no resource lifecycle to track. ### Query a Business Bureau `GET /business-holmes/:taxId/:type` Path params identify what to look up. The `taxId` is the company's CNPJ (14 digits, masked or unmasked); the `type` selects the bureau and the shape of the response. Query params control paging. Only `civil` and `criminal` (JusBrasil) honour `cursor` — repeat the request with the returned cursor to fetch the next page. **Parameters** | Name | Required | Description | | --- | --- | --- | | `taxId` | REQUIRED | CNPJ of the company being investigated, masked or unmasked. Example: `20.018.183/0001-80`. | | `type` | REQUIRED | Bureau to query. Options: `civil`, `criminal`, `kyc`, `frauds`, `data`, `dict`, `jointResolution6`, `federalRevenueRegistry`, `negativeMedia`, `qsa`. | | `limit` | OPTIONAL | Maximum number of items per page for paginated bureaus. Integer in the `1..100` range. Defaults to `100`. | | `cursor` | OPTIONAL | Opaque page token returned by the previous call. Only meaningful for `civil` and `criminal`; ignored by every other bureau. | **Request** ```python import starkinfra result = starkinfra.request.get( path="/business-holmes/20018183000180/kyc" ).json() print(result) ``` **Response** ```python The payload key and its inner shape depend on the bureau "type" queried. For each type (civil, criminal, kyc, frauds, data, dict, jointResolution6, federalRevenueRegistry, negativeMedia, qsa) the response is documented in the corresponding section of the get-started. ``` # Others ## Webhook You can create webhook subscriptions to receive events whenever a new log is created. We send the event by making a POST request to your endpoint URL. The event will be delivered with a digital signature (headers["Digital-Signature"]), which can be verified using the Stark Infra public key. If your endpoint URL does not return a 200 status, the webhook service will try again at most three times. The interval between each attempt is 5 min, 30 min and finally 120 min. **NOTE 1:** Registered webhooks will only work for services used in that same version. **NOTE 2:** Even if you use Webhook, we strongly recommend that you create a daily task to get all undelivered events and set them as delivered. It's important to add redundancy and resilience to your system. ### The Webhook Object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the webhook subscription. | | `url` | STRING | Endpoint URL that receives webhook events. | | `subscriptions` | LIST OF STRINGS | List of subscribed event types. | ### Create a Webhook `POST /v2/webhook` Register a new webhook URL. The subscriptions refer to which kinds of logs will be sent to the webhook URL being registered. Available subscriptions: pix-request, pix-reversal, pix-pull-subscription, pix-pull-request, pix-internal-transaction-report, pix-key, pix-key-holmes, pix-claim, pix-infraction, pix-chargeback, pix-dispute, issuing-card, issuing-holder, issuing-purchase, issuing-invoice, credit-note or credit-holmes **Parameters** | Name | Required | Description | | --- | --- | --- | | `url` | REQUIRED | The server URL that will receive the Webhook Events. | | `subscriptions` | REQUIRED | Array of subscriptions. Possible values: "pix-request", "pix-reversal", "pix-pull-subscription", "pix-pull-request", "pix-internal-transaction-report", "pix-key", "pix-key-holmes", "pix-claim", "pix-infraction", "pix-chargeback", "pix-dispute", "issuing-card", "issuing-holder", "issuing-purchase", "issuing-invoice", "credit-note" or "credit-holmes" | **Request** ```python import starkinfra webhook = starkinfra.webhook.create( url="https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec", subscriptions=[ "pix-request", "pix-reversal", "pix-key", "credit-note", "credit-holmes" ] ) print(webhook) ``` **Response** ```python Webhook( id=5601079539523584, url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec, subscriptions=['pix-request', 'pix-reversal', 'pix-key', 'credit-note', 'credit-holmes'] ) ``` ### List Webhooks `GET /v2/webhook` Get a list of non-deleted webhooks in chunks of at most 100. If you need smaller chunks, use the limit parameter. **Parameters** | Name | Required | Description | | --- | --- | --- | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `limit` | OPTIONAL | Maximum number of Webhooks to be retrieved. Max = 100. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra webhooks = starkinfra.webhook.query(limit=10) for webhook in webhooks: print(webhook) ``` **Response** ```python Webhook( id=5601079539523584, url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec, subscriptions=['pix-request', 'credit-note'] ) ``` ### Get a Webhook `GET /v2/webhook/:id` Get a single Webhook by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the webhook entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra webhook = starkinfra.webhook.get("5601079539523584") print(webhook) ``` **Response** ```python Webhook( id=5601079539523584, url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec, subscriptions=['pix-request', 'credit-note'] ) ``` ### Delete a Webhook `DELETE /v2/webhook/:id` Delete a single Webhook subscription. **NOTE:** This action cannot be undone. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Webhook to be deleted. | **Request** ```python import starkinfra webhook = starkinfra.webhook.delete("5601079539523584") print(webhook) ``` **Response** ```python Webhook( id=5601079539523584, url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec, subscriptions=['pix-request', 'credit-note'] ) ``` ## Event Every time a log is created, a corresponding event will be generated and sent to you by **webhook**, if the appropriate subscription was set. Therefore, the event represents an occurrence in your workspace. **NOTE:** All the events have a log property containing an entity log. The nature of the log, however, may change according to the subscription that triggered the event. For example, if the subscription is credit-note, the log in the event will be a CreditNoteLog. ### The Event object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the event. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `isDelivered` | STRING | Whether the event has been successfully delivered. Options: "true", "false". | | `subscription` | STRING | Subscription that triggered the event. | | `workspaceId` | STRING | ID of the workspace the event belongs to. | ### List Events `GET /v2/event` Get a list of non-deleted events in chunks of at most 100. If you need smaller chunks, use the limit parameter. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Date filter for Events created only after a specific date. Example: "2022-01-20" | | `before` | OPTIONAL | Date filter for Events created only before a specific date. Example: "2022-02-20" | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `isDelivered` | OPTIONAL | If false, only gets Events that haven't been delivered. If true, only gets Events that have already been delivered. | | `limit` | OPTIONAL | Maximum number of Events to be retrieved. Max = 100. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra events = starkinfra.event.query(limit=10, is_delivered=False) for event in events: print(event) ``` **Response** ```python Event( id=5719405850615809, log=CreditNote.Log(id=5155165527080961, type=created), created=2022-06-01T00:00:00.000000+00:00, is_delivered=False, subscription=credit-note, workspace_id=4019167990849536 ) ``` ### Get an Event `GET /v2/event/:id` Get a single Event by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Unique id of the event entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra event = starkinfra.event.get("5719405850615809") print(event) ``` **Response** ```python Event( id=5719405850615809, log=CreditNote.Log(id=5155165527080961, type=created), created=2022-06-01T00:00:00.000000+00:00, is_delivered=False, subscription=credit-note, workspace_id=4019167990849536 ) ``` ### Delete an Event `DELETE /v2/event/:id` Delete a single Event from the event list. **Note:** This action cannot be undone. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the Event entity to be deleted. | **Request** ```python import starkinfra event = starkinfra.event.delete("5719405850615809") print(event) ``` **Response** ```python Event( id=5719405850615809, log=CreditNote.Log(id=5155165527080961, type=created), created=2022-06-01T00:00:00.000000+00:00, is_delivered=False, subscription=credit-note, workspace_id=4019167990849536 ) ``` ### Update an Event `PATCH /v2/event/:id` The only information you can update in an Event is the isDelivered property. This can be useful when, after experiencing server downtime on your side, you list all events with isDelivered=false, process them, and then set them as delivered to stabilize your operations. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Id of the event entity. Example: "5719405850615809" | | `isDelivered` | REQUIRED | Bool signaling if the Event has or hasn't been successfully delivered. | **Request** ```python import starkinfra event = starkinfra.event.update( "5719405850615809", is_delivered=True ) print(event) ``` **Response** ```python Event( id=5719405850615809, log=CreditNote.Log(id=5155165527080961, type=created), created=2022-06-01T00:00:00.000000+00:00, is_delivered=True, subscription=credit-note, workspace_id=4019167990849536 ) ``` ## Event Attempt When an [Event](#event) delivery fails, an event attempt will be registered. It carries information meant to help you debug event reception issues. ### The Event Attempt object **Attributes** | Name | Type | Description | | --- | --- | --- | | `id` | STRING | Unique id for the event attempt. | | `code` | STRING | Delivery error code. | | `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". | | `eventId` | STRING | ID of the associated Event. | | `message` | STRING | Delivery error description. | | `webhookId` | STRING | ID of the associated Webhook. | ### List failed Webhook Event delivery attempts `GET /v2/event/attempt` Get information on failed webhook event delivery attempts. **Parameters** | Name | Required | Description | | --- | --- | --- | | `after` | OPTIONAL | Filter entities created after this date. | | `before` | OPTIONAL | Filter entities created before this date. | | `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. | | `eventIds` | OPTIONAL | List of Event ids to filter attempts. Example: ["5656565656565656", "4545454545454545"] | | `limit` | OPTIONAL | Number of results per cursor. Max = 100. | | `webhookIds` | OPTIONAL | List of Webhook ids to filter attempts. Example: ["5656565656565656", "4545454545454545"] | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra attempts = starkinfra.event.attempt.query(limit=10) for attempt in attempts: print(attempt) ``` **Response** ```python Attempt( id=6891221774008321, code=CONNECTION_ERROR, message=Connection refused, event_id=5719405850615809, webhook_id=5601079539523584, created=2022-06-01T00:00:00.000000+00:00 ) ``` ### Get an Event Attempt `GET /v2/event/attempt/:id` Get a single event attempt by its id. **Parameters** | Name | Required | Description | | --- | --- | --- | | `id` | REQUIRED | Unique id of the event attempt entity. | | `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. | **Request** ```python import starkinfra attempt = starkinfra.event.attempt.get("6891221774008321") print(attempt) ``` **Response** ```python Attempt( id=6891221774008321, code=CONNECTION_ERROR, message=Connection refused, event_id=5719405850615809, webhook_id=5601079539523584, created=2022-06-01T00:00:00.000000+00:00 ) ```