Criar Pagamento

Criar Pagamento

curl --request POST \
  --url https://api-gateway.firebanking.dev/credit-card/v1/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "purchaseValue": 100,
  "installments": 1,
  "externalId": "ext-payment-12345",
  "payment": {
    "chargeType": "FEE_TO_CUSTOMER",
    "capture": true,
    "card": {
      "name": "JOSE DAS NEVES TEST",
      "number": "5383638854408981",
      "expiration": "12/24",
      "securityCode": "220"
    },
    "cardToken": {
      "cardToken": "550e8400-e29b-41d4-a716-446655440000",
      "cvv": "220"
    }
  },
  "purchaseTitle": "Compra de Produto",
  "description": "Descrição da compra",
  "buyer": {
    "name": "João da Silva Teste",
    "document": "11144477735",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01000000",
      "number": "220",
      "complement": "Apto 45"
    }
  },
  "buyerUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "additionalInfo": {
    "customerIp": "192.168.1.100"
  },
  "callbackUrl": "<string>"
}
'

{
  "id": "<string>",
  "status": "<string>",
  "amount": 123,
  "installments": 123,
  "externalId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z"
}

POST

credit-card

payment

Criar Pagamento

curl --request POST \
  --url https://api-gateway.firebanking.dev/credit-card/v1/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "purchaseValue": 100,
  "installments": 1,
  "externalId": "ext-payment-12345",
  "payment": {
    "chargeType": "FEE_TO_CUSTOMER",
    "capture": true,
    "card": {
      "name": "JOSE DAS NEVES TEST",
      "number": "5383638854408981",
      "expiration": "12/24",
      "securityCode": "220"
    },
    "cardToken": {
      "cardToken": "550e8400-e29b-41d4-a716-446655440000",
      "cvv": "220"
    }
  },
  "purchaseTitle": "Compra de Produto",
  "description": "Descrição da compra",
  "buyer": {
    "name": "João da Silva Teste",
    "document": "11144477735",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01000000",
      "number": "220",
      "complement": "Apto 45"
    }
  },
  "buyerUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "additionalInfo": {
    "customerIp": "192.168.1.100"
  },
  "callbackUrl": "<string>"
}
'

{
  "id": "<string>",
  "status": "<string>",
  "amount": 123,
  "installments": 123,
  "externalId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z"
}

Criar um novo pagamento utilizando dados do cartão ou um token de cartão salvo. Este endpoint suporta tanto captura imediata quanto fluxos de pré-autorização.

Métodos de Pagamento

Você pode criar pagamentos usando dois métodos:

Pagamento Direto com Cartão

Use os dados do cartão diretamente para pagamentos únicos

Pagamento com Token

Use um token de cartão salvo para pagamentos recorrentes ou seguros

Tipos de Cobrança

FEE_TO_CUSTOMER: Taxa cobrada do cliente
FEE_TO_SELLER: Taxa cobrada do vendedor

Observações Importantes

Nunca envie card e cardToken na mesma requisição. Use um ou outro.

Todos os valores monetários são especificados em reais no formato decimal. Por exemplo: 100.00, 25.50, 1.23.

Exemplo: Pagamento com Cartão

Exemplo de Requisição

{
  "purchaseValue": 1.23,
  "installments": 1,
  "externalId": "ext-payment-123",
  "purchaseTitle": "Compra de Produto",
  "description": "Descrição da compra",
  "payment": {
    "chargeType": "FEE_TO_CUSTOMER",
    "capture": true,
    "card": {
      "name": "João da Silva",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "João da Silva",
    "document": "25201246010",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01000000",
      "number": "123",
      "complement": "Apto 45"
    }
  },
  "additionalInfo": {
    "customerIp": "192.168.1.100"
  },
  "callbackUrl": "https://example.com/webhook/callback"
}

Exemplo: Pagamento com Token

Exemplo de Requisição

{
  "purchaseValue": 5000,
  "installments": 3,
  "externalId": "ext-payment-token-67890",
  "purchaseTitle": "Pagamento com Token",
  "payment": {
    "chargeType": "FEE_TO_CUSTOMER",
    "capture": true,
    "cardToken": {
      "cardToken": "550e8400-e29b-41d4-a716-446655440000",
      "cvv": "123"
    }
  },
  "buyerUuid": "buyer-uuid-12345"
}

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Body

application/json

purchaseValue

integer

required

Valor da compra em reais

Example:

100

installments

integer

required

Número de parcelas

Intervalo obrigatório: x >= 1

Example:

1

externalId

string

required

ID de referência externa

Example:

"ext-payment-12345"

payment

object

required

Mostrar atributos filhos

payment.chargeType

enum<string>

required

Tipo de cobrança

Opções disponíveis:

FEE_TO_CUSTOMER,

FEE_TO_SELLER

payment.capture

boolean

default:true

Se deve capturar o pagamento imediatamente

payment.card

object

Mostrar atributos filhos

payment.card.name

string

required

Nome do portador do cartão

Example:

"JOSE DAS NEVES TEST"

payment.card.number

string

required

Número do cartão

Example:

"5383638854408981"

payment.card.expiration

string

required

Data de expiração do cartão (MM/AA)

Example:

"12/24"

payment.card.securityCode

string

required

Código de segurança do cartão (CVV)

Example:

"220"

payment.cardToken

object

Mostrar atributos filhos

payment.cardToken.cardToken

string<uuid>

required

Token do cartão salvo

Example:

"550e8400-e29b-41d4-a716-446655440000"

payment.cardToken.cvv

string

Código de segurança do cartão para pagamento com token

Example:

"220"

purchaseTitle

string

Título da compra

Example:

"Compra de Produto"

description

string

Descrição do pagamento

Example:

"Descrição da compra"

buyer

object

Mostrar atributos filhos

buyer.name

string

required

Nome completo do comprador

Example:

"João da Silva Teste"

buyer.document

string

required

Número do documento (CPF/CNPJ)

Example:

"11144477735"

buyer.email

string<email>

required

Endereço de email

Example:

"[email protected]"

buyer.phone

string

required

Número de telefone

Example:

"11999999999"

buyer.countryCode

string

required

Código do país com prefixo +

Example:

"+55"

buyer.address

object

required

Mostrar atributos filhos

buyer.address.country

string

required

Código do país

Example:

"BR"

buyer.address.state

string

required

Código do estado

Example:

"SP"

buyer.address.city

string

required

Nome da cidade

Example:

"São Paulo"

buyer.address.district

string

required

Bairro/distrito

Example:

"Centro"

buyer.address.street

string

required

Nome da rua

Example:

"Rua das Flores"

buyer.address.zipCode

string

required

CEP/código postal

Example:

"01000000"

buyer.address.number

string

required

Número da residência

Example:

"220"

buyer.address.complement

string

Complemento do endereço

Example:

"Apto 45"

buyerUuid

string<uuid>

UUID de comprador existente (alternativa ao objeto buyer)

additionalInfo

object

Mostrar atributos filhos

additionalInfo.customerIp

string<ipv4>

Endereço IP do cliente

Example:

"192.168.1.100"

callbackUrl

string<uri>

URL de callback do webhook

Response

Pagamento criado com sucesso

string

ID do pagamento

status

string

Status do pagamento

amount

integer

Valor do pagamento em reais

installments

integer

Número de parcelas

externalId

string

ID de referência externa

createdAt

string<date-time>

Timestamp de criação

Fluxo de Integração - Cartão de Crédito Listar Pagamentos

⌘I

Visão Geral

Fluxo de Integração

Pagamentos

Tokenização

Assinaturas

Gestão de Compradores

Webhooks

Métodos de Pagamento

Pagamento Direto com Cartão

Pagamento com Token

Tipos de Cobrança

Observações Importantes

Exemplo: Pagamento com Cartão

Exemplo: Pagamento com Token

Authorizations

Body

Response

Visão Geral

Fluxo de Integração

Pagamentos

Tokenização

Assinaturas

Gestão de Compradores

Webhooks

​Métodos de Pagamento

Pagamento Direto com Cartão

Pagamento com Token

​Tipos de Cobrança

​Observações Importantes

​Exemplo: Pagamento com Cartão

​Exemplo: Pagamento com Token

Authorizations

Body

Response

Métodos de Pagamento

Tipos de Cobrança

Observações Importantes

Exemplo: Pagamento com Cartão

Exemplo: Pagamento com Token