docs
Endpoints

Create Charge

Overview

The PUT /api/cob/:txid endpoint creates an immediate charge (cob) tied to the given transaction identifier (txid). The payload follows the Central Bank Pix API format and the response returns the PIX copy-and-paste code (EMV) used to generate the QR Code.

The txid is generated by your system and must be unique per account. It comes back in the data.txId field of the RECEIVE webhook, which lets you reconcile the payment with your order.

Endpoint

PUT https://api.fypay.me/api/cob/{txid}

Authentication

stringobrigatorio

Bearer token obtained from POST https://api.fypay.me/api/auth/token. This route does not use a client certificate.

Example: Bearer eyJhbGciOiJSUzI1NiIs...

URL Parameters

txidstringobrigatorio

Transaction identifier. Up to 50 characters and unique per account. We recommend following the Central Bank standard: 26 to 35 alphanumeric characters [a-zA-Z0-9].

Reusing a txid returns 400 with the code PIX_DUPLICATE_EXTERNAL_ID.

Example: 7978c0c97ea847e78e8849634473c1f1

Request Body

object

Charge timing information. If omitted, the default expiration applies.

objectobrigatorio

Monetary values of the charge.

string

Receiver PIX key. Maximum 77 characters. Accepted for compatibility and returned in the response; the charge is always created for the account authenticated by the token.

string

Free text for the payer. Maximum 140 characters.

array

List of additional charge information. Up to 10 items, with a unique nome in each item.

The Central Bank standard devedor field is not accepted today. Sending devedor with cpf/cnpj and nome makes the API respond 400 (PUB_REQUEST_BODY_INVALID). Do not include this field in the body.

Request

curl -X PUT https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "calendario": {
      "expiracao": 3600
    },
    "valor": {
      "original": "123.45"
    },
    "solicitacaoPagador": "Serviço realizado.",
    "infoAdicionais": [
      {
        "nome": "Pedido",
        "valor": "#12345"
      }
    ]
  }'
const response = await fetch(
  'https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      calendario: {
        expiracao: 3600,
      },
      valor: {
        original: '123.45',
      },
      solicitacaoPagador: 'Serviço realizado.',
      infoAdicionais: [
        { nome: 'Pedido', valor: '#12345' },
      ],
    }),
  }
);

const charge = await response.json();
import requests

response = requests.put(
    'https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'calendario': {
            'expiracao': 3600,
        },
        'valor': {
            'original': '123.45',
        },
        'solicitacaoPagador': 'Serviço realizado.',
        'infoAdicionais': [
            {'nome': 'Pedido', 'valor': '#12345'},
        ],
    }
)

charge = response.json()

Response

{
  "calendario": {
    "criacao": "2024-01-15T10:30:00.358Z",
    "expiracao": 3600
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 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",
  "valor": {
    "original": "123.45"
  },
  "chave": "",
  "solicitacaoPagador": "Serviço realizado.",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#12345"
    }
  ]
}
{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/cob/7978c0c97ea847e78e8849634473c1f1",
  "method": "PUT",
  "code": "PUB_REQUEST_BODY_INVALID",
  "message": "Request body validation failed: valor: invalid",
  "userMessage": "Request body is invalid.",
  "details": {
    "violations": {
      "valor": "invalid"
    }
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}
{
  "statusCode": 400,
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "userMessage": "Esta transação já existe no sistema.",
  "details": {
    "externalId": "7978c0c97ea847e78e8849634473c1f1",
    "existingTransactionId": 12345
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

Errors follow the standard API format: statusCode, timestamp, path, method, code, message, userMessage, details (optional) and errorId. Handle them by code, not by the message text.

Response Fields

calendarioobject

txidstring

Transaction identifier given in the URL.

revisaointeger

Charge revision number. Always 0.

locobject

PIX payload information.

locationstring

PIX copy-and-paste code (same value as loc.location). Unlike the Central Bank standard, here it is the EMV payload itself, not a URL.

statusstring

Charge status at creation time:

  • ATIVA: charge created, awaiting payment (normal case)
  • CONCLUIDA: payment already confirmed
  • REMOVIDA_PELO_PSP: the charge failed at the provider
valorobject

The values sent in the request.

chavestring

The key sent in the request, or an empty string if none was sent.

solicitacaoPagadorstring

The text sent in the request, when present.

infoAdicionaisarray

The list sent in the request, when present.

There is no charge lookup endpoint in this format. Payment confirmation arrives through the RECEIVE webhook.

Payment Webhook

When the payment is confirmed, the URLs registered for the cash_in event with the PIX BACEN format receive a RECEIVE webhook (excerpt):

{
  "data": {
    "id": 12345,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "123.45",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202401151030abcdefghijk",
    "debtorAccount": {
      "name": "Carlos Oliveira",
      "document": "12345678909"
    }
  },
  "type": "RECEIVE"
}

RECEIVE Webhook

See the full RECEIVE webhook documentation

Common Errors

HTTP codecodeCauseSolution
400PUB_REQUEST_BODY_INVALIDInvalid body (amount in the wrong format, unknown field such as devedor, size limit)Check details.violations
400PIX_DUPLICATE_EXTERNAL_IDtxid already used on this accountUse a new txid
400PIX_KEY_NOT_FOUNDThe account has no active PIX key to receiveRegister a PIX key on the account
400PROVIDER_EXPIRATION_BELOW_MINIMUMexpiracao below the provider minimumIncrease calendario.expiracao
401Missing, invalid or expired tokenGenerate a new token

Next Steps

Request Refund

Refund a received PIX

RECEIVE Webhook

Process payment notifications

Activation

How to use the PIX Bacen endpoints and enable V2 Webhooks on your account

Request Refund

Request a refund for a received PIX in the Central Bank Pix API format

On this page

OverviewEndpointAuthenticationURL ParametersRequest BodyRequestResponseResponse FieldsPayment WebhookCommon ErrorsNext Steps