> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar transação
> Crie uma transação PIX, boleto ou cartão de crédito
Cria uma transação PIX, boleto ou cartão de crédito.
* **PIX**: Apenas `method` e `amount` são obrigatórios. Retorna o código **Copia e Cola** para pagamento.
* **Boleto**: Requer `method`, `amount` e um cliente vinculado (`customerId` **ou** `customerName`). Retorna código de barras, linha digitável e URL do PDF.
* **Cartão de Crédito**: Requer `method=CreditCard`, `amount` e os dados do cartão (`cardNumber`, `cardHolderName`, `cardExpirationMonth`, `cardExpirationYear`, `cardCvv`) **ou** um `cardToken` obtido via `POST /v1/card-tokenize`.
A imagem do QR Code **não é retornada** pela API. Você deve gerar a imagem no seu frontend usando uma biblioteca de QR Code a partir do campo `copyAndPaste`.
Veja o guia dedicado: [Gerando QR Code do PIX](/api-reference/transactions/qr-code).
Você também pode usar **cartão tokenizado** como forma de pagamento! Consulte o guia dedicado: [Tokenizar cartão](/api-reference/transactions/card-tokenize).
## Split de pagamento via API
Em uma transação **PIX**, envie `splits` para destinar partes do valor líquido a outras organizações. Cada destinatário é identificado pelo seu `splitCode`.
```json theme={null}
{
"method": "Pix",
"amount": 10000,
"currency": "BRL",
"splits": [
{
"splitCode": "550e8400-e29b-41d4-a716-446655440001",
"type": "PERCENTAGE",
"value": 20
},
{
"splitCode": "550e8400-e29b-41d4-a716-446655440002",
"type": "FIXED",
"value": 1000
}
]
}
```
* `type`: use `PERCENTAGE` ou `FIXED`.
* `value` em `PERCENTAGE`: de 1 a 100, com até duas casas decimais.
* `value` em `FIXED`: valor inteiro em centavos.
* O mesmo `splitCode` não pode aparecer duas vezes e a soma das fatias deve caber no saldo disponível projetado do pagamento.
* Split é exclusivo de PIX e depende de estar habilitado para a organização que cria a cobrança.
Quando o PIX for confirmado, cada destinatário recebe seu `shareAmount` em centavos. A resposta de criação e a consulta da transação retornam os splits aplicados para conciliação.
## OpenAPI
````yaml api-reference/openapi.json POST /v1/transactions
openapi: 3.1.1
info:
title: Safefy - Pix Gateway
description: >
## Introducao
**Seu parceiro financeiro de confianca.**
Nos somos a Safefy, uma plataforma especializada em solucoes de pagamento
PIX. Com um servico personalizado e focado nas suas necessidades, estamos
prontos para apoiar sua empresa em cada etapa do processo.
- Conte com o **PIX** como metodo de pagamento rapido, seguro e alinhado com
as melhores praticas de conformidade e prevencao a fraudes.
- Gerencie suas financas de forma simples e acessivel por meio de uma
interface completa e intuitiva.
- Nosso time de suporte esta sempre disponivel para oferecer um atendimento
exclusivo e eficiente.
## Precisa de Ajuda?
A equipe da Safefy quer garantir que sua integracao seja um sucesso. Se
tiver duvidas ou precisar de suporte, nao hesite em nos contatar:
**suporte@safefypay.com.br**
---
## Valores Monetarios
Todos os valores monetarios sao representados em **centavos** (menor unidade
da moeda).
| Valor Real | Valor na API |
|------------|--------------|
| R$ 1,00 | 100 |
| R$ 10,50 | 1050 |
| R$ 100,00 | 10000 |
contact:
name: Suporte Safefy
email: suporte@safefypay.com.br
version: v1
servers:
- url: https://api-payment.safefypay.com.br
description: API de Pagamentos Safefy
security:
- bearerAuth: []
tags:
- name: Autenticacao
description: Endpoints de autenticacao OAuth2
- name: Transacoes
description: Gerenciamento de transacoes PIX
- name: Clientes
description: Gerenciamento de clientes
- name: Saldo
description: Consulta de saldo e volumes
- name: Saques
description: Solicitacao e gerenciamento de saques
- name: Disputas
description: Consulta de disputas e envio de defesa
paths:
/v1/transactions:
post:
tags:
- Transacoes
summary: Criar transacao
description: >-
Cria uma nova transacao PIX ou boleto. Para PIX, apenas method e amount
sao obrigatorios. Para boleto, method, amount e um cliente vinculado sao
obrigatorios (customerId ou customerName). Se customerId nao for enviado
e customerName for informado, a Safefy cria (ou reutiliza) um cliente
automaticamente. Em PIX, o array splits permite distribuir o valor
liquido para outras organizacoes identificadas por splitCode. A imagem
do QR Code não é retornada - utilize uma biblioteca de geração de QR
Code no seu frontend para exibir o codigo visualmente.
operationId: createTransaction
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransactionRequest'
examples:
pix:
summary: Criar transacao PIX
value:
method: Pix
amount: 10000
currency: BRL
description: 'Pagamento do pedido #12345'
externalId: pedido_12345
callbackUrl: https://seusite.com.br/webhook
pixExpirationMinutes: 30
customerName: Joao Silva
customerDocument: '12345678900'
customerEmail: joao@exemplo.com
customerPhone: '5511999998888'
pixWithSplits:
summary: Criar transacao PIX com splits
value:
method: Pix
amount: 10000
currency: BRL
externalId: pedido_com_split_12345
splits:
- splitCode: 550e8400-e29b-41d4-a716-446655440001
type: PERCENTAGE
value: 20
- splitCode: 550e8400-e29b-41d4-a716-446655440002
type: FIXED
value: 1000
boleto:
summary: Criar transacao Boleto
value:
method: Boleto
amount: 15000
currency: BRL
customerId: 550e8400-e29b-41d4-a716-446655440000
description: 'Pagamento do pedido #67890'
boletoDueDate: '2025-02-15'
callbackUrl: https://seusite.com.br/webhook
boletoInlineCustomer:
summary: Criar transacao Boleto (criando cliente automaticamente)
value:
method: Boleto
amount: 15000
currency: BRL
customerName: Joao Silva
customerDocument: '12345678900'
customerEmail: joao@exemplo.com
customerPhone: '5511999998888'
description: 'Pagamento do pedido #67890'
boletoDueDate: '2025-02-15'
callbackUrl: https://seusite.com.br/webhook
responses:
'201':
description: Transacao criada com sucesso
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransactionResponse'
example:
data:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
externalId: pedido_12345
method: Pix
amount: 10000
fee: 150
netAmount: 9850
currency: BRL
status: Pending
description: 'Pagamento do pedido #12345'
environment: Sandbox
expiresAt: '2025-01-15T15:30:00Z'
createdAt: '2025-01-15T15:00:00Z'
completedAt: null
customerId: 550e8400-e29b-41d4-a716-446655440000
splits:
- splitCode: 550e8400-e29b-41d4-a716-446655440001
type: PERCENTAGE
value: 20
shareAmount: 1970
pix:
txId: SAFEFY2025011512345678901234
copyAndPaste: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890...
expiresAt: '2025-01-15T15:30:00Z'
card: null
boleto: null
message: Transacao criada com sucesso.
error: null
'400':
description: Dados invalidos
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransactionResponse'
example:
data: null
message: null
error:
message: O Valor Mínimo da transacao e R$ 1,00 (100 centavos).
code: invalid_amount
'401':
description: Nao autorizado
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransactionResponse'
example:
data: null
message: null
error:
message: Token invalido ou expirado.
code: unauthorized
'500':
description: Erro interno
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransactionResponse'
example:
data: null
message: null
error:
message: Erro ao processar a transacao. Tente novamente.
code: internal_error
components:
schemas:
CreateTransactionRequest:
type: object
required:
- method
- amount
- currency
properties:
method:
type: string
enum:
- Pix
- CreditCard
- Boleto
description: Metodo de pagamento
example: Pix
amount:
type: integer
format: int64
description: 'Valor em centavos (min: 100)'
example: 10000
currency:
type: string
enum:
- BRL
description: Moeda
example: BRL
description:
type: string
nullable: true
description: 'Descricao da transacao (max: 500)'
example: 'Pagamento do pedido #12345'
externalId:
type: string
nullable: true
description: 'ID externo para referencia (max: 100)'
example: pedido_12345
customerId:
type: string
format: uuid
nullable: true
description: >-
ID do cliente cadastrado. Para boleto, informe customerId ou
customerName.
example: 550e8400-e29b-41d4-a716-446655440000
callbackUrl:
type: string
nullable: true
description: URL para receber webhooks
example: https://seusite.com.br/webhook
metadata:
type: string
nullable: true
description: Metadados em JSON
example: '{"orderId": 12345}'
splits:
type: array
nullable: true
description: >-
Regras de split para PIX. Cada split direciona parte do valor
liquido a outra organizacao. Disponivel apenas quando o split
estiver habilitado para a organizacao principal.
items:
$ref: '#/components/schemas/TransactionSplitRequest'
pixExpirationMinutes:
type: integer
nullable: true
description: Tempo de expiracao do PIX (5-1440 min)
example: 30
customerName:
type: string
nullable: true
description: >-
Nome do cliente/pagador. Se customerId nao for enviado e
customerName for informado, a Safefy cria (ou reutiliza) um cliente
e vincula a transacao.
example: Joao Silva
customerDocument:
type: string
nullable: true
description: CPF/CNPJ do cliente/pagador
example: '12345678900'
customerEmail:
type: string
nullable: true
description: >-
Email do cliente/pagador (opcional). Se nao for enviado, a Safefy
gera um email tecnico apenas para viabilizar o processamento.
example: joao@exemplo.com
customerPhone:
type: string
nullable: true
description: >-
Telefone do cliente/pagador com codigo do pais. Aceita com ou sem
'+' no envio e e normalizado para apenas digitos no processamento.
example: '5511999998888'
boletoDueDate:
type: string
format: date
nullable: true
description: >-
Data de vencimento do boleto (YYYY-MM-DD). Obrigatorio para boleto.
Minimo: D+2.
example: '2025-02-15'
boletoInstructions:
type: string
nullable: true
description: Instrucoes do boleto. Opcional.
example: Nao receber apos o vencimento
cardNumber:
type: string
nullable: true
description: Numero do cartao de credito (obrigatorio para method=CreditCard)
example: '4111111111111111'
cardHolderName:
type: string
nullable: true
description: Nome do titular do cartao (obrigatorio para method=CreditCard)
example: JOAO SILVA
cardExpirationMonth:
type: string
nullable: true
description: >-
Mes de expiracao do cartao, dois digitos (obrigatorio para
method=CreditCard)
example: '12'
cardExpirationYear:
type: string
nullable: true
description: >-
Ano de expiracao do cartao, quatro digitos (obrigatorio para
method=CreditCard)
example: '2028'
cardCvv:
type: string
nullable: true
description: >-
Codigo de seguranca do cartao CVV (obrigatorio para
method=CreditCard)
example: '123'
installments:
type: integer
nullable: true
description: Numero de parcelas, de 1 a 12 (obrigatorio para method=CreditCard)
example: 1
cardToken:
type: string
nullable: true
description: >-
Token de cartao obtido via /v1/card-tokenize (alternativa ao envio
de dados brutos do cartao)
example: ct_abc123def456
CreateTransactionResponse:
type: object
properties:
data:
$ref: '#/components/schemas/TransactionData'
message:
type: string
nullable: true
error:
$ref: '#/components/schemas/ApiErrorResponse'
TransactionSplitRequest:
type: object
required:
- splitCode
- type
- value
description: >-
Regra para direcionar uma fatia do valor liquido de uma transacao PIX a
outra organizacao.
properties:
splitCode:
type: string
format: uuid
description: Codigo de referencia da organizacao destinataria.
example: 550e8400-e29b-41d4-a716-446655440001
type:
type: string
enum:
- PERCENTAGE
- FIXED
description: >-
PERCENTAGE divide o valor liquido por percentual; FIXED direciona um
valor fixo em centavos.
example: PERCENTAGE
value:
type: number
description: >-
Em PERCENTAGE, valor de 1 a 100 com no maximo duas casas decimais.
Em FIXED, inteiro positivo em centavos.
example: 20
TransactionData:
type: object
properties:
id:
type: string
format: uuid
description: ID unico da transacao
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
externalId:
type: string
nullable: true
description: ID externo informado
example: pedido_12345
method:
type: string
enum:
- Pix
- CreditCard
- Boleto
description: Metodo de pagamento
example: Pix
amount:
type: integer
format: int64
description: Valor em centavos
example: 10000
fee:
type: integer
format: int64
description: Taxa cobrada em centavos
example: 150
netAmount:
type: integer
format: int64
description: Valor liquido em centavos
example: 9850
currency:
type: string
description: Moeda
example: BRL
status:
type: string
enum:
- Pending
- Processing
- Completed
- Failed
- Refunded
- Expired
- Cancelled
description: Status da transacao
example: Pending
description:
type: string
nullable: true
description: Descricao
example: 'Pagamento do pedido #12345'
environment:
type: string
enum:
- Sandbox
- Production
description: Ambiente
example: Sandbox
expiresAt:
type: string
format: date-time
nullable: true
description: Data de expiracao
example: '2025-01-15T15:30:00Z'
createdAt:
type: string
format: date-time
description: Data de criacao
example: '2025-01-15T15:00:00Z'
completedAt:
type: string
format: date-time
nullable: true
description: Data de confirmacao
example: null
customerId:
type: string
format: uuid
nullable: true
description: ID do cliente
example: 550e8400-e29b-41d4-a716-446655440000
splits:
type: array
nullable: true
description: Splits aplicados a transacao.
items:
$ref: '#/components/schemas/TransactionSplitData'
pix:
$ref: '#/components/schemas/PixTransactionData'
card:
$ref: '#/components/schemas/CardTransactionData'
boleto:
$ref: '#/components/schemas/BoletoTransactionData'
ApiErrorResponse:
type: object
nullable: true
properties:
message:
type: string
description: Mensagem de erro
example: Token invalido ou expirado.
code:
type: string
description: Codigo do erro
example: unauthorized
TransactionSplitData:
type: object
required:
- splitCode
- type
- value
- shareAmount
description: Split efetivamente aplicado a transacao.
properties:
splitCode:
type: string
format: uuid
description: Codigo de referencia da organizacao destinataria.
type:
type: string
enum:
- PERCENTAGE
- FIXED
description: Tipo da regra aplicada.
value:
type: number
description: 'Valor original da regra: percentual ou centavos, conforme o tipo.'
shareAmount:
type: integer
format: int64
description: >-
Fatia calculada em centavos, creditada ao destinatario na
confirmacao do PIX.
example: 1970
PixTransactionData:
type: object
nullable: true
description: >-
Dados do PIX. A imagem do QR Code não é retornada - use uma biblioteca
de QR Code para gerar a imagem a partir do copyAndPaste.
properties:
txId:
type: string
description: ID da transacao PIX (TxId)
example: SAFEFY2025011512345678901234
copyAndPaste:
type: string
description: >-
Codigo PIX Copia e Cola (BR Code). Use este codigo para gerar a
imagem do QR Code no seu frontend.
example: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890...
expiresAt:
type: string
format: date-time
description: Data de expiracao do codigo PIX
example: '2025-01-15T15:30:00Z'
CardTransactionData:
type: object
nullable: true
properties:
lastFour:
type: string
description: Ultimos 4 digitos do cartao
example: '1234'
brand:
type: string
description: Bandeira do cartao
example: Visa
installments:
type: integer
description: Numero de parcelas
example: 1
authorizationCode:
type: string
description: Codigo de autorizacao
example: ABC123
BoletoTransactionData:
type: object
nullable: true
properties:
barcode:
type: string
description: Codigo de barras
example: 23793.38128 60000.000003 00000.000400 1 84340000010000
digitableLine:
type: string
description: Linha digitavel
example: 23793.38128 60000.000003 00000.000400 1 84340000010000
pdfUrl:
type: string
description: URL do PDF do boleto
example: https://api.safefypay.com.br/boleto/123456.pdf
dueDate:
type: string
format: date-time
description: Data de vencimento
example: '2025-01-20T00:00:00Z'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Token JWT obtido via /v1/auth/token
````