Forgedocs
Endpoints

Create Charge

Overview

The PUT /cob/:txid endpoint creates an immediate charge (cob) associated with the provided transaction identifier (txid). This endpoint follows the official Central Bank of Brazil specification for PIX charges.

The txid is a unique identifier generated by your system. It must be between 26 and 35 alphanumeric characters.

Endpoint

PUT /cob/{txid}

Authentication

stringobrigatorio

Bearer token obtained via /oauth/token.

Example: Bearer eyJhbGciOiJSUzI1NiIs...

URL Parameters

txidstringobrigatorio

Transaction identifier. Must be unique and contain between 26 and 35 alphanumeric characters [a-zA-Z0-9].

Example: 7978c0c97ea847e78e8849634473c1f1

Request Body

objectobrigatorio

Time control information for the charge.

object

Debtor (payer) data. Can be an individual (CPF) or a legal entity (CNPJ).

objectobrigatorio

Monetary values for the charge.

string

Receiver's PIX key. Can be phone number, email, CPF/CNPJ, or EVP (random key). Maximum 77 characters.

string

Free text for the payer. Maximum 140 characters.

array

List of additional information for the payer.

Request

curl -X PUT https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "calendario": {
      "expiração": 3600
    },
    "devedor": {
      "cpf": "12345678909",
      "nome": "Carlos Oliveira"
    },
    "valor": {
      "original": "123.45",
      "modalidadeAlteração": 0
    },
    "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
    "solicitaçãoPagador": "Serviço realizado.",
    "infoAdicionais": [
      {
        "nome": "Pedido",
        "valor": "#12345"
      }
    ]
  }'
const response = await fetch(
  'https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      calendario: {
        expiração: 3600,
      },
      devedor: {
        cpf: '12345678909',
        nome: 'Carlos Oliveira',
      },
      valor: {
        original: '123.45',
        modalidadeAlteração: 0,
      },
      chave: '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
      solicitaçãoPagador: 'Serviço realizado.',
      infoAdicionais: [
        { nome: 'Pedido', valor: '#12345' },
      ],
    }),
  }
);

const cobrança = await response.json();
import requests

response = requests.put(
    'https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'calendario': {
            'expiração': 3600,
        },
        'devedor': {
            'cpf': '12345678909',
            'nome': 'Carlos Oliveira',
        },
        'valor': {
            'original': '123.45',
            'modalidadeAlteração': 0,
        },
        'chave': '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
        'solicitaçãoPagador': 'Serviço realizado.',
        'infoAdicionais': [
            {'nome': 'Pedido', 'valor': '#12345'},
        ],
    }
)

cobrança = response.json()

Response

{
  "calendario": {
    "criação": "2024-01-15T10:30:00.358Z",
    "expiração": 3600
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisão": 0,
  "loc": {
    "id": 12345,
    "location": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD",
    "tipoCob": "cob"
  },
  "location": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD",
  "status": "ATIVA",
  "devedor": {
    "cpf": "12345678909",
    "nome": "Carlos Oliveira"
  },
  "valor": {
    "original": "123.45",
    "modalidadeAlteração": 0
  },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitaçãoPagador": "Serviço realizado.",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#12345"
    }
  ]
}
{
  "statusCode": 400,
  "message": "CPF deve conter exatamente 11 dígitos numéricos",
  "error": "Bad Request"
}
{
  "statusCode": 409,
  "message": "Cobrança com este txid já existe",
  "error": "Conflict"
}

Response Fields

calendarioobject

txidstring

Transaction identifier provided in the request.

revisãonumber

Charge revision number. Always 0 on creation.

locobject

PIX payload information.

locationstring

PIX copy-and-paste code (same value as loc.location). EMV-format string that can be used for payment.

statusstring

Charge status:

  • ATIVA: Active charge, awaiting payment
  • CONCLUIDA: Payment received
  • REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelled by the receiver
  • REMOVIDA_PELO_PSP: Removed by the PSP

Charge Status

stateDiagram-v2
    [*] --> ATIVA: Charge created
    ATIVA --> CONCLUIDA: Payment received
    ATIVA --> REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelled
    ATIVA --> REMOVIDA_PELO_PSP: Expired/Removed
    CONCLUIDA --> [*]
    REMOVIDA_PELO_USUARIO_RECEBEDOR --> [*]
    REMOVIDA_PELO_PSP --> [*]

Payment Webhook

When the payment is confirmed, you will receive a V2 webhook of type RECEIVE:

{
  "type": "RECEIVE",
  "data": {
    "id": 123,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "123.45",
      "currency": "BRL"
    },
    "endToEndId": "E12345678901234567890123456789012",
    "debtorAccount": {
      "name": "Carlos Oliveira",
      "document": "123.xxx.xxx-xx"
    }
  }
}

Webhooks V2

See the full RECEIVE webhook documentation

Common Errors

CodeErrorSolution
400txid does not match the patternUse 26-35 alphanumeric characters
400Invalid CPF/CNPJCheck the format (numbers only)
400Invalid valueUse the format "123.45" (string with 2 decimals)
401Invalid tokenRenew the access token
409txid already existsUse a different txid

Next Steps

Request Refund

Refund a received PIX

RECEIVE Webhook

Process payment notifications

Activation

How to activate PIX Bacen mode and V2 Webhooks on your account

Request Refund

Request a refund for a received PIX following the BACEN specification

On this page

OverviewEndpointAuthenticationURL ParametersRequest BodyRequestResponseResponse FieldsCharge StatusPayment WebhookCommon ErrorsNext Steps