Card Issuing

Setup

For each environment (Sandbox and Production):

1. Create an account at Stark Bank.

2. Get in touch with your account manager to define your Issuing Product: pre-paid or credit card — the product determines network (Visa/Mastercard), default rules and BIN.

3. Inform the sub-issuer parameters to help@starkbank.com:

authorizationUrl: HTTPS URL to receive synchronous Issuing Purchase authorizations from your cards. If empty, the following parameters will dictate your authorizations.
defaultAuthorizationMaxAmount: Maximum amount in Reais (R$) that the default authorization system will approve in case your system does not respond correctly. Minimum is R$0,00.
defaultAuthorizationMinScore: Minimum score that the default authorization will approve. The score ranges from 0 (worst) to 1 (best).

4. Create a Webhook resource subscribing to issuing-card, issuing-holder, issuing-purchase, issuing-invoice, issuing-embossing-request events.

5. Fund the issuing balance with an Issuing Invoice before issuing your first card.

Authorization flow

Every card purchase is authorized in real time. Stark Infra receives the authorization message from the card network and forwards it to the authorizationUrl you registered during Setup as a synchronous request.

We screen every purchase before calling you. Stark Infra first checks that the card and holder are active, that the purchase fits the spending controls set on the card and/or holder, that your issuing balance as a sub issuer covers it, and that the merchant, country, payment method and installments are eligible — and it computes a fraud score for the purchase. If any of these checks fails we deny the purchase ourselves and your authorizationUrl is never called; only purchases that clear them are forwarded to you (with the score) for the final decision.

Issuing basic flow

Your endpoint must answer within 2 seconds, always with HTTP status 200 — even when you decline. To approve, return {"authorization": {"status": "approved"}} (you may also override the amount - by a smaller one, if the field isPartialAllowed is true - or attach tags). To decline, return {"authorization": {"status": "denied", "reason": "..."}} with one of the accepted denial reasons — download the full list here.

If you do not respond in time (or you never registered an authorizationUrl), the request is not automatically denied: the default authorization protocol takes over and decides on your behalf. It approves the purchase when the amount is within the defaultAuthorizationMaxAmount and the purchase score is at least the defaultAuthorizationMinScore you configured during Setup, and declines it otherwise (reason standInDenial). A timeout can therefore still result in an approval.

NOTE: Because the default authorization protocol can approve or deny a purchase your system was still processing, prepare for concurrency — you may receive the approved / denied Issuing Purchase events for a purchase before your own authorization logic finishes. Reconcile by endToEndId so the same purchase is not registered twice.

Issuing Card Overview

An Issuing Card is a credit or pre-paid card you issue to an Issuing Holder.

Virtual vs. physical. A virtual card is created instantly with status "active" and can be used for online purchases right away. A physical card is created with status "pending": it must be embossed and shipped through an Issuing Embossing Request, and then activated (set its status to "active" together with a PIN) before it can be used.

Getting a productId. Every card must reference a productId — the card product, which sets its BIN range. A product defines the card's network (Visa/Mastercard), funding type (credit or pre-paid), holder type (business or individual) and tier (e.g.: Black, Platinum). See the Issuing Product section to learn more.

Spending controls. Pass a "rules" list when creating or updating a card (or its holder) to cap how much can be spent per interval and to restrict categories, countries or methods. Each rule tracks how much was already spent in the current interval (counterAmount). See the Issuing Rule section for the full rule object and how to set or change it.

Card Statuses

Each Issuing Card has a status that reflects where it is in its life cycle:

Issuing Card life cycle

Status	Description
pending	A physical card was created but is not usable yet. Activate it by setting its status to "active" together with a PIN. Virtual cards skip this status.
active	The card is active and can be used for purchases.
blocked	The card is temporarily blocked. You can unblock it by setting its status back to "active".
expired	The card has passed its expiration date and can no longer be used.
canceled	The card was permanently canceled. This is irreversible.

Card Logs

Every time you or Stark Infra change an Issuing Card, we create a Log entry. Logs let you audit a card's full history — each status change, rule update and so on.

Query the card logs with GET /v2/issuing-card/log (filter by cardIds, types, after / before), or fetch a single one with GET /v2/issuing-card/log/:id. Check the API reference for the full list of log fields and types.

Creating a Card

Create one or more cards by sending a "cards" list. Each card needs holderName, holderTaxId, holderExternalId and a productId.

Holder resolution. The card's holder is identified by its holderExternalId. If no holder with that external id exists under your sub-issuer yet, one is created from the holderName and holderTaxId you send; if a holder with that external id already exists, the card is attached to it. In that case the holderName and holderTaxId must match the existing holder — otherwise the request is rejected.

Set "type" to "virtual" (the default — instantly active) or "physical" (created as "pending", needs embossing, shipment and activation).

Billing address. If you omit the address, the card inherits your sub-issuer's registered address by default. The address is all-or-nothing: send the complete address (streetLine1, streetLine2, district, city, stateCode, zipCode) or none — a partial address is rejected.

ENDPOINT

POST /v2/issuing-card

Unblocking (activating) a physical card

A physical card is created as "pending". To activate it, set its status to "active" together with a "pin" (a numeric string, 4 to 6 digits) — its first activation always requires a PIN.

NOTE: To unblock a card that was merely blocked (and had already been activated before), you can send "status": "active" on its own, without a PIN.

ENDPOINT

PATCH /v2/issuing-card/:id

Blocking a card

Temporarily block a card by setting its status to "blocked". A blocked card declines purchases until you unblock it.

ENDPOINT

PATCH /v2/issuing-card/:id

Updating the Card PIN

Set or change a card's PIN by sending "pin" (a numeric string, 4 to 6 digits) on update.

The PIN is write-only and is never returned — inform "expand=isPinDefined" when fetching the card to check whether a PIN is set.

ENDPOINT

PATCH /v2/issuing-card/:id

Canceling a card

Permanently cancel a card by its id. The card's status becomes "canceled". This action is irreversible.

ENDPOINT

DELETE /v2/issuing-card/:id

Getting a Card's Logs

Audit a card's history by querying its logs with the "cardIds" filter. Each status change creates a Log — a card that was created, activated, blocked and then canceled returns one log per step. The "card" field in each log is a full representation of the Issuing Card as it was at that point in its history (shown abbreviated with "...").

You can also filter by "types" (created, unblocked, blocked, expired, canceled, updated) and "after" / "before", or fetch a single log with GET /v2/issuing-card/log/:id.

ENDPOINT

GET /v2/issuing-card/log

Issuing Holder Overview

An Issuing Holder is the person or business that owns the cards you issue. Each Issuing Card is attached to a holder, and one holder can own many cards.

Individual vs. business. A holder's type is derived from its taxId: a CPF (11 digits) makes it an individual, a CNPJ (14 digits) a business. This must match the holderType of the card's Issuing Product — issuing a business-product card to a CPF holder (or vice-versa) is rejected.

externalId. Each holder carries an externalId — your own reference for it, unique among your active and blocked holders. It is what lets you create cards by holderExternalId without first looking up the holder's Stark id, and it stops you from accidentally creating the same holder twice.

Spending controls. A holder can carry its own "rules" list, applied on top of each card's rules — handy to cap total spend across every card a holder owns. Pass a "rules" list on create or update. The "rules" field is always returned on the holder; pass "expand=rules" to also get each rule's live spending counter (counterAmount). See the Issuing Rule section for the full rule object and how to set it.

Holder Statuses

Each Issuing Holder has a status that reflects where it is in its life cycle:

Issuing Holder life cycle

Status	Description
active	The holder is active and its cards can be used. New holders are created in this status.
blocked	The holder is temporarily blocked. You can unblock it by setting its status back to "active".
canceled	The holder was permanently canceled, together with all of its cards. This is irreversible.

Holder Logs

Every time you or Stark Infra change an Issuing Holder, we create a Log entry. Logs let you audit a holder's full history — each status change and rule update.

Query the holder logs with GET /v2/issuing-holder/log (filter by holderIds, types, after / before), or fetch a single one with GET /v2/issuing-holder/log/:id. The log types are: created, unblocked, blocked, updated, canceled.

Creating a Holder

Create one or more holders by sending a "holders" list (up to 100 at a time). Each holder needs a name, a taxId and an externalId. New holders start with status "active".

The externalId must be unique among your active and blocked holders: reusing the externalId of an existing one is rejected.

You can attach a "rules" list at creation to set holder-level spending limits. The created rules are returned either way; pass "expand=rules" in the query string to also get each rule's counterAmount.

ENDPOINT

POST /v2/issuing-holder

Blocking a Holder

Temporarily block a holder by setting its status to "blocked". While blocked, the holder's cards decline purchases until you unblock it.

ENDPOINT

PATCH /v2/issuing-holder/:id

Unblocking a Holder

Reactivate a blocked holder by setting its status back to "active". Only "active" and "blocked" are accepted on update — to permanently retire a holder use the cancel route below.

ENDPOINT

PATCH /v2/issuing-holder/:id

Updating a Holder's Rules

Send a "rules" list on update to replace the holder's spending rules — the new list overwrites the old one. You can also update "name" and "tags" in the same call.

Rules are echoed back abbreviated unless you pass "expand=rules". See the Issuing Rule section for the full rule object.

ENDPOINT

PATCH /v2/issuing-holder/:id

Canceling a Holder

Permanently cancel a holder by its id. The holder's status becomes "canceled" and all of its cards are canceled along with it. This action is irreversible.

ENDPOINT

DELETE /v2/issuing-holder/:id

Getting a Holder's Logs

Audit a holder's history by querying its logs with the "holderIds" filter. Each change creates a Log — a holder that was created, blocked and then unblocked returns one log per step. The "holder" field in each log is a representation of the Issuing Holder as it was at that point in its history.

You can also filter by "types" (created, unblocked, blocked, updated, canceled) and "after" / "before", or fetch a single log with GET /v2/issuing-holder/log/:id.

ENDPOINT

GET /v2/issuing-holder/log

Issuing Rule Overview

The Issuing Rule object represents the spending controls you attach to an Issuing Holder or Issuing Card.

A rule caps how much can be spent within a time interval and optionally restricts spending to specific merchant categories, countries or card methods.

Rules are nested objects — you never create them on their own. You set them when creating or updating a holder or card.

The spending counter. Each rule keeps a "counterAmount": how much has already been spent against it in the current interval. We update it after every purchase that moves the limit — it goes up when a purchase is approved, and back down when a purchase is reversed or confirmed for a smaller amount than was authorized. It resets to 0 when the rule's interval rolls over.

Reading the remaining balance. The amount still available on a rule is simply "amount" − "counterAmount". For example, a R$ 1.500,00 rule (amount = 150000) that already has counterAmount = 40000 still has R$ 1.100,00 left to spend in the current interval.

The rule object is always returned on its holder or card — you do not need any expand to read a rule's name, interval, amount and restrictions. Passing "expand=rules" simply enriches each returned rule with its live "counterAmount" (plus the currency name/symbol and the fully-resolved category, country and method objects).

The Issuing Rule object

Attributes

name STRING

Rule name, used to identify it. Example: "Travel".

interval STRING

Interval after which the rule counter resets. Options: "instant", "day", "week", "month", "year", "lifetime".

NOTE: "lifetime" never resets on its own — a rule with this interval keeps accumulating its counterAmount indefinitely. The only way to clear it is to replace the rule yourself: update the holder or card with that rule's id omitted, which starts a fresh rule (and a fresh counter) in its place.

amount INTEGER

Maximum amount that can be spent within the interval, in cents. Example: 150000 (R$ 1.500,00).

currencyCode STRING

Currency the rule's amount is measured in (e.g. "BRL", "USD"). The rule does not limit spending to this currency — purchases in other currencies are converted and counted against the limit. Example: a R$ 100,00 limit covers a R$ 100,00 purchase, or a US$ 20,00 purchase when 1 USD = 5 BRL.

schedule STRING

Optional schedule dictating when the rule can be used. Some examples:

"everyday from 09:00 to 18:00 in America/Sao_Paulo" — every day, 09:00–18:00 São Paulo time;
"every monday, wednesday, friday from 08:00 to 12:00 in America/Sao_Paulo" — only those weekdays, mornings;
"every saturday, sunday" — weekends, all day, in UTC;

purposes LIST OF STRINGS

Optional list of transaction purposes the rule applies to. Options: "purchase", "withdrawal", "verification". The rule then limits only purchases of those purposes; omit it to allow any purposes. Example: ["purchase", "verification"] if you want us to automatically deny withdrawal.

categories LIST OF OBJECTS

Optional list of MerchantCategory objects the rule applies to. Restricts spending to the given merchant categories.

countries LIST OF OBJECTS

Optional list of MerchantCountry objects the rule applies to. Restricts spending to the given countries.

methods LIST OF OBJECTS

Optional list of CardMethod objects the rule applies to. Restricts spending to the given payment methods.

id STRING

Unique id of the rule. Inform it when updating to preserve the rule's counters; omit it to create a fresh rule in its place.

counterAmount INTEGER

Amount already spent against this rule in the current interval, in cents. It increases when a purchase is approved and decreases when one is reversed or confirmed for a smaller amount, resetting to 0 when the interval rolls over. The rule's remaining balance is amount − counterAmount. Only present when you query the holder or card with "expand=rules".

currencyName STRING

Currency full name. Returned only. Example: "Brazilian Real".

currencySymbol STRING

Currency symbol. Returned only. Example: "R$".

Creating with Spending Controls

Set the initial rules when you create a holder (or card) by passing a "rules" list of IssuingRule objects.

Omit each rule's id on creation — Stark Infra assigns one, which you later reuse to preserve the rule's counters when updating.

ENDPOINT

POST /v2/issuing-holder

Updating Spending Controls

You may need to add or change the rules on your holders and cards.

NOTE: When you update the rules list, inform each existing rule with its id to preserve its counters. To reset a rule, omit the id and a new rule is created in place of the old one.

Send the full list you want the resource to end with — any rule absent from the list is removed. The same pattern applies to Issuing Card updates.

ENDPOINT

PATCH /v2/issuing-holder/:id

Issuing Purchase Overview

An Issuing Purchase is a transaction made with an Issuing Card. You never create purchases yourself — they appear in real time, when a cardholder pays at a merchant and the authorization is approved.

How purchases reach you. When a card is used, the network sends us an authorization request. We fire an issuing-purchase Webhook event so you can approve or deny it on the spot; the approved (or denied) purchase is then persisted and can be queried here. See the Handling Purchase Events section to learn how to answer authorizations and react to status changes.

Merchant vs. issuer amount. When a purchase is made in a currency other than your own, the same money is recorded twice: merchantAmount (in merchantCurrencyCode, what the merchant charged) and issuerAmount (in issuerCurrencyCode, what is debited from your Issuing Balance after FX conversion). All amounts are integers in cents.

Installments. installmentCount is how many installments the purchase was split into (1 for a single, upfront charge). Each installment settles separately, so a single purchase can produce more than one confirmation over time.

endToEndId. Every purchase carries an endToEndId, the unique transaction identifier shared across the network. Use it to reconcile a purchase with the acquirer or to filter the listing (endToEndIds).

Ledger link. Once a purchase affects your balance, issuingTransactionIds lists the Issuing Transaction entries it generated — that's the bridge between a purchase and your ledger.

metadata. When a purchase came from an authorization you answered, metadata carries its authorizationId; otherwise it's an empty object.

Purchase Statuses

Each Issuing Purchase has a status that reflects where it is in its life cycle. Status changes are driven by the network and the sub-issuer — not by you:

Issuing Purchase life cycle

Status	Description
approved	The authorization request was approved by the sub-issuer or by the network/issuer default protocol. The amount is reserved for future settlement.
confirmed	The purchase was settled by the network. At this point the money is transferred through the network.
voided	The purchase was fully reversed and is no longer in effect.
canceled	An approved purchase was canceled by the acquirer. The reserved amount goes back to your Issuing Balance.
denied	The authorization request was denied by the sub-issuer or by the network/issuer default protocol.

Purchase Logs

Every change to an Issuing Purchase creates a Log entry. Logs are how you follow a purchase through its life cycle: each authorization, settlement, reversal and edit becomes one log. Whenever a new Log is created, we fire a Webhook to your registered URL (see Handling Purchase Events).

A log's type is one of: approved, denied, confirmed, reversed (some amount was reversed, partially or fully), voided (the purchase was fully reversed), canceled and updated (you set a description or tags). Note that reversed is a log type but not a purchase status — a partial reversal logs reversed while the purchase stays confirmed.

Each log carries the purchase as it was at that point (shown abbreviated with "..."), plus installment (which installment the log refers to) and issuingTransactionId (the ledger entry tied to this step). Query logs with GET /v2/issuing-purchase/log or fetch one with GET /v2/issuing-purchase/log/:id.

Corner Cases

A few unusual authorization scenarios are worth knowing about:

Corner case 1. The network does not send us the authorization request and instead only notifies us that it approved or denied a purchase, without our (or your) permission — for example, in the unlikely event of a communication failure between us and the network.

Issuing Purchase corner case 1

Corner case 2. Common at gas stations in the USA: the cardholder sends the authorization request before filling the tank just to check the card data. Once the fuel is in the car and can no longer be retrieved, we are only notified of the final value charged, since it can no longer be denied.

Issuing Purchase corner case 2

Corner case 3. The merchant sends cash to the holder, producing an Issuing Purchase with a negative amount (e.g. a bonus or benefit to a recurring customer). In this case the interchange is retained by the acquirer and does not reach us (or you).

Issuing Purchase corner case 3

Corner case 4. New authorization requests can reference the same purchase, incrementing the original amount. These incremental authorizations share the same endToEndId as the previous ones — for example, when a ride-hailing app extends a previous authorization after a route change or delay.

Issuing Purchase corner case 4

Default Authorization Cases

These cases happen when your sub-issuer fails to respond to the authorization request in time and our default authorization protocol is triggered (governed by the defaultAuthorizationMaxAmount and defaultAuthorizationMinScore you set during setup).

Case 1. The authorization request reaches your endpoint, but the default authorization protocol denies an authorization your system had approved, or vice-versa:

Default authorization case 1

Case 2. When the default authorization protocol is triggered, the request may be approved with a different amount than expected. For example, when the merchant allows a partial amount and the holder doesn't have the full amount, your system could approve a smaller amount — but if the default protocol is triggered, the purchase may be fully approved instead.

Default authorization case 2

NOTE: prepare for concurrency — we may have already detected a timeout on your endpoint and sent you the corresponding approved/denied event while your system is still processing the authorization. If left unchecked, you could register two purchases with the same endToEndId.

Parsing an authorization request

When a holder uses our card, Stark Infra receives an authorization message from the card network, and POSTs a synchronous authorization request to the authorizationUrl you registered during Setup — see the Authorization flow for the full contract.

Verify the request really came from us before trusting it: pass the raw body and the Digital-Signature header to the SDK's parse method, which checks the signature against Stark Infra's public key and returns the Issuing Purchase to analyze. Then answer with {"authorization": {"status": "approved"}} (optionally overriding amount or attaching tags) or {"authorization": {"status": "denied", "reason": "..."}} with one of the accepted denial reasons.

Listing purchases

List purchases in pages of up to 100. Filter by "status" (one of the purchase statuses), "cardIds", "holderIds", "endToEndIds", "ids", "tags" and the "after" / "before" date range.

The "issuerAmount" / "merchantAmount" split and the populated "metadata.authorizationId" are visible here — use them to reconcile each purchase against the merchant charge and the authorization you answered.

ENDPOINT

GET /v2/issuing-purchase

Getting a purchase

Fetch a single purchase by its id. The "issuingTransactionIds" field links it to the ledger Issuing Transaction entries it generated.

ENDPOINT

GET /v2/issuing-purchase/:id

Updating a purchase

A purchase is settled by the network, so its financial fields are read-only. The only things you can change are its "description" (free text, up to 140 characters) and its "tags" — useful for reconciliation and bookkeeping. Each update creates an "updated" Log.

ENDPOINT

PATCH /v2/issuing-purchase/:id

Getting purchase Logs

Audit a purchase's history by querying its logs with the "purchaseIds" filter. A purchase that was approved, then confirmed, then edited returns one log per step. You can also filter by "types" (approved, denied, confirmed, reversed, voided, canceled, updated) and "after" / "before", or fetch a single log with GET /v2/issuing-purchase/log/:id.

ENDPOINT

GET /v2/issuing-purchase/log

Issuing Preview Installment Overview

An Issuing Preview Installment is a single upcoming installment of a card purchase that has not been billed yet. It exists only in the credit (postpaid) flow, where installment purchases are charged across several future Issuing Billing Invoices instead of being settled immediately.

Use it to preview, ahead of time, the amounts that will compose your future billing invoices — for example to forecast next month's charges or to reconcile what each purchase will add to each invoice.

Read-only. This resource is query-only: there is a single GET list endpoint. You cannot create, update or cancel a preview installment — Stark Infra derives them automatically from your installment purchases, and each one disappears from the list once its installment is actually billed.

amount vs. totalAmount. All money is in cents. amount is the value of this single installment; totalAmount is the full value of the source purchase. So a R$ 900.00 purchase split in 3 returns three preview installments of amount 30000 each, all sharing totalAmount 90000.

number and count. number is the position of this installment (1-based) and count is how many installments the source purchase was split into — e.g. number 2 of count 3.

source. Points back to the entity that originated the installment, formatted as "<resource>/<id>" — typically an Issuing Purchase, e.g. "issuing-purchase/5155165527080960".

due. The datetime when this installment is scheduled to be billed — i.e. the invoice it will land on.

Querying Preview Installments

List the upcoming installments that have not been billed yet, in chunks of at most 100. Page through the results with the "cursor" returned in each response.

Sorting. Pass "sort" to order the results: "created" / "-created" by creation datetime, or "due" / "-due" by billing datetime. A leading "-" means descending. The default is "-created". Use "due" to walk the installments in the order they will be charged.

Filtering. Narrow the list with "after" / "before" (on the creation date), "ids" (fetch specific installments) and "tags". Use "limit" to cap the page size (max 100).

ENDPOINT

GET /v2/issuing-preview-installment

Issuing Balance Overview

The Issuing Balance is the spendable wallet that backs every card you issue. Your cards draw on this single pool of funds — there is one Issuing Balance per workspace, not one per card or per holder.

Funding and draining. You top up the balance with an Issuing Invoice (pay its BR Code or transfer to its account) and pull money back out with an Issuing Withdrawal. Card purchases settle against the balance and lower it. Every one of these movements is recorded as an Issuing Transaction in the ledger — query those to see exactly how the balance reached its current amount.

amount is in cents. Like every monetary value in the API, amount is an integer in cents: 5000000 means R$50,000.00. It is the balance left after the latest transaction.

limit and maxLimit. Both report the ceiling your issuing wallet is allowed to reach. They are always equal (100000000, i.e. R$1,000,000.00, in the example below) and are not configurable through the API — treat them as read-only information, not a setting you can change.

Getting your Balance

Fetch your current Issuing Balance. There is a single balance per workspace, so this endpoint takes no id and returns just one entry — the wallet that all your cards spend from.

The updated field is the timestamp of the latest Issuing Transaction that moved the balance; if nothing has moved yet it reflects the current moment.

ENDPOINT

GET /v2/issuing-balance

Issuing Invoice Overview

An Issuing Invoice is a Pix invoice you create to fund your issuing balance — the wallet your cards spend from. You must top this balance up before you can issue and spend on cards, so creating an invoice is usually the first call you make.

Creating an invoice returns a payable Pix: a "brcode" (the Pix copy-and-paste / QR string), a "link" to a hosted payment page and a "due" datetime (7 days ahead by default). Pay it from any account, and once Stark Infra confirms the payment the invoice moves to "paid" and the amount lands in your Issuing Balance, ready to spend on Issuing Cards.

amount is always in cents — 10000 means R$100.00. It must be a positive integer.

The returned taxId is the issuer's, not the payer's. You may pass a payer "name" and "taxId" when creating the invoice (they default to your workspace owner's if omitted), but the "taxId" returned on the invoice is always the tax id of your card-issuer entity — the party receiving the funds.

Watch for the "paid" status. The deposit is asynchronous: the invoice is born "created" and only becomes "paid" once the Pix settles. Track that transition through the invoice Logs or a webhook subscribed to issuing-invoice events — that is your signal that the balance was funded.

Invoice Statuses

Each Issuing Invoice has a status that reflects where it is in its life cycle:

Issuing Invoice life cycle

Status	Description
created	The invoice was created and is waiting for payment. Its brcode and link are payable.
paid	The Pix was paid and the amount was credited to your issuing balance. This is the status you watch for.
overdue	The due datetime passed and the invoice was not paid yet. It can still be paid for a short grace period.
expired	The invoice expired and can no longer be paid. Create a new one to fund the balance.
canceled	The invoice was canceled and can no longer be paid.

Invoice Logs

Every time an Issuing Invoice changes, we create a Log entry. Logs are how you follow an invoice from creation to payment without polling — query them, or subscribe a webhook to issuing-invoice events, and react to the "paid" log to know the funds landed in your balance.

Query the invoice logs with GET /v2/issuing-invoice/log (filter by ids, types, after / before), or fetch a single one with GET /v2/issuing-invoice/log/:id. Log types are: created, paid, overdue, expired, credited and canceled. The "invoice" field in each log is an abbreviated representation of the Issuing Invoice as it was at that point (shown abbreviated with "...").

Creating an Invoice

Create an invoice to fund your issuing balance by sending an "amount" in cents. "name", "taxId", "tags" and "metadata" are optional — if you omit "name" / "taxId" they default to your workspace owner's.

The response carries the payable Pix: "brcode", "link" and "due". The invoice starts as "created"; "issuingTransactionId" stays null until the Pix is paid.

NOTE: You cannot create a funding invoice while you have an unpaid Issuing Billing Invoice — if a billing invoice is pending or overdue, settle it first.

NOTE: In Sandbox, an invoice has about a 90% chance of being paid automatically by our simulation system within 10 minutes — handy for testing the funding flow end to end.

ENDPOINT

POST /v2/issuing-invoice

Listing Invoices

List your invoices in pages of at most 100. Filter by "status" (created, paid, overdue, expired, canceled), "tags" and "after" / "before". Use the returned "cursor" to page through results.

ENDPOINT

GET /v2/issuing-invoice

Getting an Invoice

Fetch a single invoice by its id — for example to re-read its current "status" or recover its "brcode" and "link" to present the Pix again.

ENDPOINT

GET /v2/issuing-invoice/:id

Getting an Invoice's Logs

Follow an invoice's life cycle by querying its logs. Filter by "types" (e.g. "paid") to react only to the transitions you care about, or by "ids" to scope to specific invoices, plus "after" / "before". Fetch a single log with GET /v2/issuing-invoice/log/:id.

ENDPOINT

GET /v2/issuing-invoice/log

Issuing Billing Invoice Overview

An Issuing Billing Invoice is the postpaid settlement document of a credit issuing operation. At the close of each billing period Stark Infra consolidates everything your cards spent and bills it back to you as a single Pix invoice that you pay.

It is composed of Issuing Billing Transaction entries. Each purchase, withdrawal, refund and reversal settled in the period becomes a billing transaction; the invoice's nominalAmount is the sum of those entries. Query the Issuing Billing Transaction section to see the line items behind an invoice.

Read-only. You do not create or update billing invoices — Stark Infra generates and closes them on the billing cycle. The only operations available here are listing them and fetching one by id.

Pay it before funding. While an invoice is "pending" or "overdue" you cannot create a funding Issuing Invoice — settle the outstanding billing invoice first. Pay it with its brcode (a Pix BR Code) or by opening its link.

Money direction & amounts. nominalAmount is the original amount owed for the period; amount is what you owe right now — equal to nominalAmount until the due date, then growing by fine and interest once the invoice is overdue. Both are integers in cents (e.g. 100000 = R$ 1,000.00). fine is a one-off percentage and interest a monthly percentage, applied only when you pay after the due date.

Billing Invoice Statuses

Each Issuing Billing Invoice has a status that reflects where it is in the billing cycle:

Status	Description
created	The invoice was generated for the billing period but is not yet open for payment.
pending	The invoice is open and awaiting payment. Pay it with its brcode or link before the due date to avoid fine and interest.
overdue	The due date passed without payment. The amount now grows by fine and interest until it is paid.
paid	The invoice was settled. No further amount is owed for the period.
expired	The invoice was not paid and is no longer payable through this document. The outstanding balance is handled outside this flow.

Listing Billing Invoices

List your billing invoices in chunks of at most 100. Filter by "status" (created, pending, overdue, expired, paid), by "after" / "before" on the creation date, by "ids" or by "tags".

Use "status=pending" to find what you currently owe — these are the invoices that must be paid before you can fund your operation with a new Issuing Invoice.

ENDPOINT

GET /v2/issuing-billing-invoice

Getting a Billing Invoice

Fetch a single billing invoice by its id to read its current amount, status, due date and the brcode / link you use to pay it.

The billing period the invoice covers is given by "start" and "end"; "due" is when payment is expected. Once overdue, "amount" reflects the original "nominalAmount" plus the accrued fine and interest.

ENDPOINT

GET /v2/issuing-billing-invoice/:id

Issuing Billing Transaction Overview

An Issuing Billing Transaction is a single line entry that composes an Issuing Billing Invoice. Each purchase, withdrawal or fee that was billed in a period produces one transaction — and an installment purchase produces one transaction per installment that falls in that period.

This is a read-only, query-only resource: there is one endpoint and it lists transactions. You never create, update or cancel a transaction directly — they are generated by Stark Infra as purchases settle into invoices.

Reconciling an invoice. Pass "invoiceId" to list every transaction that makes up a given Issuing Billing Invoice. The transactions are ordered as they were applied, and each one carries the running "balance" — the invoice balance in cents after that transaction — so the last transaction's balance equals the invoice total.

Tracing back to the purchase. The "source" field points to the entity that originated the transaction, formatted as "/" (e.g. "issuing-purchase/5155165527080960"). Use it to walk from a billed line back to the originating Issuing Purchase. The "externalId" is the unique external identifier of the transaction (for an installment it is suffixed with the installment number, e.g. "5155165527080960-1").

Installments

When a purchase is split into installments, each installment is billed as its own transaction. "installmentCount" is the total number of installments of the source purchase and "installment" is the number of this one (1-based). A single-payment purchase has "installment": 1 and "installmentCount": 1.

The transactions for the different installments of the same purchase share the same originating "source", but each lands in the invoice of its own billing period — so to see them all you query across invoices, not within a single one.

Amounts and currency

All amounts are integers in cents. "amount" is what was billed in BRL (e.g. 30000 = R$ 300.00) and "tax" is the IOF in cents applied to the transaction. For international transactions, "merchantAmount" and "merchantCurrencyCode" hold the amount in the merchant's currency and "rate" is the conversion rate that was applied; for domestic transactions the merchant amount equals the amount, the code is "BRL" and the rate is 1.0.

Listing Billing Transactions

List billing transactions in pages of up to 100 ("limit"). The response wraps the results in a "transactions" list plus a "cursor" — pass the cursor back to fetch the next page; a null cursor means there are no more results.

Pass "invoiceId" to scope the list to a single Issuing Billing Invoice and reconcile it to its line entries. You can also filter by "ids" (a comma-separated list of specific transaction ids), by "tags", and by "after" / "before" to bound the creation date.

ENDPOINT

GET /v2/issuing-billing-transaction

Issuing Withdrawal Overview

An Issuing Withdrawal moves funds out of your Issuing Balance and back into your Stark Infra workspace. It is the inverse of a funding Issuing Invoice: where an invoice tops your issuing balance up, a withdrawal drains the excess back to your main account.

Use a withdrawal whenever your issuing balance holds more than you need to back your cards — the money returns to your regular Stark Infra balance, where it can be transferred out or reused.

Two transaction ids. A successful withdrawal records both legs of the move: issuingTransactionId is the debit on your issuing balance, and transactionId is the matching credit on your Stark Infra workspace balance. Both are returned only after the withdrawal settles.

externalId (idempotency). You assign your own externalId to each withdrawal. It must be unique per workspace — sending a withdrawal whose externalId was already used is rejected, so a retried request never withdraws twice. Use it later to look a withdrawal back up with the externalIds filter.

amount is an integer in cents (e.g. 10000 means R$100.00) and must be positive. description is mandatory and must be 10 to 200 characters long.

Creating a Withdrawal

Create a withdrawal by sending amount, externalId and description. The amount is debited from your issuing balance and credited back to your Stark Infra workspace balance.

The externalId must be unique per workspace — a repeated externalId is rejected, which makes a retried request safe. The description is mandatory and must be 10 to 200 characters.

The response echoes the withdrawal together with the transactionId (workspace credit) and issuingTransactionId (issuing-balance debit) recorded for the move.

ENDPOINT

POST /v2/issuing-withdrawal

Listing Withdrawals

List your withdrawals in pages of up to 100. Filter by "after" / "before" (creation date), "tags", or "externalIds" to find the ones you assigned.

The response is paginated: follow the "cursor" to fetch the next page (null means the last page).

ENDPOINT

GET /v2/issuing-withdrawal

Getting a Withdrawal

Fetch a single withdrawal by its id.

ENDPOINT

GET /v2/issuing-withdrawal/:id

Issuing Transaction Overview

An Issuing Transaction is a single entry in the ledger of your Issuing Balance. Every event that moves money in your issuing account — a card purchase, an Issuing Invoice that funds it, an Issuing Withdrawal that takes money out, or a fee — produces exactly one transaction.

Read-only. You never create, update or delete transactions: Stark Infra writes them automatically as funds move. You can only list them and fetch them by id.

Amount sign. The amount is in cents and its sign tells you the direction of the money: a positive amount is a credit (money in — e.g. an invoice that tops up your balance), a negative amount is a debit (money out — e.g. a purchase or a withdrawal).

Running balance. The balance field is your full issuing balance, in cents, right after this transaction was applied. Walking the transactions in order lets you reconcile every cent of your Issuing Balance without recomputing it yourself.

Source. The source links a transaction back to the entity that generated it, in the form resource/id — for example issuingPurchase/6724771005489152. Use it to trace a balance change back to the Issuing Purchase, Issuing Invoice or Issuing Withdrawal that caused it, and as a query filter to pull every transaction tied to one source.

Listing Transactions

List your issuing transactions, most recent first, in pages of at most 100. Narrow the result with "after" / "before" (by creation date), "tags", "ids" or "externalIds".

Filter by "source" to pull every transaction generated by one entity — pass the full resource/id value (e.g. "issuingPurchase/6724771005489152") to follow a single purchase, invoice or withdrawal through the ledger.

ENDPOINT

GET /v2/issuing-transaction

Getting a Transaction

Fetch a single transaction by its id to inspect one ledger entry — its amount, the resulting balance and the source that generated it.

ENDPOINT

GET /v2/issuing-transaction/:id

Issuing Product Overview

An Issuing Product is the card product — the BIN range — that every Issuing Card references through its productId. It defines the network, funding type, holder type and code shared by every card created under it.

Read-only. Products are not created through the API: they are defined together with your account manager when you set up card issuing. The API exposes a single endpoint to list the products available to your workspace so you can pick a productId to issue cards with.

Getting a productId. List your products with the endpoint below and copy the id of the one you want. If you don't have any product yet, request one at help@starkinfra.com.

Field meanings. network is the card network ("Visa" or "Mastercard"). fundingType is how the card settles — "prepaid" (balance is debited from your Issuing Balance up front) or "credit". holderType tells whether the product issues cards to a "business" or to an "individual". code is the product code that identifies the specific card product.

NOTE: settlement, client and customerType are legacy aliases kept for backward compatibility — settlement mirrors fundingType, while client and customerType both mirror holderType. Prefer the canonical fields in new integrations.

Listing your Products

List the card products available to your workspace and copy the id of the one you want to issue cards with. Each entry exposes the product's network, fundingType, holderType and code.

This is the only Issuing Product endpoint — products are read-only and cannot be created, updated or deleted through the API.

ENDPOINT

GET /v2/issuing-product

Issuing Design Overview

An Issuing Design is the artwork template applied when a physical card is embossed and printed. It defines the visual layout — the artwork, fonts and positioning — that the embosser prints onto the card.

Designs are read-only: you don't create them through the API. They are registered for your sub-issuer ahead of time (together with the embossers that can print them), and you reference one by its id when you order a physical card through an Issuing Embossing Kit.

Registering a design requires network approval. A design is not something you configure on your own: each one must be approved by the card network (Visa/Mastercard) through the embosser that will print it before it can be registered for your sub-issuer. To set up a new design or change an existing one, contact help@starkinfra.com and our team will walk you through the network approval and embosser configuration.

Picking a design for a kit. Each design lists the embosserIds that are able to print it. When you assemble an Issuing Embossing Kit, the card design and the envelope design you choose must both be printable by the same embosser — so check the embosserIds overlap before referencing them.

Previewing the artwork. Beyond the design metadata, you can download a PDF proof of the layout to preview exactly how a card or envelope will look once printed. See Getting a Design's PDF below.

Design Types

A design's "type" is one of exactly two values, telling you which part of the physical mailing it applies to:

Type	Description
card	Artwork printed on the plastic card itself.
envelope	Artwork for any printed material that is not the plastic card — the mailing envelope, a flyer, a leaflet or any other paper that ships alongside the card. Anything other than the card is typed as "envelope".

Listing Designs

List the designs available to your sub-issuer. Use this to discover which design ids you can reference when ordering physical cards, and to read each design's type and the embosserIds that can print it.

Filter by "ids" to fetch specific designs, and page through results with "limit" (max 100) and "cursor" — our SDKs handle the cursor for you.

ENDPOINT

GET /v2/issuing-design

Getting a Design

Fetch a single design by its id to read its name, type and the embosserIds that support it.

ENDPOINT

GET /v2/issuing-design/:id

Getting a Design's PDF

Download a PDF proof of the design's artwork to preview how the card or envelope will look once printed.

Unlike the other endpoints, this one returns the raw PDF bytes — there is no JSON body. With curl, write the response straight to a file with --output design.pdf; our SDKs return the binary content for you to save.

ENDPOINT

GET /v2/issuing-design/:id/pdf

Issuing Embossing Kit Overview

An Issuing Embossing Kit bundles the physical materials used to personalize a card — the plastic and packaging — together with the Issuing Designs available for embossing.

Where it fits. When you order an Issuing Embossing Request for a physical card, you reference a kitId. The kit determines which designs you can pick and how the card is physically produced and shipped, so you list the available kits first and reuse their ids in your embossing requests.

Read-only. Kits are provisioned for your sub-issuer by Stark Infra — you cannot create, change or delete them. The only operations are listing the kits available to you and fetching one by its id.

The designs field. Each kit returns a "designs" list referencing the Issuing Designs it supports. These come back as id-only objects (e.g. {"id": "6284441486065664"}) — resolve a design's full details through the Issuing Design section using that id.

Listing your Embossing Kits

List the embossing kits available to your sub-issuer. Use the returned ids when ordering an Issuing Embossing Request.

Filter by "designIds" to keep only the kits that support a given Issuing Design (up to 30 ids), by "ids" to fetch specific kits, or by "after" / "before" to bound the results by creation date.

ENDPOINT

GET /v2/issuing-embossing-kit

Getting an Embossing Kit

Fetch a single embossing kit by its id to inspect its name and the Issuing Designs it supports.

ENDPOINT

GET /v2/issuing-embossing-kit/:id

Issuing Stock Overview

An Issuing Stock tracks the raw blank cards available for embossing. Each stock entry pairs one card design (Issuing Design) with the embosser that physically holds those blanks, and its balance tells you how many blanks are still available to be embossed.

Read-only. You never create or edit a stock directly — Stark Infra opens one for each design/embosser pair you have. You can only Query it, Get it by id, and read its Logs.

Raising the balance. To add more blanks, register an Issuing Restock: each restock increases the matching stock's balance by the ordered amount once the blanks arrive at the embosser.

Low-balance alerts. Embossing a Issuing Embossing Request consumes blanks and lowers the balance. Set an Issuing Stock Rule to be warned (via webhook) before a stock runs out, so you can restock in time.

Stock Balance

The balance is the count of card blanks currently available for embossing. It is computed on demand, so it is not returned by default — inform expand=balance on Query or Get to include it.

Without expand=balance a stock returns only its identifiers (id, designId, embosserId, embosserName) and timestamps.

Stock Logs

Every time a stock's balance shifts, Stark Infra creates a Log entry. Logs let you audit how a stock reached its current balance — each restock that came in and each batch of blanks that was embossed or written off.

Each log carries a top-level count (the signed shift in balance for that event) and a nested stock object (a representation of the stock the log refers to). The log type is one of:

Type	Description
created	The stock was opened for a design/embosser pair, seeding its initial balance.
restocked	An Issuing Restock arrived at the embosser and raised the balance.
spent	Blanks were consumed to emboss cards, lowering the balance.
lost	Blanks were written off (damaged or otherwise unusable), lowering the balance.

Query the stock logs with GET /v2/issuing-stock/log (filter by stockIds, types, after / before), or fetch a single one with GET /v2/issuing-stock/log/:id.

Querying Stocks

List your stocks, newest first, in pages of up to 100. Filter by "designIds", "embosserIds", "ids" or by creation date with "after" / "before".

Inform "expand=balance" to include each stock's current blank count — it is omitted otherwise (see the Stock Balance note above).

ENDPOINT

GET /v2/issuing-stock

Getting a Stock

Fetch a single stock by its id. As with Query, inform "expand=balance" to include its current blank count.

ENDPOINT

GET /v2/issuing-stock/:id

Getting a Stock's Logs

Audit a stock's balance history by querying its logs with the "stockIds" filter. Each balance shift creates a Log — a stock that was created, restocked and then partly embossed returns one log per event. The "stock" field in each log is a representation of the Issuing Stock the log refers to.

You can also filter by "types" (created, restocked, spent, lost) and "after" / "before", or fetch a single log with GET /v2/issuing-stock/log/:id.

ENDPOINT

GET /v2/issuing-stock/log

Issuing Stock Rule Overview

An Issuing Stock Rule sets a low-balance alert on one of your Issuing Stock entries. When that stock's available count drops below the rule's minimumBalance, we notify the contacts you registered so you can reorder cards before you run out.

One rule per stock. Each stock can have a single active rule at a time. The rule is tied to a stockId at creation, and that link cannot be changed afterwards — to point the alert at a different stock, cancel this rule and create a new one.

Who gets notified. A rule notifies the addresses in its "emails" list and the numbers in its "phones" list (each capped at 10). At least one email or phone must be present — a rule with no contacts is rejected.

What triggers it. minimumBalance is a stock count, not money: it is the number of remaining cards below which the alert fires. It must be a positive integer.

Stock Rule Statuses

Each Issuing Stock Rule has a status that reflects where it is in its life cycle:

Status	Description
active	The rule is active and monitoring its stock. New rules are created in this status. Only one active rule is allowed per stock.
canceled	The rule was permanently canceled and no longer fires alerts. This is irreversible.

Creating a Stock Rule

Create one or more stock rules by sending a "rules" list. Each rule needs a minimumBalance and the stockId of the Issuing Stock it watches, plus at least one contact across "emails" and "phones".

Creating a second rule for a stock that already has an active rule is rejected — cancel the existing one first.

ENDPOINT

POST /v2/issuing-stock-rule

Querying Stock Rules

List your stock rules in chunks of at most 100. Filter by "status", "stockIds" (to find the rule watching a given stock), "ids", "tags" and "after" / "before".

ENDPOINT

GET /v2/issuing-stock-rule

Updating a Stock Rule

Change a rule's minimumBalance, emails, phones or tags. The stockId is fixed at creation and cannot be updated.

Each list you send replaces the old one wholesale, and the combined emails + phones must still hold at least one contact. A canceled rule cannot be updated.

ENDPOINT

PATCH /v2/issuing-stock-rule/:id

Canceling a Stock Rule

Permanently cancel a rule by its id. Its status becomes "canceled" and it stops firing alerts. This action is irreversible, and once canceled the stock is free to receive a new active rule.

ENDPOINT

DELETE /v2/issuing-stock-rule/:id

Issuing Restock Overview

An Issuing Restock is an order you place to replenish your Issuing Stock of blank cards. Each physical card you emboss consumes one blank from that stock — when it runs low, create a Restock to request more.

What you send. A restock needs only a count (how many blanks to order) and the stockId of the Issuing Stock to top up. You can create up to 100 restocks in a single request by sending more entries in the "restocks" list.

Fulfillment is asynchronous. Creating a restock does not add blanks to your stock immediately. The order starts as "created", moves to "processing" while it is being fulfilled, and reaches "confirmed" once the blanks have been added to your stock. You don't change a restock's status yourself — it advances on its own and is reflected back to you through its status and its Logs.

Read-only after creation. A restock has no update or cancel endpoint. Once placed, you can only query it, fetch it by id, or follow its Logs to track fulfillment.

Restock Statuses

Each Issuing Restock has a status that reflects where its order is in the fulfillment flow:

Status	Description
created	The restock order was registered and is waiting to be fulfilled.
processing	The order is being fulfilled — the requested blanks are being added to your stock.
confirmed	The order was fulfilled: the blanks are now part of your stock and available for embossing.
canceled	The order was canceled and its blanks were not added to your stock.

Restock Logs

Every time a restock advances through its fulfillment flow, we create a Log entry. Logs let you follow an order from placement to confirmation without polling the restock itself — you get one log per step the order goes through (created, processing, confirmed).

Query the restock logs with GET /v2/issuing-restock/log (filter by restockIds, types, after / before), or fetch a single one with GET /v2/issuing-restock/log/:id. Each log carries the "restock" it refers to (shown abbreviated with "...").

Creating a Restock

Order blank cards by sending a "restocks" list. Each entry needs a count (the number of blanks to order) and the stockId of the Issuing Stock to replenish. Optionally tag each restock for later queries.

New restocks come back with status "created" — they are queued for fulfillment, not yet added to your stock.

ENDPOINT

POST /v2/issuing-restock

Querying Restocks

List your restocks in pages of up to 100. Narrow the results with "status", "stockIds", "ids", "tags" and the "after" / "before" date filters.

For example, filter by "status=created" to find orders still awaiting fulfillment, or by a "stockIds" value to see every restock placed against a given stock.

ENDPOINT

GET /v2/issuing-restock

Getting a Restock

Fetch a single restock by its id to check its current status and count.

ENDPOINT

GET /v2/issuing-restock/:id

Getting a Restock's Logs

Follow an order's fulfillment by querying its logs with the "restockIds" filter. A restock that was created, then processed, then confirmed returns one log per step.

You can also filter by "types" (created, processing, confirmed) and "after" / "before", or fetch a single log with GET /v2/issuing-restock/log/:id.

ENDPOINT

GET /v2/issuing-restock/log

Issuing Embossing Request Overview

An Issuing Embossing Request is the order to physically produce and ship a physical Issuing Card. After you create a physical card (which starts as "pending"), you submit an embossing request to have it printed, packaged and shipped to the holder.

Prerequisites. You need an existing physical Issuing Card (its cardId), an Issuing Embossing Kit (the kitId — the plastic, packaging and design to print), and available stock for that kit. Once the card reaches the holder, it is activated separately by setting its status to "active" together with a PIN.

Batch. Send a "requests" list to order up to 100 at once. Each request needs the cardId and kitId, the name embossed on the card (displayName1), and the full shipping address plus shippingService (the carrier, e.g. "loggi") and a shippingTrackingNumber. Optional fields: embosserId, displayName2 / displayName3, shippingPhone and tags.

Tracking the shipment. shippingTrackingNumber is the code you use to follow the parcel with the carrier; the request's status and Logs tell you how production and dispatch are progressing.

Embossing Request Statuses

Each Issuing Embossing Request has a status that reflects where its order is in the production and shipping flow:

Status	Description
created	The request was registered and is queued for production.
processing	The card is being embossed and prepared for shipping.
success	The card was embossed and shipped.
failed	The request could not be fulfilled.

Embossing Request Logs

Every time an embossing request advances through production and dispatch, we create a Log entry, so you can follow an order without polling the request itself. The "request" field in each log is a representation of the Issuing Embossing Request as it was at that point (shown abbreviated with "...").

The log types are: created, sending, sent, success and failed. Query the logs with GET /v2/issuing-embossing-request/log (filter by requestIds, types, after / before), or fetch a single one with GET /v2/issuing-embossing-request/log/:id.

Creating an Embossing Request

Order the physical production and shipping of one or more cards by sending a "requests" list. Each entry needs cardId, kitId, displayName1, the shipping address (shippingStreetLine1, shippingStreetLine2, shippingDistrict, shippingCity, shippingStateCode, shippingZipCode, shippingCountryCode), shippingService and shippingTrackingNumber.

New requests come back with status "created" — they are queued for production, not yet embossed.

ENDPOINT

POST /v2/issuing-embossing-request

Querying Embossing Requests

List your embossing requests in pages of up to 100. Filter by "status", "cardIds", "ids", "tags" and "after" / "before". Page through results with the returned "cursor".

ENDPOINT

GET /v2/issuing-embossing-request

Getting an Embossing Request

Fetch a single embossing request by its id to check its current status and shipping details.

ENDPOINT

GET /v2/issuing-embossing-request/:id

Getting an Embossing Request's Logs

Follow an order's production and dispatch by querying its logs with the "requestIds" filter. You can also filter by "types" (created, sending, sent, success, failed) and "after" / "before", or fetch a single log with GET /v2/issuing-embossing-request/log/:id.

ENDPOINT

GET /v2/issuing-embossing-request/log

Issuing Token Overview

An Issuing Token is an Issuing Card provisioned into a digital wallet — Apple Pay or Google Pay. The token is a wallet-specific stand-in for the card: purchases run through it without ever exposing the real card number.

You do not create a token here. Tokens are created through the Issuing Token Request provisioning flow, when a cardholder adds the card to a wallet. This section covers what you do afterwards: listing tokens, inspecting one, blocking or unblocking it, canceling it, and auditing its history.

Reading the object. walletId / walletName identify the wallet the card was added to (e.g. "apple" / "Apple Pay"). cardId points back to the Issuing Card that was tokenized, and merchantId is set only when the token is merchant-specific. externalId is the wallet's own identifier for the token. walletDeviceScore and walletAccountScore are risk scores the wallet reports at provisioning time — they are null when the wallet did not send them.

Token Statuses

Each Issuing Token has a status that reflects where it is in its life cycle:

Status	Description
pending	The wallet requested provisioning and the token is awaiting approval. It cannot be used for purchases yet.
active	The token was provisioned and can be used for purchases.
frozen	The wallet has temporarily suspended the token (for example, the device was locked or the card was suspended in the wallet). This state is driven by the wallet, not by this API.
blocked	The token is blocked and declines purchases. Unblock it by setting its status back to "active".
denied	The provisioning request was rejected, so the token was never activated.
canceled	The token was permanently canceled and removed from the wallet. This is irreversible.

Token Logs

Every change to an Issuing Token — including the wallet-driven provisioning steps — creates a Log entry, so you can audit a token's full history. The "token" field in each log is a representation of the Issuing Token as it was at that point (shown abbreviated with "...").

Each log carries a "type". The possible types are: created, denied, updated, unblocking, unblocked, blocking, blocked, frozen, unfrozen, canceling, canceled and failed. The transient "-ing" types (unblocking, blocking, canceling) mark a state change that was requested with the wallet and is still being confirmed; the matching past-tense type is emitted once it settles. "failed" marks a provisioning or status change the wallet rejected.

Query the token logs with GET /v2/issuing-token/log (filter by tokenIds, types, tokenTags, after / before), or fetch a single one with GET /v2/issuing-token/log/:id.

Listing Tokens

List the tokens that have been provisioned from your cards, in chunks of at most 100. Filter by "status", "cardIds" (to see every wallet a given card was added to), "externalIds", "tags" or "after" / "before".

Use the returned "cursor" to page through results — pass it back as the "cursor" parameter to get the next batch. A null cursor means there are no more pages.

ENDPOINT

GET /v2/issuing-token

Getting a Token

Fetch a single token by its id to inspect which card and wallet it belongs to and its current status.

ENDPOINT

GET /v2/issuing-token/:id

Blocking a Token

Block a token by setting its status to "blocked". A blocked token declines purchases through that wallet until you unblock it; the underlying Issuing Card and any other wallets keep working. You can also send a new "tags" array on the same request.

ENDPOINT

PATCH /v2/issuing-token/:id

Unblocking a Token

Unblock a previously blocked token by setting its status back to "active".

ENDPOINT

PATCH /v2/issuing-token/:id

Canceling a Token

Permanently cancel a token by its id. Its status becomes "canceled" and it is removed from the wallet. This action is irreversible — a token that is already canceled cannot be canceled again.

ENDPOINT

DELETE /v2/issuing-token/:id

Getting a Token's Logs

Audit a token's history by querying its logs with the "tokenIds" filter. Each step — provisioning, blocking, canceling and so on — produces one log. You can also filter by "types", "tokenTags" and "after" / "before", or fetch a single log with GET /v2/issuing-token/log/:id.

ENDPOINT

GET /v2/issuing-token/log

Issuing Token Request Overview

An Issuing Token Request starts the provisioning of an Issuing Card into a digital wallet (Apple Pay, Google Pay or a merchant wallet). It is the first step of tokenization: you call it, get back a signed payload, and hand that payload to the wallet's SDK on the device to finish adding the card.

The card is identified by its id (cardId) — the id Stark Infra returned when you created the Issuing Card.

walletId. This is NOT a token or a JWT — it is the wallet the card is being added to. Send one of "apple", "google" or "merchant".

methodCode. The provisioning method: "app" (in-app provisioning, where your app drives the flow through the wallet SDK) or "manual" (the cardholder types the card details into the wallet themselves).

The returned payload. The response gives you a "content" and a "signature". These are the inputs the wallet SDK expects to complete provisioning on the device. Stark Infra does not store a token request as a queryable resource — there is no status, no lifecycle and no log: once you have the content and signature, the rest of the flow happens between the device and the wallet, producing an Issuing Token.

Starting a tokenization

Send the card's id (cardId), the target walletId ("apple", "google" or "merchant") and the methodCode ("app" or "manual"). You may also attach a "metadata" object to carry your own data through the flow.

The response echoes back what you sent plus the "content" and "signature" you forward to the wallet SDK on the device. The result is wrapped in a "request" object.

ENDPOINT

POST /v2/issuing-token-request

Issuing Token Design Overview

An Issuing Token Design controls how a card looks inside a digital wallet — it is the artwork displayed for an Issuing Token once an Issuing Card has been tokenized into Apple Pay or Google Pay.

You provide the artwork; Stark Infra provisions it. The card design itself comes from you, the sub-issuer: send your artwork to help@starkinfra.com and Stark Infra provisions it with your card networks and makes the resulting Token Design available to your workspace.

Read-only through the API. Token designs are not created, changed or deleted through the API. Once provisioned, the API only lets you list the designs available to your workspace, fetch one by its id, and download its artwork as a PDF.

What you get back. Each design is a thin record: an id you reference when requesting a token, a human-readable name (e.g. "Apple Pay Card Art"), and created / updated datetimes. The visual asset itself is not part of the JSON — fetch it through the PDF endpoint.

Listing Token Designs

List the token designs available to your workspace. Filter by "ids" to fetch specific designs, and page through results with "limit" (max 100) and "cursor".

Use the "id" of the design you want when requesting an Issuing Token, so the tokenized card shows the right artwork in the wallet.

ENDPOINT

GET /v2/issuing-token-design

Getting a Token Design

Fetch a single token design by its id. A design only resolves if it belongs to your sub-issuer — fetching another sub-issuer's design is rejected.

ENDPOINT

GET /v2/issuing-token-design/:id

Downloading the Token Design PDF

Download the design's artwork as a PDF. This endpoint returns the raw binary file (no JSON wrapper), so save it straight to disk — with curl, use "--output" to write it to a file.

ENDPOINT

GET /v2/issuing-token-design/:id/pdf

Handling Purchase Events

In this section we're going deeper with the Issuing Purchase Events, that will allow you to handle the scenarios mentioned earlier.

First of all, you need to create a Webhook endpoint with issuing-purchase subscription.

Creating a Webhook

Receiving Events

Once created, you'll start to receive the Events at the informed URL. The Event will look like this:

Parsing Events

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. In case the event cannot be delivered after those three attempts, we will stop trying to deliver the message.

Listening to Issuing Purchase Events After answering a Issuing Purchase authorization request, you can use asynchronous Webhooks to monitor status changes of the entity. Issuing Purchases will follow the following life cycle:

Every time we change an Issuing Purchase, we create a Log. Logs are pretty useful for understanding the life cycle of each Issuing Purchase. Whenever a new Log is created, we will fire a Webhook to your registered URL. Check out this diagram to understand the possible Issuing Purchase Logs:

TYPES AND STATUS DEFINITIONS

Approved

An Issuing Purchase authorization request was approved by the sub-issuer or by the network/issuer default authorization protocol. The amount of money is reserved for the future settlement.

Confirmed

A purchase was settled by the network. At this point, the amount of money is transfered through the network.

Reversed

Some amount of the purchase was reversed, it can be partially or fully reversed.

Voided

Once a purchase is fully reversed, its status changes to voided.

Denied

An Issuing Purchase authorization request was denied by the sub-issuer or by the network/issuer default authorization protocol.

Canceled

An approved purchase was canceled by the acquirer. The reserved amount of money goes back to your Issuing Balance.

Updated

A new updated Log is generated when you set a description or tags for the purchase.

Success Webhook Example

4.1. Success Webhook Example

Failed Webhook Example

4.2. Failed Webhook Example

Setup

Authorization flow

Issuing Card Overview

Card Statuses

Card Logs

Creating a Card

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Unblocking (activating) a physical card

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Blocking a card

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Updating the Card PIN

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir