> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Issue a card > Issues a card in a wallet: a new virtual card, or a physical card you already received. A `VIRTUAL` card is issued at once; read its full number and security code with the card-details endpoint. An `EMBOSSED` card is a physical card linked to the wallet by the `cardId` read from the QR code that comes with it. Either way the card is returned `ACTIVE`, spending from the wallet's balance. Send `x-environment: LIVE` to issue a production card. Pass `cardLimits` to create the card's spending limits in the same call — the card is activated only after they are in place. You can also add limits later with the create-a-card-limit endpoint. The account must be open and the wallet active in the environment, with card payments enabled, and the account must have room in its card limit, which counts every card it issued — blocked and cancelled ones included. Organization admins can issue cards in any wallet; other users only in wallets they use as `OWNER` or `USER`. **Retries:** issuing a virtual card isn't idempotent — retrying a request that failed after the card was issued issues another one. List the wallet's cards before retrying. ## OpenAPI ````yaml /api-reference/banking.openapi.json post /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards openapi: 3.0.3 info: title: Banking version: 1.0.0 description: >- Portão 3 banking API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Banking attaches a zod validationSchema at the route; request bodies are resolved from it (object + array roots). Responses have no presenter layer, so they stay tier=unknown. Confidence tiers: generated:typed=215 copied:manual=4 unknown=52. servers: - url: https://api.banking.v2.portao3.com.br/ description: production - url: https://api.banking.dev.3pers.com.br/ description: development security: [] tags: - name: Accounts - name: Account Limits - name: Wallets - name: Cards - name: Card Limits - name: Cards 3DS - name: PIX - name: PIX Keys (DICT) - name: PIX Charges - name: PIX Automatic - name: PIX Initiation (Open Finance) - name: PIX Infractions (MED) - name: Boleto - name: Boleto Charges - name: TED - name: Transfers - name: Transactions - name: Cashback - name: Currency Codes - name: Reversals paths: /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards: post: tags: - Cards summary: Issue a card description: >- Issues a card in a wallet: a new virtual card, or a physical card you already received. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdWalletsByWalletIdCards parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization the wallet belongs to. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: accountId in: path required: true description: ID of the organization's account (24 hexadecimal characters). schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 66f2a1c7b4d3e80012c9a0b4 - name: walletId in: path required: true description: >- ID of the wallet the card is issued in (24 hexadecimal characters), or `default` for the organization's main wallet. schema: type: string pattern: ^([0-9a-fA-F]{24}|default)$ example: 66f2a3d1b4d3e80012c9a0d2 - name: x-environment in: header required: false description: >- Environment to issue the card in: `LIVE` (production) or `TEST` (sandbox). When you omit it, the card is issued in `TEST`; any other value is rejected. schema: type: string enum: - LIVE - TEST example: LIVE requestBody: required: true content: application/json: schema: type: object properties: type: type: string enum: - VIRTUAL - EMBOSSED description: >- Kind of card: `VIRTUAL` issues a new card now; `EMBOSSED` links a physical card you already received to the wallet, identified by `cardId`. example: VIRTUAL cardId: description: >- Required for an `EMBOSSED` card: the identifier read from the QR code that comes with the physical card. Ignored for a `VIRTUAL` card. example: 3f1c9a52-7d4e-4b8a-9e21-6c0d8b7a5f43 type: string singleUse: description: >- `true` issues a single-use card, blocked after its first cleared transaction. Only for `VIRTUAL` cards. Defaults to `false`. example: false type: boolean name: description: Name of the card, to tell it apart in lists. example: Marketing - Ads type: string customFields: description: >- Values of the organization's card custom fields, keyed by each field's `slug`. Each value must fit its field's type and options. --- Example: `{"cost-center":"CC-1020"}` example: cost-center: CC-1020 type: object additionalProperties: {} cardLimits: description: >- Spending limits to create together with the card. Each one works like a limit created with the create-a-card-limit endpoint, for this card only. type: array items: type: object properties: name: description: Name of the limit. example: Campaign budget type: string amount: type: integer minimum: 1 description: >- Amount the card can spend under this limit, in cents (BRL). example: 150000 startDate: type: string pattern: ^\d{4}-\d{2}-\d{2} description: First day of the limit, as `YYYY-MM-DD`. example: '2026-11-01' endDate: type: string pattern: ^\d{4}-\d{2}-\d{2} description: >- Last day of the limit, as `YYYY-MM-DD`. The limit stops applying when this day ends. example: '2026-11-30' ruleIds: minItems: 1 type: array items: type: string pattern: >- ^([0-9a-fA-F]{24}|HOTEL|FLIGHT|TRAVEL|FLEX_INTERNATIONAL)$ example: FLEX_INTERNATIONAL description: >- Card limit rules the limit applies: IDs of your account's rules, or the names of the default rule sets `HOTEL`, `FLIGHT`, `TRAVEL` and `FLEX_INTERNATIONAL`. A transaction is allowed when any one of them matches. --- Example: `["FLEX_INTERNATIONAL"]` required: - amount - startDate - endDate - ruleIds required: - type responses: '201': description: Successful response content: application/json: schema: type: object properties: _id: type: string description: ID of the card. Use it as `cardId` in the card endpoints. example: 66f2a4b8b4d3e80012c9a0e1 realmId: type: string description: ID of the realm the card belongs to. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization the card belongs to. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid accountId: type: string description: ID of the organization's account. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: ID of the wallet the card spends from. example: 66f2a3d1b4d3e80012c9a0d2 environment: type: string enum: - LIVE - TEST description: >- Environment of the card: `LIVE` (production) or `TEST` (sandbox). example: LIVE panMasked: type: string description: >- Card number with its middle digits masked: the first six and the last four digits. Read the full number with the card-details endpoint. example: 524674******4821 expiryDate: type: string description: Expiry month and year of the card, as `MM/YYYY`. example: 11/2031 tokenisationPermitted: type: boolean description: >- Whether the card can be added to a device wallet such as Apple Pay, Google Pay or Samsung Pay. example: true singleUse: type: boolean description: >- Whether the card is single-use: blocked after its first cleared transaction. Absent on some older cards. example: false type: type: string enum: - VIRTUAL - EMBOSSED description: >- Kind of card: `VIRTUAL` or `EMBOSSED` (a physical card). Absent on a few old cancelled cards. example: VIRTUAL external: type: object properties: cardId: type: string description: Identifier of the card at the issuer. example: 3f1c9a52-7d4e-4b8a-9e21-6c0d8b7a5f43 instrumentId: type: string description: >- Identifier the issuer uses to apply the card's spending limits. Absent on older cards. example: 8b2e4f60-1a3c-4d5e-9f70-2b4c6d8e0a12 description: Identifiers of the card at the card issuer. status: type: string enum: - ACTIVE - BLOCKED - CANCELLED description: >- Status of the card: `ACTIVE` (it can be used), `BLOCKED` (blocked — unblock it to use it again) or `CANCELLED` (closed by the issuer for good). example: ACTIVE customFields: type: object additionalProperties: {} description: >- Values of the organization's card custom fields, keyed by each field's `slug`. Absent when the card has none. --- Example: `{"cost-center":"CC-1020"}` example: cost-center: CC-1020 issuedAt: type: string description: >- When the card was issued, or linked to the wallet for a physical card. Absent on a few older cards. example: '2026-11-02T13:05:11.000Z' format: date-time name: type: string description: Name of the card. Absent when it was issued without one. example: Marketing - Ads ownerName: type: string description: >- Cardholder name associated with the card: in upper case, without accents, abbreviated to about 26 characters. Absent on older cards. example: MARIANA COSTA isSuper: type: boolean description: >- Whether the card is on the premium card product. Absent on older cards. example: false walletProduct: type: string description: >- Card product of the wallet when the card was issued. Absent on older cards. example: NORMAL cardLimitIds: type: array items: type: string example: 66f2a5c2b4d3e80012c9a0f3 description: >- Legacy field kept on older cards: IDs of limits created with the card. It is not kept up to date — list the card's limits with the card-limits endpoint instead. --- Example: `["66f2a5c2b4d3e80012c9a0f3"]` createdBy: type: string nullable: true description: >- ID of the user who issued the card. Absent, or `null`, on older cards. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 updatedBy: type: string nullable: true description: >- ID of the user who last changed the card. Absent, or `null`, on older cards. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 createdAt: type: string description: When the card record was created. example: '2026-11-02T13:05:11.000Z' format: date-time updatedAt: type: string description: When the card record last changed. example: '2026-11-02T13:05:12.000Z' format: date-time __v: type: number description: Version of the record, incremented by some updates. example: 0 required: - _id - realmId - organizationId - accountId - walletId - environment - panMasked - external - status - createdAt - updatedAt description: A payment card of a wallet. '400': description: >- `ACCOUNT_NOT_OPEN` — The account isn't open in this environment. `WALLET_NOT_ACTIVE` — The wallet isn't `ACTIVE`. `ACCOUNT_LIMITS_EXCEEDED` — The account already has as many cards as its limits allow. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - ACCOUNT_NOT_OPEN - WALLET_NOT_ACTIVE - ACCOUNT_LIMITS_EXCEEDED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: ACCOUNT_NOT_OPEN origin: BANKING message: Account not open '403': description: >- `FORBIDDEN_WALLET` — You can't issue cards in this wallet, or card payments are turned off in its settings. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - FORBIDDEN_WALLET description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: FORBIDDEN_WALLET origin: BANKING message: >- You do not have permission to perform this action on this wallet '404': description: >- `ACCOUNT_NOT_FOUND` — No account with this ID exists in the organization. `WALLET_NOT_FOUND` — No wallet with this ID exists in the account and environment. `CARD_LIMIT_RULE_NOT_FOUND` — A `cardLimits` rule ID is not one of the account's rules in this environment. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - ACCOUNT_NOT_FOUND - WALLET_NOT_FOUND - CARD_LIMIT_RULE_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: ACCOUNT_NOT_FOUND origin: BANKING message: Account not found '422': description: >- `BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field. `CUSTOM_FIELD_NOT_FOUND` — A `customFields` key is not the `slug` of a custom field of the organization; `fields` names it. `CUSTOM_FIELD_NOT_ALLOWED` — A `customFields` key is a custom field that doesn't apply to cards; `fields` names it. `CUSTOM_FIELD_INVALID_VALUE` — A `customFields` value doesn't fit its field's type or options; `fields` names it. `CARD_ALREADY_LINKED` — The physical card in `cardId` is already linked to a wallet. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST - CUSTOM_FIELD_NOT_FOUND - CUSTOM_FIELD_NOT_ALLOWED - CUSTOM_FIELD_INVALID_VALUE - CARD_ALREADY_LINKED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: BANKING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: type message: 'Invalid option: expected one of "VIRTUAL"|"EMBOSSED"' code: TYPE_ONE_OF values: - VIRTUAL - EMBOSSED '500': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The card issuer failed, or its answer never arrived. List the wallet's cards before retrying. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '502': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The card issuer answered with a server error. List the wallet's cards before retrying. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '503': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The card issuer is unavailable. List the wallet's cards before retrying. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '504': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The card issuer didn't answer in time. List the wallet's cards before retrying. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BANKING_PROVIDER_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider did not respond in time, please retry ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.