{
  "openapi": "3.0.3",
  "info": {
    "title": "2rPay Pagamentos — API",
    "description": "API REST para receber pagamentos por PIX e Boleto Bancário de forma simples e segura.\n\n## Autenticação\nTodas as requisições utilizam o campo `merchant_key`, enviado no corpo (body) da requisição. Você encontra a sua chave na área de Merchants: https://2rpay.com.br/user/merchant\n\n## Formato de valores\nTodos os valores monetários são inteiros em centavos. Exemplo: `500` equivale a R$ 5,00.\n\n## Webhooks (postback)\nQuando 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.\n\n### Como funciona\n1. Ao criar uma transação, envie o campo `postback_url` com a URL do seu servidor que receberá as notificações.\n2. Quando o pagamento for confirmado, a 2rPay faz um POST para essa URL com o objeto completo da transação (mesmo formato do endpoint de consulta).\n3. Seu servidor deve responder com HTTP `200` para confirmar o recebimento. Caso contrário, novas tentativas serão realizadas.\n\n### Payload enviado\nO corpo da requisição POST é um JSON com os campos do objeto `payloadTransaction`, incluindo `id`, `reference`, `amount`, `status`, `pix`, `billet`, `metadata`, `postback_url` e `created_at`.\n\n### Boas práticas\n- Use HTTPS para garantir a segurança dos dados.\n- Valide o conteúdo recebido antes de processar.\n- Retorne HTTP 200 o mais rápido possível; processe a lógica de negócio de forma assíncrona se necessário.\n\n## Códigos de erro\n- **400 — Bad Request**: dados enviados de forma incorreta ou fora do padrão.\n- **401 — Forbidden**: sem autorização suficiente ou recurso não encontrado.",
    "version": "1.2.0",
    "contact": {
      "name": "2rPay Pagamentos",
      "url": "https://www.2rpay.com.br",
      "email": "contato@2rpay.com.br"
    }
  },
  "servers": [
    {
      "url": "https://www.2rpay.com.br/api",
      "description": "Produção"
    }
  ],
  "tags": [
    {
      "name": "Transações",
      "description": "Criação, consulta e cancelamento de cobranças por PIX e Boleto."
    },
    {
      "name": "Histórico",
      "description": "Consulta do extrato de movimentações da conta."
    }
  ],
  "paths": {
    "/v1/transaction": {
      "post": {
        "tags": ["Transações"],
        "summary": "Criar transação",
        "operationId": "createTransaction",
        "description": "Cria uma transação de cobrança, que pode ser por PIX ou por Boleto Bancário.",
        "requestBody": {
          "required": true,
          "description": "Dados para a criação da transação.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/payloadCreateTransaction"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transação criada com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/payloadTransaction"
                }
              }
            }
          },
          "400": {
            "description": "Dados enviados de forma incorreta ou fora do padrão"
          },
          "401": {
            "description": "Sem autorização suficiente para acessar o recurso"
          }
        }
      }
    },
    "/v1/transaction/{transaction_id}": {
      "get": {
        "tags": ["Transações"],
        "summary": "Consultar transação",
        "operationId": "getTransaction",
        "description": "Consulta os dados de uma transação pelo seu identificador.",
        "parameters": [
          {
            "name": "transaction_id",
            "in": "path",
            "description": "Identificador da transação",
            "schema": {
              "type": "string"
            },
            "example": "13564855",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/payloadTransaction"
                }
              }
            }
          },
          "401": {
            "description": "Transação não encontrada"
          }
        }
      }
    },
    "/v1/transactions": {
      "get": {
        "tags": ["Transações"],
        "summary": "Listar transações",
        "operationId": "listTransactions",
        "description": "Lista as transações dentro de um intervalo de datas.",
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "description": "Data/hora inicial do período (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2022-02-01T00:00:00",
            "required": true
          },
          {
            "name": "date_end",
            "in": "query",
            "description": "Data/hora final do período (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2022-02-01T23:59:59",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/payloadTransaction"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Transação não encontrada"
          }
        }
      }
    },
    "/v1/extracts": {
      "get": {
        "tags": ["Histórico"],
        "summary": "Listar histórico",
        "operationId": "listExtracts",
        "description": "Lista o histórico (extrato) de movimentações dentro de um intervalo de datas.",
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "description": "Data/hora inicial do período (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2022-02-01T00:00:00",
            "required": true
          },
          {
            "name": "date_end",
            "in": "query",
            "description": "Data/hora final do período (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2022-02-01T23:59:59",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/payloadExtract"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Histórico não encontrado"
          }
        }
      }
    },
    "/v1/transaction/cancel": {
      "post": {
        "tags": ["Transações"],
        "summary": "Cancelar transação",
        "operationId": "cancelTransaction",
        "description": "Cancela uma transação que ainda não foi liquidada.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "merchant_key",
                  "transaction_id"
                ],
                "type": "object",
                "properties": {
                  "merchant_key": {
                    "type": "string",
                    "description": "Merchant Key da conta",
                    "example": "w764tNdWUD7BPtd13ILusr0M0DN5u7Tx"
                  },
                  "transaction_id": {
                    "type": "string",
                    "description": "Id da transação",
                    "example": "120301"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/payloadTransaction"
                }
              }
            }
          },
          "401": {
            "description": "Transação não encontrada"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Status": {
        "enum": [
          "paid",
          "liquidate",
          "processing",
          "returned",
          "cancel"
        ],
        "description": "Status da transação",
        "type": "string"
      },
      "PaymentMethod": {
        "enum": [
          "billet",
          "pix"
        ],
        "description": "Método de pagamento da transação",
        "type": "string"
      },
      "CreatePix": {
        "required": [
          "expiration_days"
        ],
        "type": "object",
        "properties": {
          "expiration_days": {
            "type": "integer",
            "description": "Quantidade de dias para expirar",
            "example": 1
          }
        }
      },
      "CreateBillet": {
        "required": [
          "bank",
          "expiration_days"
        ],
        "type": "object",
        "properties": {
          "bank": {
            "type": "string",
            "description": "Banco emissor (si = Sicredi | bb = Banco do Brasil)",
            "example": "si"
          },
          "expiration_days": {
            "type": "integer",
            "description": "Quantidade de dias para expirar",
            "example": 1
          }
        }
      },
      "Customer": {
        "required": [
          "firstName",
          "lastName",
          "email",
          "phoneNumber",
          "documentType",
          "documentNumber",
          "zipCode",
          "address",
          "number_home",
          "neighborhood",
          "city",
          "state",
          "ipAddress"
        ],
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Nome do cliente",
            "example": "João"
          },
          "lastName": {
            "type": "string",
            "description": "Sobrenome do cliente",
            "example": "Silva"
          },
          "email": {
            "type": "string",
            "description": "E-mail do cliente",
            "example": "exemplo@dominio.com.br"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Número do telefone",
            "example": "99 99999-9999"
          },
          "documentType": {
            "type": "string",
            "description": "Tipo de documento: cpf ou cnpj",
            "example": "cpf"
          },
          "documentNumber": {
            "type": "string",
            "description": "Número do documento",
            "example": "58858573005"
          },
          "zipCode": {
            "type": "string",
            "description": "CEP do cliente",
            "example": "14401269"
          },
          "address": {
            "type": "string",
            "description": "Endereço",
            "example": "R. Prof. Laerte Barbosa Cintra"
          },
          "number_home": {
            "type": "string",
            "description": "Número do endereço",
            "example": "661"
          },
          "complement": {
            "type": "string",
            "description": "Complemento do endereço",
            "example": "",
            "nullable": true
          },
          "neighborhood": {
            "type": "string",
            "description": "Bairro do cliente",
            "example": "Res. Baldassari"
          },
          "city": {
            "type": "string",
            "description": "Cidade do cliente",
            "example": "Franca"
          },
          "state": {
            "type": "string",
            "description": "Estado do cliente (UF)",
            "example": "SP"
          },
          "ipAddress": {
            "type": "string",
            "description": "Endereço IP de acesso do cliente",
            "example": "200.150.100.50"
          }
        }
      },
      "Pix": {
        "required": [
          "id",
          "code",
          "qrcode",
          "expiration"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Id do PIX",
            "example": "aa00aa2a-b1ff-4e62-a9090-317f43027111"
          },
          "code": {
            "type": "string",
            "description": "Código copia-e-cola do PIX",
            "example": "00020126890064BR.GOV.BCB.PIX2567api-pix.bancoabs2.com.br/spi/v2/143bb3d8-2490-48b6-80ae-bfd5753f434b52040000530398654045.005802BR5920Repasses Financeiros6014Belo Horizonte61083038040362070503***630412BD"
          },
          "qrcode": {
            "type": "string",
            "format": "uri",
            "description": "Link da imagem do QR Code do PIX",
            "example": "https://cdn.2rpay.com.br/qrcodes/2022/01/2b98c3c2b9e944d1573a9f31d64e8a96c63bdb52d.png"
          },
          "expiration": {
            "type": "string",
            "description": "Data de expiração do PIX",
            "format": "date-time",
            "example": "2020-07-31T20:14:00.000"
          },
          "additional_info": {
            "type": "string",
            "description": "Reservado para informações adicionais",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Objeto que representa as informações da cobrança via PIX"
      },
      "Billet": {
        "required": [
          "id",
          "code",
          "link",
          "expiration"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Id do boleto",
            "example": "00034a77630900162701"
          },
          "code": {
            "type": "string",
            "description": "Código de barras do boleto bancário",
            "example": "0819009009034776300000162701171188660000000500"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Link do PDF do boleto bancário",
            "example": "https://cdn.2rpay.com.br/billet/2022/01/bb/3efe1357a99d453fffd6a00576994afd746e523e.pdf"
          },
          "expiration": {
            "type": "string",
            "description": "Data de expiração do boleto bancário",
            "format": "date-time",
            "example": "2020-07-31T20:14:00.000"
          },
          "additional_info": {
            "type": "string",
            "description": "Reservado para informações adicionais",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Objeto que representa as informações da cobrança via Boleto Bancário"
      },
      "Metadata": {
        "type": "object",
        "properties": {
          "meu_campo": {
            "type": "string",
            "example": "meu_valor"
          },
          "outro_campo": {
            "type": "string",
            "example": "outro_valor"
          }
        },
        "additionalProperties": true,
        "description": "Campos personalizados livres associados à transação"
      },
      "payloadTransaction": {
        "required": [
          "id",
          "reference",
          "amount",
          "tax",
          "status",
          "created_at"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 13456465,
            "description": "Id da transação"
          },
          "reference": {
            "type": "string",
            "example": "000AAA111",
            "description": "Referência da transação"
          },
          "amount": {
            "type": "string",
            "example": "500",
            "description": "Valor da transação em centavos (500 = R$ 5,00)"
          },
          "tax": {
            "type": "string",
            "example": "099",
            "description": "Valor da tarifa em centavos (099 = R$ 0,99)"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Status"
              }
            ],
            "example": "paid"
          },
          "pix": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/Pix"
              }
            ]
          },
          "billet": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/Billet"
              }
            ]
          },
          "metadata": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/Metadata"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data/hora da transação",
            "example": "2020-07-31T20:14:00.000"
          },
          "postback_url": {
            "type": "string",
            "format": "uri",
            "example": "https://dominio.com.br/callback",
            "description": "URL de callback utilizada para enviar as notificações de mudança de status",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "payloadExtract": {
        "required": [
          "id",
          "amount",
          "tax",
          "total",
          "balance",
          "details",
          "reference",
          "created_at"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 13456465,
            "description": "Id do histórico"
          },
          "amount": {
            "type": "string",
            "example": "500",
            "description": "Valor em centavos (500 = R$ 5,00)"
          },
          "tax": {
            "type": "string",
            "example": "099",
            "description": "Valor da tarifa em centavos (099 = R$ 0,99)"
          },
          "total": {
            "type": "string",
            "example": "401",
            "description": "Valor total do histórico em centavos (401 = R$ 4,01)"
          },
          "balance": {
            "type": "string",
            "example": "1099",
            "description": "Saldo após a movimentação em centavos (1099 = R$ 10,99)"
          },
          "details": {
            "type": "string",
            "example": "Recebimento PIX",
            "description": "Detalhes do histórico"
          },
          "reference": {
            "type": "string",
            "example": "000AAA111",
            "description": "Referência do histórico"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data/hora da movimentação",
            "example": "2020-07-31T20:14:00.000"
          }
        },
        "additionalProperties": false
      },
      "payloadCreateTransaction": {
        "required": [
          "merchant_key",
          "payment_method",
          "amount",
          "customer"
        ],
        "type": "object",
        "properties": {
          "merchant_key": {
            "type": "string",
            "example": "q3sQ6K7ajGQaKXwlf9SOqtYDsl6WweRxL",
            "description": "Merchant Key da conta"
          },
          "payment_method": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PaymentMethod"
              }
            ],
            "example": "billet"
          },
          "billet": {
            "nullable": true,
            "description": "Obrigatório caso payment_method = billet",
            "allOf": [
              {
                "$ref": "#/components/schemas/CreateBillet"
              }
            ]
          },
          "pix": {
            "nullable": true,
            "description": "Obrigatório caso payment_method = pix",
            "allOf": [
              {
                "$ref": "#/components/schemas/CreatePix"
              }
            ]
          },
          "amount": {
            "type": "string",
            "example": "500",
            "description": "Valor da transação em centavos (500 = R$ 5,00)"
          },
          "metadata": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/Metadata"
              }
            ]
          },
          "customer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Customer"
              }
            ]
          },
          "postback_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "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.",
            "example": "https://seusite.com.br/webhook/2rpay"
          }
        },
        "additionalProperties": false
      }
    }
  }
}