curl -X POST https://api.thalbank.com/transactions \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"amount": 5000,
"method": "PIX",
"customer": {
"name": "Maria Silva",
"email": "[email protected]",
"phone": "11999999999",
"documentType": "CPF",
"document": "12345678901"
},
"items": [
{
"title": "Assinatura Mensal",
"amount": 5000,
"quantity": 1,
"tangible": false
}
],
"metadata": { "planId": "premium" }
}'
curl -X POST https://api.thalbank.com/transactions \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
-d '{
"amount": 15000,
"method": "CREDIT_CARD",
"installments": 3,
"customer": {
"name": "Joao Souza",
"email": "[email protected]",
"phone": "21988888888",
"documentType": "CPF",
"document": "98765432100"
},
"items": [
{
"title": "Curso Online",
"amount": 15000,
"quantity": 1,
"tangible": false
}
],
"card": {
"number": "4111111111111111",
"holderName": "JOAO SOUZA",
"expirationMonth": 12,
"expirationYear": 2028,
"cvv": "123"
}
}'
{
"status": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": 5000,
"method": "PIX",
"status": "PENDING",
"pixQrCode": "00020126580014br.gov.bcb.pix...",
"pixQrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
"expiresAt": "2026-03-10T01:00:00.000Z",
"customer": {
"name": "Maria Silva",
"email": "[email protected]"
},
"metadata": { "planId": "premium" },
"createdAt": "2026-03-10T00:00:00.000Z"
}
}
{
"status": true,
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"amount": 15000,
"method": "CREDIT_CARD",
"status": "PAID",
"installments": 3,
"customer": {
"name": "Joao Souza",
"email": "[email protected]"
},
"paidAt": "2026-03-10T00:00:01.000Z",
"createdAt": "2026-03-10T00:00:00.000Z"
}
}
{
"statusCode": 400,
"message": ["amount must not be less than 100"],
"error": "Bad Request"
}
Transactions
Criar Transacao
Cria uma nova transacao de pagamento (PIX, Boleto ou Cartao)
POST
/
transactions
curl -X POST https://api.thalbank.com/transactions \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"amount": 5000,
"method": "PIX",
"customer": {
"name": "Maria Silva",
"email": "[email protected]",
"phone": "11999999999",
"documentType": "CPF",
"document": "12345678901"
},
"items": [
{
"title": "Assinatura Mensal",
"amount": 5000,
"quantity": 1,
"tangible": false
}
],
"metadata": { "planId": "premium" }
}'
curl -X POST https://api.thalbank.com/transactions \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
-d '{
"amount": 15000,
"method": "CREDIT_CARD",
"installments": 3,
"customer": {
"name": "Joao Souza",
"email": "[email protected]",
"phone": "21988888888",
"documentType": "CPF",
"document": "98765432100"
},
"items": [
{
"title": "Curso Online",
"amount": 15000,
"quantity": 1,
"tangible": false
}
],
"card": {
"number": "4111111111111111",
"holderName": "JOAO SOUZA",
"expirationMonth": 12,
"expirationYear": 2028,
"cvv": "123"
}
}'
{
"status": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": 5000,
"method": "PIX",
"status": "PENDING",
"pixQrCode": "00020126580014br.gov.bcb.pix...",
"pixQrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
"expiresAt": "2026-03-10T01:00:00.000Z",
"customer": {
"name": "Maria Silva",
"email": "[email protected]"
},
"metadata": { "planId": "premium" },
"createdAt": "2026-03-10T00:00:00.000Z"
}
}
{
"status": true,
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"amount": 15000,
"method": "CREDIT_CARD",
"status": "PAID",
"installments": 3,
"customer": {
"name": "Joao Souza",
"email": "[email protected]"
},
"paidAt": "2026-03-10T00:00:01.000Z",
"createdAt": "2026-03-10T00:00:00.000Z"
}
}
{
"statusCode": 400,
"message": ["amount must not be less than 100"],
"error": "Bad Request"
}
Descricao
Cria uma transacao de pagamento. Para PIX, retorna QR Code. Para Boleto, retorna codigo de barras. Para Cartao, processa a cobranca imediatamente.Requer header
Idempotency-Key com UUID v4 unico. Veja o guia de idempotencia.Request
Headers
string
required
UUID v4 unico para garantir idempotencia. Exemplo:
550e8400-e29b-41d4-a716-446655440000Body
integer
required
Valor total em centavos. Minimo: 100 (R1,00).Exemplo:R 15,00 =
1500string
required
Metodo de pagamento. Valores:
PIX, BOLETO, CREDIT_CARDobject
required
Dados do comprador.
Show Campos do customer
Show Campos do customer
string
required
Nome completo do comprador.
string
required
Email valido do comprador.
string
required
Telefone com DDD (apenas digitos). Exemplo:
11999999999string
required
Tipo do documento. Valores:
CPF, CNPJstring
required
Numero do documento (apenas digitos). CPF: 11 digitos, CNPJ: 14 digitos.
string
Referencia externa do cliente no seu sistema (max 128 chars).
array
required
object
Dados do cartao. Obrigatorio quando
method = CREDIT_CARD.Show Campos do card
Show Campos do card
string
required
Numero do cartao (apenas digitos, sem espacos).
string
required
Nome impresso no cartao.
integer
required
Mes de validade (1-12).
integer
required
Ano de validade (4 digitos, ex: 2028).
string
required
Codigo de seguranca (3-4 digitos). Nunca armazenado apos autorizacao.
string
CPF/CNPJ do portador do cartao (apenas digitos).
string
Token de cartao previamente tokenizado (substitui number/cvv).
string
ID de sessao do SDK antifraude.
integer
Numero de parcelas (1-12). Obrigatorio para
CREDIT_CARD.object
JSON com dados customizados (max 10 chaves). Exemplo:
{"orderId": "ORD-001"}string
Descricao da transacao.
string
URL alternativa para receber webhook desta transacao (HTTPS).
integer
Tempo de expiracao em segundos (para PIX e Boleto).
curl -X POST https://api.thalbank.com/transactions \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"amount": 5000,
"method": "PIX",
"customer": {
"name": "Maria Silva",
"email": "[email protected]",
"phone": "11999999999",
"documentType": "CPF",
"document": "12345678901"
},
"items": [
{
"title": "Assinatura Mensal",
"amount": 5000,
"quantity": 1,
"tangible": false
}
],
"metadata": { "planId": "premium" }
}'
curl -X POST https://api.thalbank.com/transactions \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
-d '{
"amount": 15000,
"method": "CREDIT_CARD",
"installments": 3,
"customer": {
"name": "Joao Souza",
"email": "[email protected]",
"phone": "21988888888",
"documentType": "CPF",
"document": "98765432100"
},
"items": [
{
"title": "Curso Online",
"amount": 15000,
"quantity": 1,
"tangible": false
}
],
"card": {
"number": "4111111111111111",
"holderName": "JOAO SOUZA",
"expirationMonth": 12,
"expirationYear": 2028,
"cvv": "123"
}
}'
{
"status": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": 5000,
"method": "PIX",
"status": "PENDING",
"pixQrCode": "00020126580014br.gov.bcb.pix...",
"pixQrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
"expiresAt": "2026-03-10T01:00:00.000Z",
"customer": {
"name": "Maria Silva",
"email": "[email protected]"
},
"metadata": { "planId": "premium" },
"createdAt": "2026-03-10T00:00:00.000Z"
}
}
{
"status": true,
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"amount": 15000,
"method": "CREDIT_CARD",
"status": "PAID",
"installments": 3,
"customer": {
"name": "Joao Souza",
"email": "[email protected]"
},
"paidAt": "2026-03-10T00:00:01.000Z",
"createdAt": "2026-03-10T00:00:00.000Z"
}
}
{
"statusCode": 400,
"message": ["amount must not be less than 100"],
"error": "Bad Request"
}
Was this page helpful?