Skip to main content
POST
/
pay
/
payments
Criar novo pagamento
curl --request POST \
  --url https://api-v2.orbitapay.com.br/pay/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "paymentMethod": "pix",
  "amount": 2,
  "currency": "BRL",
  "paymentDetails": {
    "firstName": "<string>",
    "lastName": "<string>",
    "document": "<string>",
    "documentType": "cpf",
    "email": "[email protected]",
    "phoneNumber": "<string>",
    "address": {
      "address1": "<string>",
      "neighboor": "<string>",
      "zipCode": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "BR",
      "address2": "<string>"
    }
  },
  "items": [
    {
      "tangible": true,
      "title": "<string>",
      "unitPrice": 123,
      "quantity": 2
    }
  ],
  "postbackUrl": "<string>",
  "installments": 2,
  "creditCard": {
    "cardHolderName": "<string>",
    "cardNumber": "<string>",
    "cardMonth": "<string>",
    "cardYear": "<string>",
    "cardCVV": "<string>"
  },
  "splits": [
    {
      "coProducerEmail": "[email protected]",
      "percentage": 49.5
    }
  ],
  "UTMSource": "<string>",
  "UTMMedium": "<string>",
  "UTMCampaign": "<string>",
  "UTMTerm": "<string>",
  "UTMContent": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "initial",
  "amount": 123,
  "netAmount": 123,
  "method": "pix",
  "installments": 1,
  "acquirerTxId": "<string>",
  "systemTxId": "<string>",
  "pixQrCode": "<string>",
  "pixCode": "<string>",
  "billetCode": "<string>",
  "billetUrl": "<string>",
  "endToEnd": "<string>",
  "dateTime": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "approvedAt": "2023-11-07T05:31:56Z",
  "paidAt": "2023-11-07T05:31:56Z",
  "transactionProducts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity": 1,
      "unitPrice": 123,
      "totalPrice": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "product": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "description": "<string>",
        "type": "physical",
        "imageUrl": "<string>",
        "category": "<string>",
        "isActive": true
      }
    }
  ],
  "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

​
📋 Estrutura da Requisição

​
Payload Principal

​
paymentMethod
string
required
Método de pagamento: pix, credit_card ou boleto
​
amount
integer
required
Valor em centavos (ex: 10000 = R$ 100,00)
​
currency
string
required
Moeda (sempre “BRL”)
​
paymentDetails
object
required
Dados do pagador
​
paymentDetails.firstName
string
required
Nome do pagador
​
paymentDetails.lastName
string
required
Sobrenome do pagador
​
paymentDetails.document
string
required
CPF/CNPJ (apenas números)
​
paymentDetails.documentType
string
required
Tipo do documento: cpf ou cnpj
​
paymentDetails.email
string
required
E-mail do pagador
​
paymentDetails.phoneNumber
string
required
Telefone (apenas números, sem formatação)
​
paymentDetails.address
object
required
Endereço completo
​
paymentDetails.address.address1
string
required
Endereço linha 1
​
paymentDetails.address.address2
string
Endereço linha 2 (complemento)
​
paymentDetails.address.neighboor
string
required
Bairro
​
paymentDetails.address.zipCode
string
required
CEP (formato: 01234-567)
​
paymentDetails.address.city
string
required
Cidade
​
paymentDetails.address.state
string
required
Estado (UF)
​
paymentDetails.address.country
string
required
País (sempre “BR”)
​
items
array
Lista de itens/produtos
​
items[].tangible
boolean
Se o item é físico ou digital
​
items[].title
string
Título do item
​
items[].unitPrice
integer
Preço unitário em centavos
​
items[].quantity
integer
Quantidade
​
postbackUrl
string
URL para receber webhooks de notificação
​
splits
array
Lista de splits para divisão de pagamento entre co-produtores
​
splits[].coProducerEmail
string
E-mail do co-produtor
​
splits[].percentage
number
Porcentagem do split (máximo 99%)
​
UTMSource
string
UTM Source para rastreamento de origem (opcional)
​
UTMMedium
string
UTM Medium para rastreamento de mídia (opcional)
​
UTMCampaign
string
UTM Campaign para rastreamento de campanha (opcional)
​
UTMTerm
string
UTM Term para rastreamento de termo (opcional)
​
UTMContent
string
UTM Content para rastreamento de conteúdo (opcional)

​
💰 Splits de Pagamento

O campo splits permite dividir o valor da transação entre co-produtores. Cada split deve conter:
  • coProducerEmail: E-mail do co-produtor
  • percentage: Porcentagem do valor total (máximo 99% por split)
A soma das porcentagens de todos os splits não deve exceder 99%.

​
💳 Campos Específicos para Cartão de Crédito

Quando paymentMethod = "credit_card", os seguintes campos são obrigatórios:
​
installments
integer
required
Número de parcelas (obrigatório para cartão)
​
creditCard
object
required
Dados do cartão de crédito (obrigatório para cartão)
​
creditCard.cardHolderName
string
required
Nome do portador do cartão
​
creditCard.cardNumber
string
required
Número do cartão (apenas números)
​
creditCard.cardMonth
string
required
Mês de expiração (formato: “12”)
​
creditCard.cardYear
string
required
Ano de expiração (formato: “25”)
​
creditCard.cardCVV
string
required
Código de segurança (CVV)

​
📤 Respostas da API

​
PIX - Resposta de Sucesso

{
  "acquirerTxId": "acq-12345",
  "pixQrCode": "00020126580014BR.GOV.BCB.PIX...",
  "pixCode": "00020126580014BR.GOV.BCB.PIX...",
  "transactionId": "14d486a6-7c9d-4e75-919c-b0a2d1bf49ae",
  "status": "pending"
}

​
Boleto - Resposta de Sucesso

{
  "acquirerTxId": "acq-12345",
  "boletoCode": "34191790010104351004791020150008291070026000",
  "transactionId": "14d486a6-7c9d-4e75-919c-b0a2d1bf49ae",
  "status": "pending"
}

​
Cartão de Crédito - Resposta de Sucesso

{
  "acquirerTxId": "acq-12345",
  "systemTxId": "sys-67890",
  "status": "approved",
  "endToEnd": "E12345678202412345678901234567890",
  "transactionId": "14d486a6-7c9d-4e75-919c-b0a2d1bf49ae"
}

​
Exemplo de Resposta de Erro

{
  "error": "Validation failed",
  "message": "creditCard and installments are required when paymentMethod is 'credit_card'",
  "statusCode": 422
}

​
💡 Exemplos Práticos

​
Exemplo 1: Pagamento PIX

curl -X POST https://api-v2.orbitapay.com.br/pay/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sua-api-key" \
  -d '{
    "paymentMethod": "pix",
    "amount": 5000,
    "currency": "BRL",
    "paymentDetails": {
      "firstName": "Maria",
      "lastName": "Santos",
      "document": "12345678901",
      "documentType": "cpf",
      "email": "[email protected]",
      "phoneNumber": "11999999999",
      "address": {
        "address1": "Av. Paulista, 1000",
        "neighboor": "Bela Vista",
        "zipCode": "01310-000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    },
    "items": [{
      "tangible": false,
      "title": "Curso Online",
      "unitPrice": 5000,
      "quantity": 1
    }],
    "postbackUrl": "https://meusite.com/webhook"
  }'

​
Exemplo 2: Pagamento com Cartão

curl -X POST https://api-v2.orbitapay.com.br/pay/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sua-api-key" \
  -d '{
    "paymentMethod": "credit_card",
    "amount": 15000,
    "currency": "BRL",
    "installments": 3,
    "creditCard": {
      "cardHolderName": "João Silva",
      "cardNumber": "4111111111111111",
      "cardMonth": "12",
      "cardYear": "25",
      "cardCVV": "123"
    },
    "paymentDetails": {
      "firstName": "João",
      "lastName": "Silva",
      "document": "12345678901",
      "documentType": "cpf",
      "email": "[email protected]",
      "phoneNumber": "11999999999",
      "address": {
        "address1": "Rua das Flores, 123",
        "neighboor": "Centro",
        "zipCode": "01234-567",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    }
  }'

​
Exemplo 3: Pagamento com Splits

curl -X POST https://api-v2.orbitapay.com.br/pay/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sua-api-key" \
  -d '{
    "paymentMethod": "pix",
    "amount": 10000,
    "currency": "BRL",
    "paymentDetails": {
      "firstName": "Carlos",
      "lastName": "Oliveira",
      "document": "12345678901",
      "documentType": "cpf",
      "email": "[email protected]",
      "phoneNumber": "11999999999",
      "address": {
        "address1": "Av. Brasil, 500",
        "neighboor": "Centro",
        "zipCode": "01234-567",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    },
    "items": [{
      "tangible": false,
      "title": "E-book",
      "unitPrice": 10000,
      "quantity": 1
    }],
    "splits": [{
      "coProducerEmail": "[email protected]",
      "percentage": 30
    }, {
      "coProducerEmail": "[email protected]",
      "percentage": 20
    }],
    "UTMSource": "google",
    "UTMMedium": "cpc",
    "UTMCampaign": "black_friday",
    "UTMTerm": "ebook_vendas",
    "UTMContent": "banner_principal",
    "postbackUrl": "https://meusite.com/webhook"
  }'

Authorizations

​
Authorization
string
header
required

API_KEY gerada dentro da plataforma em https://app-v2.orbitapay.com.br/apps

Body

application/json

Dados do pagamento

​
paymentMethod
enum<string>
required

Método de pagamento

Available options:
pix,
credit_card,
boleto
​
amount
integer
required

Valor em centavos (ex: 10000 = R$ 100,00)

Required range: x >= 1
​
currency
enum<string>
default:BRL
required

Moeda

Available options:
BRL
​
paymentDetails
object
required
​
items
object[]

Lista de itens/produtos

​
postbackUrl
string<uri>

URL para receber webhooks de notificação

​
installments
integer

Número de parcelas (obrigatório para cartão de crédito)

Required range: x >= 1
​
creditCard
object

Dados do cartão de crédito (obrigatório quando paymentMethod = credit_card)

​
splits
object[]

Lista de splits para divisão de pagamento entre co-produtores

​
UTMSource
string | null

UTM Source para rastreamento de origem

​
UTMMedium
string | null

UTM Medium para rastreamento de mídia

​
UTMCampaign
string | null

UTM Campaign para rastreamento de campanha

​
UTMTerm
string | null

UTM Term para rastreamento de termo

​
UTMContent
string | null

UTM Content para rastreamento de conteúdo

Response

Pagamento criado com sucesso

  • Option 1
  • Option 2
  • Option 3

Resposta de pagamento PIX - contém os campos da Transaction com informações específicas de PIX

​
id
string<uuid>

ID único da transação

​
status
enum<string>

Status da transação

Available options:
initial,
pending,
approved,
declined,
refund,
chargeback,
expired,
paid,
cancelled
​
amount
number<decimal>

Valor da transação em centavos

​
netAmount
number<decimal>

Valor líquido da transação em centavos

​
method
enum<string>

Método de pagamento

Available options:
pix,
credit_card,
boleto
​
installments
integer
default:1

Número de parcelas

​
acquirerTxId
string

ID da transação no adquirente

​
systemTxId
string

ID da transação no sistema

​
pixQrCode
string

QR Code PIX para pagamento

​
pixCode
string

Código PIX para pagamento

​
billetCode
string

Código de barras do boleto

​
billetUrl
string<uri>

URL do boleto

​
endToEnd
string

Identificador end-to-end da transação

​
dateTime
string<date-time>

Data e hora de criação da transação

​
expiresAt
string<date-time>

Data e hora de expiração do pagamento

​
approvedAt
string<date-time>

Data e hora de aprovação do pagamento

​
paidAt
string<date-time>

Data e hora de confirmação do pagamento

​
transactionProducts
object[]

Produtos associados à transação

​
transactionId
string<uuid>

ID único da transação (alias para id)