Create a wallet
curl --request POST \
--url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets \
--header 'Content-Type: application/json' \
--data '
{
"currency": "986",
"name": "Marketing",
"type": "SHARED",
"settings": {
"payment": {
"pix": true,
"bankSlip": true,
"card": true
}
},
"customFields": {
"cost-center": "CC-1020"
},
"shared": [
{
"id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"role": "OWNER"
}
]
}
'import requests
url = "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets"
payload = {
"currency": "986",
"name": "Marketing",
"type": "SHARED",
"settings": { "payment": {
"pix": True,
"bankSlip": True,
"card": True
} },
"customFields": { "cost-center": "CC-1020" },
"shared": [
{
"id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"role": "OWNER"
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
currency: '986',
name: 'Marketing',
type: 'SHARED',
settings: {payment: {pix: true, bankSlip: true, card: true}},
customFields: {'cost-center': 'CC-1020'},
shared: [{id: 'e3553bc1-5e20-4e17-b22a-a796fda0aa99', role: 'OWNER'}]
})
};
fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'currency' => '986',
'name' => 'Marketing',
'type' => 'SHARED',
'settings' => [
'payment' => [
'pix' => true,
'bankSlip' => true,
'card' => true
]
],
'customFields' => [
'cost-center' => 'CC-1020'
],
'shared' => [
[
'id' => 'e3553bc1-5e20-4e17-b22a-a796fda0aa99',
'role' => 'OWNER'
]
]
]),
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"
payload := strings.NewReader("{\n \"currency\": \"986\",\n \"name\": \"Marketing\",\n \"type\": \"SHARED\",\n \"settings\": {\n \"payment\": {\n \"pix\": true,\n \"bankSlip\": true,\n \"card\": true\n }\n },\n \"customFields\": {\n \"cost-center\": \"CC-1020\"\n },\n \"shared\": [\n {\n \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n \"role\": \"OWNER\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"986\",\n \"name\": \"Marketing\",\n \"type\": \"SHARED\",\n \"settings\": {\n \"payment\": {\n \"pix\": true,\n \"bankSlip\": true,\n \"card\": true\n }\n },\n \"customFields\": {\n \"cost-center\": \"CC-1020\"\n },\n \"shared\": [\n {\n \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n \"role\": \"OWNER\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"986\",\n \"name\": \"Marketing\",\n \"type\": \"SHARED\",\n \"settings\": {\n \"payment\": {\n \"pix\": true,\n \"bankSlip\": true,\n \"card\": true\n }\n },\n \"customFields\": {\n \"cost-center\": \"CC-1020\"\n },\n \"shared\": [\n {\n \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n \"role\": \"OWNER\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"_id": "66f2a3d1b4d3e80012c9a0d2",
"realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"accountId": "66f2a1c7b4d3e80012c9a0b4",
"environment": "LIVE",
"currency": "986",
"status": "PENDING",
"role": "CHECKING",
"type": "SHARED",
"shared": [
{
"id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"role": "OWNER",
"_id": "66f2a3d1b4d3e80012c9a0d3",
"firstName": "Mariana",
"lastName": "Costa",
"email": "mariana.costa@acme.com.br"
}
],
"isSuper": false,
"createdAt": "2024-10-01T12:30:05.000Z",
"updatedAt": "2024-10-01T12:34:41.000Z",
"external": {
"balanceAccountGroupId": "4f6b0e1d-2b3a-4c5d-8e9f-0a1b2c3d4e5f",
"accountNumber": 10023456,
"branch": "0001",
"accountType": "PREPAID"
},
"customFields": {
"cost-center": "CC-1020"
},
"name": "Marketing",
"settings": {
"payment": {
"pix": true,
"bankSlip": true,
"card": true
},
"notification": {
"balanceLimit": {
"amount": 50000,
"email": true,
"isActive": true
}
}
},
"walletProduct": "NORMAL",
"createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"updatedBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"accountType": "PREPAID",
"__v": 0
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "ACCOUNT_NOT_OPEN",
"origin": "BANKING",
"message": "Account not open"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "FORBIDDEN_WALLET",
"origin": "BANKING",
"message": "You do not have permission to perform this action on this wallet"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "ACCOUNT_NOT_FOUND",
"origin": "BANKING",
"message": "Account not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "WALLET_CONFLICT",
"origin": "BANKING",
"message": "Wallet already exists"
}{
"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": "currency",
"message": "Invalid option: expected one of \"986\"",
"code": "CURRENCY_ONE_OF",
"values": [
"986"
]
}
]
}Create a wallet
Creates a wallet in the organization’s account.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
accounts
/
{accountId}
/
wallets
Create a wallet
curl --request POST \
--url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets \
--header 'Content-Type: application/json' \
--data '
{
"currency": "986",
"name": "Marketing",
"type": "SHARED",
"settings": {
"payment": {
"pix": true,
"bankSlip": true,
"card": true
}
},
"customFields": {
"cost-center": "CC-1020"
},
"shared": [
{
"id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"role": "OWNER"
}
]
}
'import requests
url = "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets"
payload = {
"currency": "986",
"name": "Marketing",
"type": "SHARED",
"settings": { "payment": {
"pix": True,
"bankSlip": True,
"card": True
} },
"customFields": { "cost-center": "CC-1020" },
"shared": [
{
"id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"role": "OWNER"
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
currency: '986',
name: 'Marketing',
type: 'SHARED',
settings: {payment: {pix: true, bankSlip: true, card: true}},
customFields: {'cost-center': 'CC-1020'},
shared: [{id: 'e3553bc1-5e20-4e17-b22a-a796fda0aa99', role: 'OWNER'}]
})
};
fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'currency' => '986',
'name' => 'Marketing',
'type' => 'SHARED',
'settings' => [
'payment' => [
'pix' => true,
'bankSlip' => true,
'card' => true
]
],
'customFields' => [
'cost-center' => 'CC-1020'
],
'shared' => [
[
'id' => 'e3553bc1-5e20-4e17-b22a-a796fda0aa99',
'role' => 'OWNER'
]
]
]),
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"
payload := strings.NewReader("{\n \"currency\": \"986\",\n \"name\": \"Marketing\",\n \"type\": \"SHARED\",\n \"settings\": {\n \"payment\": {\n \"pix\": true,\n \"bankSlip\": true,\n \"card\": true\n }\n },\n \"customFields\": {\n \"cost-center\": \"CC-1020\"\n },\n \"shared\": [\n {\n \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n \"role\": \"OWNER\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"986\",\n \"name\": \"Marketing\",\n \"type\": \"SHARED\",\n \"settings\": {\n \"payment\": {\n \"pix\": true,\n \"bankSlip\": true,\n \"card\": true\n }\n },\n \"customFields\": {\n \"cost-center\": \"CC-1020\"\n },\n \"shared\": [\n {\n \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n \"role\": \"OWNER\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"986\",\n \"name\": \"Marketing\",\n \"type\": \"SHARED\",\n \"settings\": {\n \"payment\": {\n \"pix\": true,\n \"bankSlip\": true,\n \"card\": true\n }\n },\n \"customFields\": {\n \"cost-center\": \"CC-1020\"\n },\n \"shared\": [\n {\n \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n \"role\": \"OWNER\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"_id": "66f2a3d1b4d3e80012c9a0d2",
"realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"accountId": "66f2a1c7b4d3e80012c9a0b4",
"environment": "LIVE",
"currency": "986",
"status": "PENDING",
"role": "CHECKING",
"type": "SHARED",
"shared": [
{
"id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"role": "OWNER",
"_id": "66f2a3d1b4d3e80012c9a0d3",
"firstName": "Mariana",
"lastName": "Costa",
"email": "mariana.costa@acme.com.br"
}
],
"isSuper": false,
"createdAt": "2024-10-01T12:30:05.000Z",
"updatedAt": "2024-10-01T12:34:41.000Z",
"external": {
"balanceAccountGroupId": "4f6b0e1d-2b3a-4c5d-8e9f-0a1b2c3d4e5f",
"accountNumber": 10023456,
"branch": "0001",
"accountType": "PREPAID"
},
"customFields": {
"cost-center": "CC-1020"
},
"name": "Marketing",
"settings": {
"payment": {
"pix": true,
"bankSlip": true,
"card": true
},
"notification": {
"balanceLimit": {
"amount": 50000,
"email": true,
"isActive": true
}
}
},
"walletProduct": "NORMAL",
"createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"updatedBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"accountType": "PREPAID",
"__v": 0
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "ACCOUNT_NOT_OPEN",
"origin": "BANKING",
"message": "Account not open"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "FORBIDDEN_WALLET",
"origin": "BANKING",
"message": "You do not have permission to perform this action on this wallet"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "ACCOUNT_NOT_FOUND",
"origin": "BANKING",
"message": "Account not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "WALLET_CONFLICT",
"origin": "BANKING",
"message": "Wallet already exists"
}{
"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": "currency",
"message": "Invalid option: expected one of \"986\"",
"code": "CURRENCY_ONE_OF",
"values": [
"986"
]
}
]
}The wallet starts
PENDING, with no bank account details yet, and becomes ACTIVE once provisioned — usually within seconds; only then can it hold balances and move money. It is shared with the users in shared, or, when you omit it, with you alone as OWNER; users who aren’t members of the organization are left out. A PERSONAL wallet can’t be created while its first OWNER already has an ACTIVE, PENDING or BLOCKED one in the account. Send x-environment: LIVE to create a production wallet.
The account must be open in the environment, and its wallet limit, when it has one, counts every wallet it ever had — closed ones included. Only organization admins can create wallets.Headers
Environment to create the wallet in: LIVE (production) or TEST (sandbox). When you omit it, the wallet is created in TEST; any other value is rejected.
Available options:
LIVE, TEST Path Parameters
ID of your realm.
Format: UUID
ID of the organization the wallet is created in.
Format: UUID
ID of the organization's account (24 hexadecimal characters).
Pattern:
^[0-9a-fA-F]{24}$Body
application/json
Currency of the wallet, as an ISO 4217 numeric code: 986 (Brazilian real) is the only one accepted.
Available options:
986 Example:
"986"
Name of the wallet.
Minimum string length:
1Example:
"Marketing"
Kind of wallet: SHARED (used by a team, the default), PERSONAL (a single user's) or VEHICLE (a vehicle's).
Available options:
PERSONAL, SHARED, VEHICLE Example:
"SHARED"
Settings of the wallet. When you omit them, every payment method is enabled.
Show child attributes
Show child attributes
Values of the organization's wallet custom fields, keyed by each field's slug. Each value must fit its field's type and options.
Example: {"cost-center":"CC-1020"}
Show child attributes
Show child attributes
Example:
{ "cost-center": "CC-1020" }
Users who can use the wallet, and how. At least one must be an OWNER who is a member of the organization; users who aren't members are left out. When you omit it, you become the wallet's only OWNER.
Minimum array length:
1Show child attributes
Show child attributes
Response
Successful response
A wallet: a balance of the organization's account, with its own bank account details, cards and PIX keys, shared with the users who can use it.
ID of the wallet.
Example:
"66f2a3d1b4d3e80012c9a0d2"
ID of the realm the wallet belongs to.
Example:
"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"
ID of the organization the wallet belongs to.
Example:
"c4bd3f21-dfbd-44e8-8055-68ba15bed410"
ID of the account the wallet belongs to.
Example:
"66f2a1c7b4d3e80012c9a0b4"
Environment the wallet lives in: LIVE (production) or TEST (sandbox).
Available options:
LIVE, TEST Example:
"LIVE"
Currency of the wallet, as an ISO 4217 numeric code. Always 986 (Brazilian real).
Example:
"986"
Status of the wallet: PENDING (being created — it can't move money yet), ACTIVE, BLOCKED (it can't move money until it is unblocked), CANCELLING or CANCELLED (closed), REPROVED (its creation was refused), FRAUD_ANALYSIS (on hold while suspected fraud is analyzed) or FRAUD_CONFIRMED (closed for fraud).
Available options:
PENDING, ACTIVE, CANCELLING, CANCELLED, BLOCKED, REPROVED, FRAUD_ANALYSIS, FRAUD_CONFIRMED Example:
"PENDING"
Role of the wallet in the account: DEFAULT for the organization's main wallet — the one that funds and receives the other wallets' transfers — and CHECKING for every other wallet. A few older wallets carry another value.
Example:
"CHECKING"
Kind of wallet: ORGANIZATION (the organization's main wallet), SHARED (used by a team), PERSONAL (a single user's) or VEHICLE (a vehicle's, for its fuel and other purchases).
Available options:
PERSONAL, SHARED, ORGANIZATION, VEHICLE Example:
"SHARED"
Users who can use the wallet, and how. Organization admins can use every wallet.
Show child attributes
Show child attributes
Whether the wallet's cards are on the premium card product.
Example:
false
When the wallet was created.
Example:
"2024-10-01T12:30:05.000Z"
When the wallet last changed.
Example:
"2024-10-01T12:34:41.000Z"
The wallet's bank account. Absent on a few wallets created before it was recorded.
Show child attributes
Show child attributes
Values of the organization's wallet custom fields, keyed by each field's slug. Absent when the wallet has none.
Example: {"cost-center":"CC-1020"}
Show child attributes
Show child attributes
Example:
{ "cost-center": "CC-1020" }
Name of the wallet. Absent on older wallets created without one.
Example:
"Marketing"
Settings of the wallet. Absent on older wallets created without them.
Show child attributes
Show child attributes
Card product of the wallet, inherited from the account. Absent on older wallets.
Example:
"NORMAL"
ID of the user who created the wallet. Absent, or null, on older wallets.
Example:
"e3553bc1-5e20-4e17-b22a-a796fda0aa99"
ID of the user who created the wallet; editing it doesn't change this field. Absent, or null, on older wallets.
Example:
"e3553bc1-5e20-4e17-b22a-a796fda0aa99"
Type of the wallet's bank account, on older wallets only: the same as external.accountType.
Available options:
PREPAID, CCLG Example:
"PREPAID"
Internal revision counter of the wallet.
Example:
0