Update a card

curl --request PUT \
  --url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Marketing - Ads",
  "singleUse": false,
  "customFields": {
    "cost-center": "CC-1020"
  }
}
'

import requests

url = "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}"

payload = {
    "name": "Marketing - Ads",
    "singleUse": False,
    "customFields": { "cost-center": "CC-1020" }
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Marketing - Ads',
    singleUse: false,
    customFields: {'cost-center': 'CC-1020'}
  })
};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Marketing - Ads',
    'singleUse' => false,
    'customFields' => [
        'cost-center' => 'CC-1020'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}"

	payload := strings.NewReader("{\n  \"name\": \"Marketing - Ads\",\n  \"singleUse\": false,\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Marketing - Ads\",\n  \"singleUse\": false,\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Marketing - Ads\",\n  \"singleUse\": false,\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "66f2a4b8b4d3e80012c9a0e1",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "accountId": "66f2a1c7b4d3e80012c9a0b4",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "environment": "LIVE",
  "panMasked": "524674******4821",
  "external": {
    "cardId": "3f1c9a52-7d4e-4b8a-9e21-6c0d8b7a5f43",
    "instrumentId": "8b2e4f60-1a3c-4d5e-9f70-2b4c6d8e0a12"
  },
  "status": "ACTIVE",
  "createdAt": "2026-11-02T13:05:11.000Z",
  "updatedAt": "2026-11-02T13:05:12.000Z",
  "expiryDate": "11/2031",
  "tokenisationPermitted": true,
  "singleUse": false,
  "type": "VIRTUAL",
  "customFields": {
    "cost-center": "CC-1020"
  },
  "issuedAt": "2026-11-02T13:05:11.000Z",
  "name": "Marketing - Ads",
  "ownerName": "MARIANA COSTA",
  "isSuper": false,
  "walletProduct": "NORMAL",
  "cardLimitIds": [
    "66f2a5c2b4d3e80012c9a0f3"
  ],
  "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "updatedBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "__v": 0
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "ACCOUNT_NOT_FOUND",
  "origin": "BANKING",
  "message": "Account not found"
}

{
  "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": "organizationId",
      "message": "Invalid UUID",
      "code": "ORGANIZATIONID_UUID"
    }
  ]
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider temporarily unavailable, please retry"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider temporarily unavailable, please retry"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider temporarily unavailable, please retry"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider did not respond in time, please retry"
}

PUT

realms

{realmId}

organizations

{organizationId}

accounts

{accountId}

wallets

{walletId}

cards

{cardId}

Update a card

curl --request PUT \
  --url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Marketing - Ads",
  "singleUse": false,
  "customFields": {
    "cost-center": "CC-1020"
  }
}
'

import requests

url = "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}"

payload = {
    "name": "Marketing - Ads",
    "singleUse": False,
    "customFields": { "cost-center": "CC-1020" }
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Marketing - Ads',
    singleUse: false,
    customFields: {'cost-center': 'CC-1020'}
  })
};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Marketing - Ads',
    'singleUse' => false,
    'customFields' => [
        'cost-center' => 'CC-1020'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}"

	payload := strings.NewReader("{\n  \"name\": \"Marketing - Ads\",\n  \"singleUse\": false,\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Marketing - Ads\",\n  \"singleUse\": false,\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/cards/{cardId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Marketing - Ads\",\n  \"singleUse\": false,\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "66f2a4b8b4d3e80012c9a0e1",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "accountId": "66f2a1c7b4d3e80012c9a0b4",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "environment": "LIVE",
  "panMasked": "524674******4821",
  "external": {
    "cardId": "3f1c9a52-7d4e-4b8a-9e21-6c0d8b7a5f43",
    "instrumentId": "8b2e4f60-1a3c-4d5e-9f70-2b4c6d8e0a12"
  },
  "status": "ACTIVE",
  "createdAt": "2026-11-02T13:05:11.000Z",
  "updatedAt": "2026-11-02T13:05:12.000Z",
  "expiryDate": "11/2031",
  "tokenisationPermitted": true,
  "singleUse": false,
  "type": "VIRTUAL",
  "customFields": {
    "cost-center": "CC-1020"
  },
  "issuedAt": "2026-11-02T13:05:11.000Z",
  "name": "Marketing - Ads",
  "ownerName": "MARIANA COSTA",
  "isSuper": false,
  "walletProduct": "NORMAL",
  "cardLimitIds": [
    "66f2a5c2b4d3e80012c9a0f3"
  ],
  "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "updatedBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "__v": 0
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "ACCOUNT_NOT_FOUND",
  "origin": "BANKING",
  "message": "Account not found"
}

{
  "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": "organizationId",
      "message": "Invalid UUID",
      "code": "ORGANIZATIONID_UUID"
    }
  ]
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider temporarily unavailable, please retry"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider temporarily unavailable, please retry"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider temporarily unavailable, please retry"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BANKING_PROVIDER_UNAVAILABLE",
  "origin": "BANKING",
  "message": "Banking provider did not respond in time, please retry"
}

Send only what you change: a field you leave out keeps its value — except within customFields, which replaces all of the card’s custom fields when you send it. The card’s status, number and limits are managed by their own endpoints. Use default as walletId for the organization’s main wallet, and send x-environment: LIVE for a production card. Any member of the organization can update a card.

Headers

x-environment

enum<string>

Environment of the card: LIVE (production) or TEST (sandbox). When you omit it, the request runs in TEST; any other value is rejected.

Available options:

LIVE,

TEST

Path Parameters

realmId

string<uuid>

required

ID of your realm.

Format: UUID

organizationId

string<uuid>

required

ID of the organization the card belongs to.

Format: UUID

accountId

string

required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

walletId

string

required

ID of the card's wallet (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

cardId

string

required

ID of the card to update (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

Body

application/json

name

string

New name of the card. It can't be blank.

Minimum string length: 1

Example:

"Marketing - Ads"

singleUse

boolean

Marks the card as single-use (true) or reusable (false) on the card record. It doesn't change how the card was issued: a card's single-use behaviour is set when it is created.

Example:

false

customFields

object

Values of the organization's card custom fields, keyed by each field's slug. When you send it, it replaces all of the card's custom fields: a field you leave out is removed. Each value must fit its field's type and options.

Example: {"cost-center":"CC-1020"}

Show child attributes

Example:

{ "cost-center": "CC-1020" }

Response

Successful response

A payment card of a wallet.

_id

string

required

ID of the card. Use it as cardId in the card endpoints.

Example:

"66f2a4b8b4d3e80012c9a0e1"

realmId

string<uuid>

required

ID of the realm the card belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId

string<uuid>

required

ID of the organization the card belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId

string

required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId

string

required

ID of the wallet the card spends from.

Example:

"66f2a3d1b4d3e80012c9a0d2"

environment

enum<string>

required

Environment of the card: LIVE (production) or TEST (sandbox).

Available options:

LIVE,

TEST

Example:

"LIVE"

panMasked

string

required

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"

external

object

required

Identifiers of the card at the card issuer.

Show child attributes

status

enum<string>

required

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).

Available options:

ACTIVE,

BLOCKED,

CANCELLED

Example:

"ACTIVE"

createdAt

string<date-time>

required

When the card record was created.

Example:

"2026-11-02T13:05:11.000Z"

updatedAt

string<date-time>

required

When the card record last changed.

Example:

"2026-11-02T13:05:12.000Z"

expiryDate

string

Expiry month and year of the card, as MM/YYYY.

Example:

"11/2031"

tokenisationPermitted

boolean

Whether the card can be added to a device wallet such as Apple Pay, Google Pay or Samsung Pay.

Example:

true

singleUse

boolean

Whether the card is single-use: blocked after its first cleared transaction. Absent on some older cards.

Example:

false

type

enum<string>

Kind of card: VIRTUAL or EMBOSSED (a physical card). Absent on a few old cancelled cards.

Available options:

VIRTUAL,

EMBOSSED

Example:

"VIRTUAL"

customFields

object

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"}

Show child attributes

Example:

{ "cost-center": "CC-1020" }

issuedAt

string<date-time>

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"

name

string

Name of the card. Absent when it was issued without one.

Example:

"Marketing - Ads"

ownerName

string

Cardholder name associated with the card: in upper case, without accents, abbreviated to about 26 characters. Absent on older cards.

Example:

"MARIANA COSTA"

isSuper

boolean

Whether the card is on the premium card product. Absent on older cards.

Example:

false

walletProduct

string

Card product of the wallet when the card was issued. Absent on older cards.

Example:

"NORMAL"

cardLimitIds

string[]

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

string | null

ID of the user who issued the card. Absent, or null, on older cards.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

updatedBy

string | null

ID of the user who last changed the card. Absent, or null, on older cards.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

__v

number

Version of the record, incremented by some updates.

Example:

0

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

Update a card

Headers

Path Parameters

Body

Response