2rPay Pagamentos — API

Receba pagamentos por PIX e Boleto Bancário de forma simples e segura, integrando a 2rPay ao seu site, app ou ERP.

Esta é a documentação oficial da API REST da 2rPay. Todas as requisições e respostas usam o formato application/json. A especificação completa, em formato OpenAPI 3, está disponível em /openapi.json — pronta para ser importada em ferramentas como Postman, Insomnia ou consumida por agentes/IAs.

Autenticação

Todas as requisições utilizam o campo merchant_key, enviado no corpo (body) da requisição. Você encontra a sua chave na área de Merchants do painel.

Mantenha sua merchant_key em segredo. Ela identifica a sua conta e autoriza a criação de cobranças. Nunca a exponha no front-end.

Base URL

Todos os endpoints são relativos à URL base abaixo:

https://www.2rpay.com.br/api

Exemplo de chamada completa: https://www.2rpay.com.br/api/v1/transaction

Formato de valores

Todos os valores monetários são inteiros em centavos. Por exemplo, 500 equivale a R$ 5,00 e 099 equivale a R$ 0,99. Datas seguem o padrão ISO 8601 (ex.: 2022-02-01T23:59:59).

Webhooks (postback)

Sempre que o status de uma transação muda — por exemplo, de processing para paid — a 2rPay envia uma notificação HTTP POST para a postback_url informada na criação da transação.

Como configurar

Ao criar uma transação (endpoint Criar transação), envie o campo opcional postback_url no corpo da requisição com a URL do seu servidor que receberá as notificações:

{
  "merchant_key": "sua_merchant_key",
  "payment_method": "pix",
  "amount": "500",
  "postback_url": "https://seusite.com.br/webhook/2rpay",
  "customer": { ... },
  "pix": { "expiration_days": 1 }
}

Como funciona

Você cria a transação informando a postback_url.
Quando o pagamento for confirmado (status muda para paid), a 2rPay faz um POST para essa URL.
Seu servidor deve responder com HTTP 200 para confirmar o recebimento. Caso contrário, novas tentativas serão realizadas.

Payload enviado

O corpo da requisição POST enviada ao seu servidor é um JSON com o objeto completo da transação (mesmo formato do endpoint de consulta — payloadTransaction), incluindo:

Campo	Descrição
id	Identificador da transação
reference	Referência da transação
amount	Valor em centavos
status	Novo status (ex.: `paid`)
pix	Dados do PIX (se aplicável)
billet	Dados do boleto (se aplicável)
metadata	Campos personalizados enviados na criação
postback_url	URL de callback configurada
created_at	Data/hora de criação da transação

Exemplo de payload recebido no seu servidor

{
  "id": 13456465,
  "reference": "000AAA111",
  "amount": "500",
  "tax": "099",
  "status": "paid",
  "pix": {
    "id": "aa00aa2a-b1ff-4e62-a9090-317f43027111",
    "code": "00020126890064BR.GOV.BCB.PIX...",
    "qrcode": "https://cdn.2rpay.com.br/qrcodes/2022/01/abc123.png",
    "expiration": "2022-02-01T23:59:59.000",
    "additional_info": null
  },
  "metadata": { "order_id": "12345" },
  "postback_url": "https://seusite.com.br/webhook/2rpay",
  "created_at": "2022-01-31T10:30:00.000"
}

Boas práticas

Use HTTPS — garante a segurança dos dados transmitidos.
Responda rápido — retorne HTTP 200 o mais rápido possível. Processe a lógica de negócio de forma assíncrona se necessário.
Valide o conteúdo — confirme que o id e amount correspondem a uma transação válida no seu sistema antes de liberar o produto/serviço.
Idempotência — seu endpoint pode receber a mesma notificação mais de uma vez. Trate duplicatas verificando se o status já foi processado.

Códigos de erro

400Bad Request — dados enviados de forma incorreta ou fora do padrão.

401Forbidden — sem autorização suficiente ou recurso não encontrado.

Endpoints

Criar transação

POST /v1/transaction

Cria uma transação de cobrança, que pode ser por PIX ou por Boleto Bancário.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
merchant_key	string	obrigatório	Merchant Key da conta
payment_method	PaymentMethod	obrigatório
billet	CreateBillet	opcional	Obrigatório caso payment_method = billet
pix	CreatePix	opcional	Obrigatório caso payment_method = pix
amount	string	obrigatório	Valor da transação em centavos (500 = R$ 5,00)
metadata	Metadata	opcional
customer	Customer	obrigatório
postback_url	string	opcional	URL de callback (webhook) para receber notificações automáticas quando o status da transação mudar. Deve ser uma URL pública acessível via HTTPS.

Exemplo de requisição

curl -X POST "https://www.2rpay.com.br/api/v1/transaction" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "q3sQ6K7ajGQaKXwlf9SOqtYDsl6WweRxL",
    "payment_method": "billet",
    "billet": {
        "bank": "si",
        "expiration_days": 1
    },
    "pix": {
        "expiration_days": 1
    },
    "amount": "500",
    "metadata": {
        "meu_campo": "meu_valor",
        "outro_campo": "outro_valor"
    },
    "customer": {
        "firstName": "João",
        "lastName": "Silva",
        "email": "[email protected]",
        "phoneNumber": "99 99999-9999",
        "documentType": "cpf",
        "documentNumber": "58858573005",
        "zipCode": "14401269",
        "address": "R. Prof. Laerte Barbosa Cintra",
        "number_home": "661",
        "complement": "",
        "neighborhood": "Res. Baldassari",
        "city": "Franca",
        "state": "SP",
        "ipAddress": "200.150.100.50"
    },
    "postback_url": "https://seusite.com.br/webhook/2rpay"
}'

Respostas

200 Transação criada com sucesso

400 Dados enviados de forma incorreta ou fora do padrão

401 Sem autorização suficiente para acessar o recurso

Exemplo de resposta 200

{
    "id": 13456465,
    "reference": "000AAA111",
    "amount": "500",
    "tax": "099",
    "status": "paid",
    "pix": {
        "id": "aa00aa2a-b1ff-4e62-a9090-317f43027111",
        "code": "00020126890064BR.GOV.BCB.PIX2567api-pix.bancoabs2.com.br/spi/v2/143bb3d8-2490-48b6-80ae-bfd5753f434b52040000530398654045.005802BR5920Repasses Financeiros6014Belo Horizonte61083038040362070503***630412BD",
        "qrcode": "https://cdn.2rpay.com.br/qrcodes/2022/01/2b98c3c2b9e944d1573a9f31d64e8a96c63bdb52d.png",
        "expiration": "2020-07-31T20:14:00.000",
        "additional_info": "string"
    },
    "billet": {
        "id": "00034a77630900162701",
        "code": "0819009009034776300000162701171188660000000500",
        "link": "https://cdn.2rpay.com.br/billet/2022/01/bb/3efe1357a99d453fffd6a00576994afd746e523e.pdf",
        "expiration": "2020-07-31T20:14:00.000",
        "additional_info": "string"
    },
    "metadata": {
        "meu_campo": "meu_valor",
        "outro_campo": "outro_valor"
    },
    "created_at": "2020-07-31T20:14:00.000",
    "postback_url": "https://dominio.com.br/callback"
}

Consultar transação

GET /v1/transaction/{transaction_id}

Consulta os dados de uma transação pelo seu identificador.

Parâmetros

Nome	Local	Tipo	Obrigatório	Descrição
transaction_id	path	string	obrigatório	Identificador da transação

Exemplo de requisição

curl -X GET "https://www.2rpay.com.br/api/v1/transaction/13564855"

Respostas

200 Sucesso

401 Transação não encontrada

Exemplo de resposta 200

{
    "id": 13456465,
    "reference": "000AAA111",
    "amount": "500",
    "tax": "099",
    "status": "paid",
    "pix": {
        "id": "aa00aa2a-b1ff-4e62-a9090-317f43027111",
        "code": "00020126890064BR.GOV.BCB.PIX2567api-pix.bancoabs2.com.br/spi/v2/143bb3d8-2490-48b6-80ae-bfd5753f434b52040000530398654045.005802BR5920Repasses Financeiros6014Belo Horizonte61083038040362070503***630412BD",
        "qrcode": "https://cdn.2rpay.com.br/qrcodes/2022/01/2b98c3c2b9e944d1573a9f31d64e8a96c63bdb52d.png",
        "expiration": "2020-07-31T20:14:00.000",
        "additional_info": "string"
    },
    "billet": {
        "id": "00034a77630900162701",
        "code": "0819009009034776300000162701171188660000000500",
        "link": "https://cdn.2rpay.com.br/billet/2022/01/bb/3efe1357a99d453fffd6a00576994afd746e523e.pdf",
        "expiration": "2020-07-31T20:14:00.000",
        "additional_info": "string"
    },
    "metadata": {
        "meu_campo": "meu_valor",
        "outro_campo": "outro_valor"
    },
    "created_at": "2020-07-31T20:14:00.000",
    "postback_url": "https://dominio.com.br/callback"
}

Listar transações

GET /v1/transactions

Lista as transações dentro de um intervalo de datas.

Parâmetros

Nome	Local	Tipo	Obrigatório	Descrição
date_start	query	string	obrigatório	Data/hora inicial do período (ISO 8601)
date_end	query	string	obrigatório	Data/hora final do período (ISO 8601)

Exemplo de requisição

curl -X GET "https://www.2rpay.com.br/api/v1/transactions?date_start=2022-02-01T00%3A00%3A00&date_end=2022-02-01T23%3A59%3A59"

Respostas

200 Sucesso

401 Transação não encontrada

Exemplo de resposta 200

[
    {
        "id": 13456465,
        "reference": "000AAA111",
        "amount": "500",
        "tax": "099",
        "status": "paid",
        "pix": {
            "id": "aa00aa2a-b1ff-4e62-a9090-317f43027111",
            "code": "00020126890064BR.GOV.BCB.PIX2567api-pix.bancoabs2.com.br/spi/v2/143bb3d8-2490-48b6-80ae-bfd5753f434b52040000530398654045.005802BR5920Repasses Financeiros6014Belo Horizonte61083038040362070503***630412BD",
            "qrcode": "https://cdn.2rpay.com.br/qrcodes/2022/01/2b98c3c2b9e944d1573a9f31d64e8a96c63bdb52d.png",
            "expiration": "2020-07-31T20:14:00.000",
            "additional_info": "string"
        },
        "billet": {
            "id": "00034a77630900162701",
            "code": "0819009009034776300000162701171188660000000500",
            "link": "https://cdn.2rpay.com.br/billet/2022/01/bb/3efe1357a99d453fffd6a00576994afd746e523e.pdf",
            "expiration": "2020-07-31T20:14:00.000",
            "additional_info": "string"
        },
        "metadata": {
            "meu_campo": "meu_valor",
            "outro_campo": "outro_valor"
        },
        "created_at": "2020-07-31T20:14:00.000",
        "postback_url": "https://dominio.com.br/callback"
    }
]

Listar histórico

GET /v1/extracts

Lista o histórico (extrato) de movimentações dentro de um intervalo de datas.

Parâmetros

Nome	Local	Tipo	Obrigatório	Descrição
date_start	query	string	obrigatório	Data/hora inicial do período (ISO 8601)
date_end	query	string	obrigatório	Data/hora final do período (ISO 8601)

Exemplo de requisição

curl -X GET "https://www.2rpay.com.br/api/v1/extracts?date_start=2022-02-01T00%3A00%3A00&date_end=2022-02-01T23%3A59%3A59"

Respostas

200 Sucesso

401 Histórico não encontrado

Exemplo de resposta 200

[
    {
        "id": 13456465,
        "amount": "500",
        "tax": "099",
        "total": "401",
        "balance": "1099",
        "details": "Recebimento PIX",
        "reference": "000AAA111",
        "created_at": "2020-07-31T20:14:00.000"
    }
]

Cancelar transação

POST /v1/transaction/cancel

Cancela uma transação que ainda não foi liquidada.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
merchant_key	string	obrigatório	Merchant Key da conta
transaction_id	string	obrigatório	Id da transação

Exemplo de requisição

curl -X POST "https://www.2rpay.com.br/api/v1/transaction/cancel" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "w764tNdWUD7BPtd13ILusr0M0DN5u7Tx",
    "transaction_id": "120301"
}'

Respostas

200 Sucesso

401 Transação não encontrada

Exemplo de resposta 200

{
    "id": 13456465,
    "reference": "000AAA111",
    "amount": "500",
    "tax": "099",
    "status": "paid",
    "pix": {
        "id": "aa00aa2a-b1ff-4e62-a9090-317f43027111",
        "code": "00020126890064BR.GOV.BCB.PIX2567api-pix.bancoabs2.com.br/spi/v2/143bb3d8-2490-48b6-80ae-bfd5753f434b52040000530398654045.005802BR5920Repasses Financeiros6014Belo Horizonte61083038040362070503***630412BD",
        "qrcode": "https://cdn.2rpay.com.br/qrcodes/2022/01/2b98c3c2b9e944d1573a9f31d64e8a96c63bdb52d.png",
        "expiration": "2020-07-31T20:14:00.000",
        "additional_info": "string"
    },
    "billet": {
        "id": "00034a77630900162701",
        "code": "0819009009034776300000162701171188660000000500",
        "link": "https://cdn.2rpay.com.br/billet/2022/01/bb/3efe1357a99d453fffd6a00576994afd746e523e.pdf",
        "expiration": "2020-07-31T20:14:00.000",
        "additional_info": "string"
    },
    "metadata": {
        "meu_campo": "meu_valor",
        "outro_campo": "outro_valor"
    },
    "created_at": "2020-07-31T20:14:00.000",
    "postback_url": "https://dominio.com.br/callback"
}

Objetos (Schemas)

Estruturas de dados reutilizadas pelos endpoints acima.

Status

Status da transação

Valores possíveis:

paidliquidateprocessingreturnedcancel

PaymentMethod

Método de pagamento da transação

Valores possíveis:

billetpix

CreatePix

Campo	Tipo	Obrigatório	Descrição
expiration_days	integer	obrigatório	Quantidade de dias para expirar

CreateBillet

Campo	Tipo	Obrigatório	Descrição
bank	string	obrigatório	Banco emissor (si = Sicredi \| bb = Banco do Brasil)
expiration_days	integer	obrigatório	Quantidade de dias para expirar

Customer

Campo	Tipo	Obrigatório	Descrição
firstName	string	obrigatório	Nome do cliente
lastName	string	obrigatório	Sobrenome do cliente
email	string	obrigatório	E-mail do cliente
phoneNumber	string	obrigatório	Número do telefone
documentType	string	obrigatório	Tipo de documento: cpf ou cnpj
documentNumber	string	obrigatório	Número do documento
zipCode	string	obrigatório	CEP do cliente
address	string	obrigatório	Endereço
number_home	string	obrigatório	Número do endereço
complement	string	opcional	Complemento do endereço
neighborhood	string	obrigatório	Bairro do cliente
city	string	obrigatório	Cidade do cliente
state	string	obrigatório	Estado do cliente (UF)
ipAddress	string	obrigatório	Endereço IP de acesso do cliente

Pix

Objeto que representa as informações da cobrança via PIX

Campo	Tipo	Obrigatório	Descrição
id	string	obrigatório	Id do PIX
code	string	obrigatório	Código copia-e-cola do PIX
qrcode	string	obrigatório	Link da imagem do QR Code do PIX
expiration	string	obrigatório	Data de expiração do PIX
additional_info	string	opcional	Reservado para informações adicionais

Billet

Objeto que representa as informações da cobrança via Boleto Bancário

Campo	Tipo	Obrigatório	Descrição
id	string	obrigatório	Id do boleto
code	string	obrigatório	Código de barras do boleto bancário
link	string	obrigatório	Link do PDF do boleto bancário
expiration	string	obrigatório	Data de expiração do boleto bancário
additional_info	string	opcional	Reservado para informações adicionais

Metadata

Campos personalizados livres associados à transação

Campo	Tipo	Obrigatório	Descrição
meu_campo	string	opcional
outro_campo	string	opcional

payloadTransaction

Campo	Tipo	Obrigatório	Descrição
id	integer	obrigatório	Id da transação
reference	string	obrigatório	Referência da transação
amount	string	obrigatório	Valor da transação em centavos (500 = R$ 5,00)
tax	string	obrigatório	Valor da tarifa em centavos (099 = R$ 0,99)
status	Status	obrigatório
pix	Pix	opcional
billet	Billet	opcional
metadata	Metadata	opcional
created_at	string	obrigatório	Data/hora da transação
postback_url	string	opcional	URL de callback utilizada para enviar as notificações de mudança de status

payloadExtract

Campo	Tipo	Obrigatório	Descrição
id	integer	obrigatório	Id do histórico
amount	string	obrigatório	Valor em centavos (500 = R$ 5,00)
tax	string	obrigatório	Valor da tarifa em centavos (099 = R$ 0,99)
total	string	obrigatório	Valor total do histórico em centavos (401 = R$ 4,01)
balance	string	obrigatório	Saldo após a movimentação em centavos (1099 = R$ 10,99)
details	string	obrigatório	Detalhes do histórico
reference	string	obrigatório	Referência do histórico
created_at	string	obrigatório	Data/hora da movimentação

payloadCreateTransaction

Campo	Tipo	Obrigatório	Descrição
merchant_key	string	obrigatório	Merchant Key da conta
payment_method	PaymentMethod	obrigatório
billet	CreateBillet	opcional	Obrigatório caso payment_method = billet
pix	CreatePix	opcional	Obrigatório caso payment_method = pix
amount	string	obrigatório	Valor da transação em centavos (500 = R$ 5,00)
metadata	Metadata	opcional
customer	Customer	obrigatório
postback_url	string	opcional	URL de callback (webhook) para receber notificações automáticas quando o status da transação mudar. Deve ser uma URL pública acessível via HTTPS.

Precisa de ajuda com a integração? Fale com a gente em [email protected] ou pela página de contato.