Criar cobranças

Três meios de recebimento estão implementados: Pix, boleto e cartão de crédito. Todos usam JSON, token Bearer e Idempotency-Key.

Como o total é calculado

O valor informado em amount é unitário. O servidor calcula:

Fórmula

subtotal = amount × quantity
total    = subtotal + (subtotal × tax / 100) − (subtotal × discount / 100)

Exemplo: amount=100, quantity=2, tax=5, discount=10 → 200,00 + 10,00 − 20,00 = 190,00. O cálculo é feito com aritmética decimal exata e o resultado é sempre devolvido como string com duas casas ("190.00").

Campos comuns

Campo	Tipo	Descrição
amountobrigatório	número > 0	Valor unitário, com ponto decimal. Máx. 999999999.
quantityobrigatório	inteiro 1–100000	Quantidade de itens.
discountobrigatório	número 0–100	Desconto em %.
taxobrigatório	número 0–100	Imposto em % (obrigatório em Pix e cartão; opcional em boleto).
invoice_noobrigatório	string ≤ 100	Seu número/identificador do pedido.
due_dateobrigatório	data AAAA-MM-DD	Vencimento.
item_nameobrigatório	string ≤ 255	Descrição do item.
notesopcional	string ≤ 500	Observações.

Pix

POST /api/pix/create — exige o método Pix habilitado. Além dos campos comuns: email, document (CPF/CNPJ do pagador) e client (nome do pagador).

Criar cobrança Pix

#!/usr/bin/env bash
# Criar cobrança Pix
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
DUE=$(date -d "+7 days" +%F 2>/dev/null || date -v+7d +%F)  # vencimento daqui a 7 dias
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/pix/create" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY:-$(uuidgen)}" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100,
  "quantity": 2,
  "discount": 10,
  "tax": 5,
  "invoice_no": "PED-1001",
  "due_date": "'"$DUE"'",
  "item_name": "Camiseta",
  "email": "maria@example.com",
  "document": "12345678909",
  "client": "Maria Souza",
  "notes": "Pedido 1001"
}'
echo

// Criar cobrança Pix — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;
const dueDate = new Date(Date.now() + 7 * 864e5).toISOString().slice(0, 10); // vencimento em 7 dias

const body = {
  amount: 100,
  quantity: 2,
  discount: 10,
  tax: 5,
  invoice_no: "PED-1001",
  due_date: dueDate,
  item_name: "Camiseta",
  email: "maria@example.com",
  document: "12345678909",
  client: "Maria Souza",
  notes: "Pedido 1001",
};

const headers = { Authorization: `Bearer ${TOKEN}` };
headers['Content-Type'] = 'application/json';
headers['Idempotency-Key'] = process.env.IDEMPOTENCY_KEY ?? randomUUID(); // reutilize a MESMA chave ao repetir a operação
const res = await fetch(`${BASE}/api/pix/create`, {
  method: 'POST',
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Criar cobrança Pix — Python 3.9+ (pip install requests)
import os, sys, uuid
from datetime import date, timedelta
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]
due_date = (date.today() + timedelta(days=7)).isoformat()  # vencimento em 7 dias

body = {
    "amount": 100,
    "quantity": 2,
    "discount": 10,
    "tax": 5,
    "invoice_no": "PED-1001",
    "due_date": due_date,
    "item_name": "Camiseta",
    "email": "maria@example.com",
    "document": "12345678909",
    "client": "Maria Souza",
    "notes": "Pedido 1001",
}

headers = {"Authorization": f"Bearer {TOKEN}"}
headers["Idempotency-Key"] = os.environ.get("IDEMPOTENCY_KEY", str(uuid.uuid4()))  # reutilize a MESMA chave ao repetir
res = requests.post(BASE + "/api/pix/create", headers=headers, json=body, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Criar cobrança Pix — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");
$dueDate = date('Y-m-d', strtotime('+7 days')); // vencimento em 7 dias

$body = [
    'amount' => 100,
    'quantity' => 2,
    'discount' => 10,
    'tax' => 5,
    'invoice_no' => 'PED-1001',
    'due_date' => $dueDate,
    'item_name' => 'Camiseta',
    'email' => 'maria@example.com',
    'document' => '12345678909',
    'client' => 'Maria Souza',
    'notes' => 'Pedido 1001',
];

$ch = curl_init($base . '/api/pix/create');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
        "Idempotency-Key: " . (getenv("IDEMPOTENCY_KEY") ?: bin2hex(random_bytes(16))), // reutilize a MESMA chave ao repetir
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

Mostre o qrcode e/ou o copy ao pagador e aguarde o webhook invoice.paid.

Boleto

POST /api/boleto/create — além dos comuns: customer (id de um cliente seu, criado antes com POST /api/customer) e, opcionalmente, instructions.

1. Cadastrar o cliente

#!/usr/bin/env bash
# Cadastrar cliente
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/customer" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY:-$(uuidgen)}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Souza",
  "document": "12345678909",
  "document_type": "CPF",
  "zipcode": "01001000",
  "country_id": 30,
  "state": "SP",
  "city": "São Paulo",
  "district": "Sé",
  "street": "Praça da Sé",
  "number": "100",
  "email": "maria@example.com",
  "phone": "1133334444",
  "mobilephone": "11999998888"
}'
echo

// Cadastrar cliente — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;

const body = {
  name: "Maria Souza",
  document: "12345678909",
  document_type: "CPF",
  zipcode: "01001000",
  country_id: 30,
  state: "SP",
  city: "São Paulo",
  district: "Sé",
  street: "Praça da Sé",
  number: "100",
  email: "maria@example.com",
  phone: "1133334444",
  mobilephone: "11999998888",
};

const headers = { Authorization: `Bearer ${TOKEN}` };
headers['Content-Type'] = 'application/json';
headers['Idempotency-Key'] = process.env.IDEMPOTENCY_KEY ?? randomUUID(); // reutilize a MESMA chave ao repetir a operação
const res = await fetch(`${BASE}/api/customer`, {
  method: 'POST',
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Cadastrar cliente — Python 3.9+ (pip install requests)
import os, sys, uuid
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]

body = {
    "name": "Maria Souza",
    "document": "12345678909",
    "document_type": "CPF",
    "zipcode": "01001000",
    "country_id": 30,
    "state": "SP",
    "city": "São Paulo",
    "district": "Sé",
    "street": "Praça da Sé",
    "number": "100",
    "email": "maria@example.com",
    "phone": "1133334444",
    "mobilephone": "11999998888",
}

headers = {"Authorization": f"Bearer {TOKEN}"}
headers["Idempotency-Key"] = os.environ.get("IDEMPOTENCY_KEY", str(uuid.uuid4()))  # reutilize a MESMA chave ao repetir
res = requests.post(BASE + "/api/customer", headers=headers, json=body, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Cadastrar cliente — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");

$body = [
    'name' => 'Maria Souza',
    'document' => '12345678909',
    'document_type' => 'CPF',
    'zipcode' => '01001000',
    'country_id' => 30,
    'state' => 'SP',
    'city' => 'São Paulo',
    'district' => 'Sé',
    'street' => 'Praça da Sé',
    'number' => '100',
    'email' => 'maria@example.com',
    'phone' => '1133334444',
    'mobilephone' => '11999998888',
];

$ch = curl_init($base . '/api/customer');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
        "Idempotency-Key: " . (getenv("IDEMPOTENCY_KEY") ?: bin2hex(random_bytes(16))), // reutilize a MESMA chave ao repetir
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

2. Emitir o boleto

#!/usr/bin/env bash
# Emitir boleto
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
DUE=$(date -d "+7 days" +%F 2>/dev/null || date -v+7d +%F)  # vencimento daqui a 7 dias
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/boleto/create" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY:-$(uuidgen)}" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 150,
  "quantity": 1,
  "discount": 0,
  "tax": 0,
  "invoice_no": "PED-1002",
  "due_date": "'"$DUE"'",
  "item_name": "Plano anual",
  "customer": '"$SHARKPAY_CUSTOMER_ID"',
  "instructions": "Não receber após o vencimento"
}'
echo

// Emitir boleto — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;
const dueDate = new Date(Date.now() + 7 * 864e5).toISOString().slice(0, 10); // vencimento em 7 dias

const body = {
  amount: 150,
  quantity: 1,
  discount: 0,
  tax: 0,
  invoice_no: "PED-1002",
  due_date: dueDate,
  item_name: "Plano anual",
  customer: Number(process.env.SHARKPAY_CUSTOMER_ID),
  instructions: "Não receber após o vencimento",
};

const headers = { Authorization: `Bearer ${TOKEN}` };
headers['Content-Type'] = 'application/json';
headers['Idempotency-Key'] = process.env.IDEMPOTENCY_KEY ?? randomUUID(); // reutilize a MESMA chave ao repetir a operação
const res = await fetch(`${BASE}/api/boleto/create`, {
  method: 'POST',
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Emitir boleto — Python 3.9+ (pip install requests)
import os, sys, uuid
from datetime import date, timedelta
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]
due_date = (date.today() + timedelta(days=7)).isoformat()  # vencimento em 7 dias

body = {
    "amount": 150,
    "quantity": 1,
    "discount": 0,
    "tax": 0,
    "invoice_no": "PED-1002",
    "due_date": due_date,
    "item_name": "Plano anual",
    "customer": int(os.environ["SHARKPAY_CUSTOMER_ID"]),
    "instructions": "Não receber após o vencimento",
}

headers = {"Authorization": f"Bearer {TOKEN}"}
headers["Idempotency-Key"] = os.environ.get("IDEMPOTENCY_KEY", str(uuid.uuid4()))  # reutilize a MESMA chave ao repetir
res = requests.post(BASE + "/api/boleto/create", headers=headers, json=body, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Emitir boleto — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");
$dueDate = date('Y-m-d', strtotime('+7 days')); // vencimento em 7 dias

$body = [
    'amount' => 150,
    'quantity' => 1,
    'discount' => 0,
    'tax' => 0,
    'invoice_no' => 'PED-1002',
    'due_date' => $dueDate,
    'item_name' => 'Plano anual',
    'customer' => (int) getenv("SHARKPAY_CUSTOMER_ID"),
    'instructions' => 'Não receber após o vencimento',
];

$ch = curl_init($base . '/api/boleto/create');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
        "Idempotency-Key: " . (getenv("IDEMPOTENCY_KEY") ?: bin2hex(random_bytes(16))), // reutilize a MESMA chave ao repetir
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

O cliente precisa de country_id (consulte GET /api/country/all) e UF (GET /api/state/all). O CEP pode ser pré-preenchido com GET /api/cep/search/{cep}.

Cartão de crédito

POST /api/creditcard/create autoriza na hora. Campos extras: email, installments (1–24), creditcard_holder, creditcard_number (12–19 dígitos), creditcard_cvv, creditcard_month, creditcard_year (4 dígitos), creditcard_brand.

Cobrar cartão (dados fictícios)

#!/usr/bin/env bash
# Cobrar cartão de crédito
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
DUE=$(date -d "+7 days" +%F 2>/dev/null || date -v+7d +%F)  # vencimento daqui a 7 dias
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/creditcard/create" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY:-$(uuidgen)}" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100,
  "quantity": 1,
  "discount": 0,
  "tax": 0,
  "installments": 3,
  "invoice_no": "PED-1003",
  "due_date": "'"$DUE"'",
  "item_name": "Assinatura",
  "email": "maria@example.com",
  "creditcard_holder": "MARIA SOUZA",
  "creditcard_number": "4111111111111111",
  "creditcard_cvv": "123",
  "creditcard_month": 12,
  "creditcard_year": 2030,
  "creditcard_brand": "Visa"
}'
echo

// Cobrar cartão de crédito — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;
const dueDate = new Date(Date.now() + 7 * 864e5).toISOString().slice(0, 10); // vencimento em 7 dias

const body = {
  amount: 100,
  quantity: 1,
  discount: 0,
  tax: 0,
  installments: 3,
  invoice_no: "PED-1003",
  due_date: dueDate,
  item_name: "Assinatura",
  email: "maria@example.com",
  creditcard_holder: "MARIA SOUZA",
  creditcard_number: "4111111111111111",
  creditcard_cvv: "123",
  creditcard_month: 12,
  creditcard_year: 2030,
  creditcard_brand: "Visa",
};

const headers = { Authorization: `Bearer ${TOKEN}` };
headers['Content-Type'] = 'application/json';
headers['Idempotency-Key'] = process.env.IDEMPOTENCY_KEY ?? randomUUID(); // reutilize a MESMA chave ao repetir a operação
const res = await fetch(`${BASE}/api/creditcard/create`, {
  method: 'POST',
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Cobrar cartão de crédito — Python 3.9+ (pip install requests)
import os, sys, uuid
from datetime import date, timedelta
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]
due_date = (date.today() + timedelta(days=7)).isoformat()  # vencimento em 7 dias

body = {
    "amount": 100,
    "quantity": 1,
    "discount": 0,
    "tax": 0,
    "installments": 3,
    "invoice_no": "PED-1003",
    "due_date": due_date,
    "item_name": "Assinatura",
    "email": "maria@example.com",
    "creditcard_holder": "MARIA SOUZA",
    "creditcard_number": "4111111111111111",
    "creditcard_cvv": "123",
    "creditcard_month": 12,
    "creditcard_year": 2030,
    "creditcard_brand": "Visa",
}

headers = {"Authorization": f"Bearer {TOKEN}"}
headers["Idempotency-Key"] = os.environ.get("IDEMPOTENCY_KEY", str(uuid.uuid4()))  # reutilize a MESMA chave ao repetir
res = requests.post(BASE + "/api/creditcard/create", headers=headers, json=body, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Cobrar cartão de crédito — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");
$dueDate = date('Y-m-d', strtotime('+7 days')); // vencimento em 7 dias

$body = [
    'amount' => 100,
    'quantity' => 1,
    'discount' => 0,
    'tax' => 0,
    'installments' => 3,
    'invoice_no' => 'PED-1003',
    'due_date' => $dueDate,
    'item_name' => 'Assinatura',
    'email' => 'maria@example.com',
    'creditcard_holder' => 'MARIA SOUZA',
    'creditcard_number' => '4111111111111111',
    'creditcard_cvv' => '123',
    'creditcard_month' => 12,
    'creditcard_year' => 2030,
    'creditcard_brand' => 'Visa',
];

$ch = curl_init($base . '/api/creditcard/create');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
        "Idempotency-Key: " . (getenv("IDEMPOTENCY_KEY") ?: bin2hex(random_bytes(16))), // reutilize a MESMA chave ao repetir
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

Se o emissor recusar, a resposta é 400 com {"error": "..."}; nesse caso nenhum valor é creditado.

Repetir com segurança

Falhou por timeout? Repita a mesma requisição com a mesma Idempotency-Key: você recebe a resposta original e nenhuma segunda cobrança é criada. Veja Idempotência.