Subcontas

Create Subaccount

Cria uma subconta: um ledger de saldo próprio para um cliente seu, dentro da sua conta. Cobranças criadas com subaccountId creditam o saldo da subconta quando o pagamento confirma, e você consulta quanto pertence a cada cliente sem manter essa contabilidade do seu lado.

A subconta não é uma conta PurinCash: ela não tem login, não tem chave de API e o dinheiro real permanece na carteira da sua conta. O saldo dela é uma camada de atribuição sobre o seu, e por isso criar subconta não exige documento nem aprovação.

Se externalId for informado e já existir outra subconta com o mesmo valor neste ambiente, a resposta é 409 com o subaccountId da existente, o que permite tratar a criação como idempotente. Limite de 1000 subcontas por conta e por ambiente.

POST

subaccounts

Create Subaccount

curl --request POST \
  --url https://api.purincash.com/v1/subaccounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Loja do João",
  "email": "joao@exemplo.com",
  "externalId": "cliente_42",
  "metadata": "{\"plano\":\"pro\"}",
  "feePercent": 5,
  "feeFixedCents": 100,
  "payoutFeePercent": 1,
  "payoutFeeFixedCents": 200
}
'

import requests

url = "https://api.purincash.com/v1/subaccounts"

payload = {
    "name": "Loja do João",
    "email": "joao@exemplo.com",
    "externalId": "cliente_42",
    "metadata": "{\"plano\":\"pro\"}",
    "feePercent": 5,
    "feeFixedCents": 100,
    "payoutFeePercent": 1,
    "payoutFeeFixedCents": 200
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Loja do João',
    email: 'joao@exemplo.com',
    externalId: 'cliente_42',
    metadata: '{"plano":"pro"}',
    feePercent: 5,
    feeFixedCents: 100,
    payoutFeePercent: 1,
    payoutFeeFixedCents: 200
  })
};

fetch('https://api.purincash.com/v1/subaccounts', 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.purincash.com/v1/subaccounts",
  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([
    'name' => 'Loja do João',
    'email' => 'joao@exemplo.com',
    'externalId' => 'cliente_42',
    'metadata' => '{"plano":"pro"}',
    'feePercent' => 5,
    'feeFixedCents' => 100,
    'payoutFeePercent' => 1,
    'payoutFeeFixedCents' => 200
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.purincash.com/v1/subaccounts"

	payload := strings.NewReader("{\n  \"name\": \"Loja do João\",\n  \"email\": \"joao@exemplo.com\",\n  \"externalId\": \"cliente_42\",\n  \"metadata\": \"{\\\"plano\\\":\\\"pro\\\"}\",\n  \"feePercent\": 5,\n  \"feeFixedCents\": 100,\n  \"payoutFeePercent\": 1,\n  \"payoutFeeFixedCents\": 200\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.purincash.com/v1/subaccounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Loja do João\",\n  \"email\": \"joao@exemplo.com\",\n  \"externalId\": \"cliente_42\",\n  \"metadata\": \"{\\\"plano\\\":\\\"pro\\\"}\",\n  \"feePercent\": 5,\n  \"feeFixedCents\": 100,\n  \"payoutFeePercent\": 1,\n  \"payoutFeeFixedCents\": 200\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.purincash.com/v1/subaccounts")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Loja do João\",\n  \"email\": \"joao@exemplo.com\",\n  \"externalId\": \"cliente_42\",\n  \"metadata\": \"{\\\"plano\\\":\\\"pro\\\"}\",\n  \"feePercent\": 5,\n  \"feeFixedCents\": 100,\n  \"payoutFeePercent\": 1,\n  \"payoutFeeFixedCents\": 200\n}"

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

{
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Loja do João",
  "email": "joao@exemplo.com",
  "externalId": "cliente_42",
  "active": true,
  "balanceCents": 0,
  "totalReceivedCents": 0,
  "metadata": "{\"plano\":\"pro\"}",
  "createdAt": "2026-08-04T12:00:00.000Z",
  "updatedAt": "2026-08-04T12:00:00.000Z"
}

{
  "error": "name is required"
}

{
  "error": "A subaccount with this externalId already exists",
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

{
  "error": "Internal error"
}

Authorizations

Authorization

string

header

required

Chave de API gerada no dashboard da PurinCash (ps_live_ ou ps_test_).

Body

application/json

name

string

required

Nome do cliente dono da subconta.

Maximum string length: 100

string

E-mail de contato do cliente (informativo, não autentica nada).

Maximum string length: 255

externalId

string

ID do cliente no seu sistema. Único por conta e ambiente quando presente. Repetir devolve 409 com a subconta existente.

Maximum string length: 200

metadata

string

default:{}

String JSON livre, devolvida sem alteração.

Maximum string length: 2048

feePercent

number

default:0

Markup percentual da plataforma sobre cada venda desta subconta (até 2 casas decimais). Descontado do líquido antes do crédito; a fatia fica na conta principal e o lançamento sale grava o feeCents cobrado.

Required range: 0 <= x <= 100

feeFixedCents

integer

default:0

Markup fixo em centavos, somado ao percentual.

Required range: x >= 0

payoutFeePercent

number

default:0

Markup percentual sobre cada SAQUE desta subconta (até 2 casas decimais). Campo separado do feePercent de propósito: quem cobra para receber não necessariamente cobra o mesmo para sacar. Zero, o padrão, é saque sem taxa.

Required range: 0 <= x <= 100

payoutFeeFixedCents

integer

default:0

Markup fixo em centavos sobre cada saque, somado ao payoutFeePercent.

Required range: x >= 0

Response

Subconta criada.

subaccountId

string

ID da subconta, prefixo sacc_. Use em cobranças e consultas.

name

string

externalId

string

Seu ID para este cliente. Vazio quando não informado.

active

boolean

Subconta desativada não recebe novas cobranças nem entradas.

balanceCents

integer

Saldo atual do ledger, em centavos.

totalReceivedCents

integer

Total já creditado por vendas, sem descontar transferências.

feePercent

number

Markup percentual da plataforma sobre cada venda desta subconta (0 a 100, até 2 casas). Descontado do líquido ANTES do crédito; a fatia fica na conta principal.

feeFixedCents

integer

Markup fixo em centavos, somado ao percentual.

payoutFeePercent

number

Markup percentual sobre cada SAQUE desta subconta (0 a 100, até 2 casas). A subconta é debitada o valor cheio e o PIX sai pelo líquido: a diferença fica na conta principal.

payoutFeeFixedCents

integer

Markup fixo de saque, em centavos, somado ao percentual.

metadata

string

createdAt

string<date-time>

updatedAt

string<date-time>

Create Subaccount

curl --request POST \
  --url https://api.purincash.com/v1/subaccounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Loja do João",
  "email": "joao@exemplo.com",
  "externalId": "cliente_42",
  "metadata": "{\"plano\":\"pro\"}",
  "feePercent": 5,
  "feeFixedCents": 100,
  "payoutFeePercent": 1,
  "payoutFeeFixedCents": 200
}
'

import requests

url = "https://api.purincash.com/v1/subaccounts"

payload = {
    "name": "Loja do João",
    "email": "joao@exemplo.com",
    "externalId": "cliente_42",
    "metadata": "{\"plano\":\"pro\"}",
    "feePercent": 5,
    "feeFixedCents": 100,
    "payoutFeePercent": 1,
    "payoutFeeFixedCents": 200
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Loja do João',
    email: 'joao@exemplo.com',
    externalId: 'cliente_42',
    metadata: '{"plano":"pro"}',
    feePercent: 5,
    feeFixedCents: 100,
    payoutFeePercent: 1,
    payoutFeeFixedCents: 200
  })
};

fetch('https://api.purincash.com/v1/subaccounts', 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.purincash.com/v1/subaccounts",
  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([
    'name' => 'Loja do João',
    'email' => 'joao@exemplo.com',
    'externalId' => 'cliente_42',
    'metadata' => '{"plano":"pro"}',
    'feePercent' => 5,
    'feeFixedCents' => 100,
    'payoutFeePercent' => 1,
    'payoutFeeFixedCents' => 200
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.purincash.com/v1/subaccounts"

	payload := strings.NewReader("{\n  \"name\": \"Loja do João\",\n  \"email\": \"joao@exemplo.com\",\n  \"externalId\": \"cliente_42\",\n  \"metadata\": \"{\\\"plano\\\":\\\"pro\\\"}\",\n  \"feePercent\": 5,\n  \"feeFixedCents\": 100,\n  \"payoutFeePercent\": 1,\n  \"payoutFeeFixedCents\": 200\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.purincash.com/v1/subaccounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Loja do João\",\n  \"email\": \"joao@exemplo.com\",\n  \"externalId\": \"cliente_42\",\n  \"metadata\": \"{\\\"plano\\\":\\\"pro\\\"}\",\n  \"feePercent\": 5,\n  \"feeFixedCents\": 100,\n  \"payoutFeePercent\": 1,\n  \"payoutFeeFixedCents\": 200\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.purincash.com/v1/subaccounts")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Loja do João\",\n  \"email\": \"joao@exemplo.com\",\n  \"externalId\": \"cliente_42\",\n  \"metadata\": \"{\\\"plano\\\":\\\"pro\\\"}\",\n  \"feePercent\": 5,\n  \"feeFixedCents\": 100,\n  \"payoutFeePercent\": 1,\n  \"payoutFeeFixedCents\": 200\n}"

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

{
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Loja do João",
  "email": "joao@exemplo.com",
  "externalId": "cliente_42",
  "active": true,
  "balanceCents": 0,
  "totalReceivedCents": 0,
  "metadata": "{\"plano\":\"pro\"}",
  "createdAt": "2026-08-04T12:00:00.000Z",
  "updatedAt": "2026-08-04T12:00:00.000Z"
}

{
  "error": "name is required"
}

{
  "error": "A subaccount with this externalId already exists",
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

{
  "error": "Internal error"
}

Visão geral

Pagamentos

Cobranças

Splits

Cartão

Assinaturas

Produtos

Entregas

Subcontas

Carteira e saques

Disputas

Sandbox

Create Subaccount

Authorizations

Body

Response