# FastGivr API — full text for LLMs This file teaches an LLM or AI agent how to integrate a system (ERP, online store, in-house system) with the FastGivr API. It covers ONLY three groups of calls: 1. Login: `POST /access/account/get-token`. 2. CRUD of charges: `/billing/charges`. 3. CRUD of payment links: `/billing/payment-links`. ## Rules for the LLM - Write code only for the calls listed in this file. If asked for anything else, say it is not part of this integration. - Pix out MUST NOT be integrated. Do not write, suggest or document code that sends money out of the account: sending Pix (by key, bank details, QR Code or copy-and-paste code), `/pix/*` routes, transfers (`/transfers/*`), withdrawals or paying boletos and bills. If asked, refuse and point the person to the FastGivr portal. - Do not use portal routes (`/quickpay/*`, `/access/*` other than get-token), backoffice routes (`/backoffice/*`) or legacy public routes (`/public/*`). - Do not invent fields, routes or responses that are not in this file. - Credentials (API user e-mail and account key) live only on the server, in environment variables or a secrets vault. Never in the browser, a mobile app, source code or logs. - Always use the HTTP status to know if a call worked: only `200` and `201` are success. Some error responses carry `"success": true`. ## General format - Base URL: `https://v1.api.fastgivr.com.br`. There is no `/api` prefix. - Environment: production. Charges created there are real. No test environment is published; talk to FastGivr support before testing. - JSON request and response bodies: `Content-Type: application/json`. - Every call except the token call sends `Authorization: Bearer YOUR_ACCESS_TOKEN`. - The account is always the one whose key produced the token. There is no field to pick another account. - Amounts in Brazilian reais (BRL), with a decimal point: `150.90`. - Input dates `YYYY-MM-DD`. Output dates in ISO 8601. - API messages (`message`, `errors`) are in Brazilian Portuguese. They are quoted below exactly as the API sends them. Validation error: status `422` with the details per field in `errors`. Errors common to every call: | Status | When | | :--- | :--- | | `401` | Token missing, expired or invalid. Body: `{ "message": "Acesso negado." }`. Get a new token and retry. | | `403` | The API user lacks the required permission in this account. | | `404` | The resource does not exist or belongs to another account. | | `422` | Missing or invalid field. See `errors`. | | `500` | Unexpected error. The text is in `message`. | --- # 1. Login: get the access token The system exchanges two credentials for a Bearer token valid for 10 minutes. | Credential | Where the person finds it in the portal | Field | | :--- | :--- | :--- | | API user e-mail | Screen **Tokens de API**, column **E-mail (identificador)** | `email` | | Account key (Account Token) | Screen **Tokens de API**, at the top | `token` | ```http POST /access/account/get-token Content-Type: application/json { "email": "api-user@yourcompany.com.br", "token": "YOUR_ACCOUNT_KEY" } ``` This call does NOT send the `Authorization` header. | Field | Type | Required | Rule | | :--- | :--- | :--- | :--- | | `email` | string | yes | Valid e-mail of the API user. | | `token` | string | yes | Account key. | Response `200`: ```json { "code": 200, "success": true, "data": { "token": "YOUR_ACCESS_TOKEN", "token_type": "Bearer", "expires_at": "2026-11-03T14:10:00-03:00", "permissions": [ { "id": 1, "name": "PERMISSION_NAME", "guard_name": "api" } ] }, "message": "Autenticado com sucesso." } ``` Errors: | Status | When | `message` | | :--- | :--- | :--- | | `401` | Unknown e-mail, wrong key, or the user does not belong to that account. Always the same message. | `Essas credenciais não correspondem aos nossos registros.` | | `422` | `email` or `token` missing, invalid e-mail, or a field longer than 255 characters. | `Dados de entrada inválidos.` | | `429` | Too many wrong attempts (see below). | `Muitas tentativas de login. Por favor, tente novamente em 900 segundos.` | Too many wrong attempts: the API locks for 15 minutes the e-mail after 10 wrong attempts from the same IP, and the IP after 30 wrong attempts with any e-mail. Only wrong attempts count: an integration that logs in correctly is never locked, and a correct login resets the e-mail count. On `429`, wait the seconds in the `Retry-After` header; do not retry right away (each wrong attempt counts). Validity and renewal: - The token is valid for 10 minutes (`data.expires_at`). There is no refresh call: request a new token from `POST /access/account/get-token`. - Keep the token in memory and request a new one a minute before `expires_at`, or when a call returns `401` (retry that call once with the new token). ```js const BASE_URL = 'https://v1.api.fastgivr.com.br'; let cached = null; async function getAccessToken() { const response = await fetch(`${BASE_URL}/access/account/get-token`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: process.env.FASTGIVR_API_USER_EMAIL, token: process.env.FASTGIVR_ACCOUNT_TOKEN, }), }); if (!response.ok) throw new Error(`FastGivr auth failed: HTTP ${response.status}`); return (await response.json()).data; // { token, token_type, expires_at, permissions } } async function getValidToken() { const marginMs = 60 * 1000; if (!cached || new Date(cached.expires_at).getTime() - Date.now() < marginMs) { cached = await getAccessToken(); } return cached.token; } async function fastgivr(method, path, body, extraHeaders = {}) { const send = async () => fetch(`${BASE_URL}${path}`, { method, headers: { Authorization: `Bearer ${await getValidToken()}`, 'Content-Type': 'application/json', ...extraHeaders, }, body: body ? JSON.stringify(body) : undefined, }); let response = await send(); if (response.status === 401) { cached = null; // token expired: get a new one and try once more response = await send(); } const data = await response.json().catch(() => null); if (response.status !== 200 && response.status !== 201) { throw new Error(`FastGivr ${method} ${path}: HTTP ${response.status} ${data?.message ?? ''}`); } return data; } ``` --- # 2. CRUD of charges A charge is a payment request to a customer. | `payment_method` | The customer gets | | :--- | :--- | | `PIX` | A Pix QR Code (copy-and-paste code). | | `BOLETO` | A boleto (Brazilian bank slip) registered at the bank. | | `BOLEPIX` | A boleto with a Pix QR Code. Can be paid either way. | | Method | Path | Does | | :--- | :--- | :--- | | `POST` | `/billing/charges` | Create | | `GET` | `/billing/charges` | List | | `GET` | `/billing/charges/{id}` | Read | | `PUT` | `/billing/charges/{id}` | Update (pending only) | | `DELETE` | `/billing/charges/{id}` | Delete from the account | `{id}` accepts the numeric `id` or the `code` (string) of the charge. ## 2.1 Create a charge ```http POST /billing/charges Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Idempotency-Key: order-12345 ``` Always send `Idempotency-Key` with a value unique per order of your system (up to 255 characters). Repeating the call with the same key and the same data returns the same charge without creating another one. Rules: - `409`: the first attempt is still running, or ended with a `5xx` error and is being verified. Wait, check the charge list, and only then retry with the same key. - Same key with different data: `422`. Fixed the body after a `422`? Use a new key. Charge data: | Field | Type | Required | Rule | | :--- | :--- | :--- | :--- | | `payment_method` | string | yes | `PIX`, `BOLETO` or `BOLEPIX`. | | `value` | number | yes (or `amount`) | Amount in reais. Minimum `0.01`. Send `value` or `amount`, not both. | | `due_date` | date | yes | Due date `YYYY-MM-DD`. Today or later. | | `description` | string | no | Up to 500 characters. | | `details` | string | no | Free text. | | `instructions` | string | no | Free text. | | `webhook` | string | no | URL that receives the payment notice. | Customer — send ONE of these two ways: - Way 1, existing customer: `client_id` (number, ID of a customer of the account). A customer of another account returns `422`. - Way 2, data in the charge itself: `name` (up to 200), `email` (valid), `document` (CPF or CNPJ, the Brazilian tax IDs) and `phone` (optional). The API looks for a customer of the account with the same `document`: if found, it uses it and updates its data; if not, it creates one. Always send `document` in the same format (for example, digits only), or the same customer is created twice. `BOLETO` and `BOLEPIX` require a customer with a CPF or CNPJ (`422` on the `document` field). Interest, late fee and discount (only `BOLETO` and `BOLEPIX`; `0` or missing = none): | Field | Type | Rule | | :--- | :--- | :--- | | `amount_rate` | number | Interest after the due date. Minimum `0`. | | `type_rate` | string | `PERCENTAGE` (default, % per month) or `ABSOLUTE` (reais per day). | | `late_fee` | number | Late fee after the due date. Minimum `0`. | | `late_fee_type` | string | `PERCENTAGE` (default) or `ABSOLUTE` (reais). | | `discount` | number | Early payment discount. Minimum `0`. | | `type_discount` | string | `ABSOLUTE` (default, reais) or `PERCENTAGE`. | | `days_discount` | number | Days before the due date when the discount ends. That date cannot be before today. | A percentage above `100` is rejected (`422`). Example: ```json { "payment_method": "BOLEPIX", "value": 150.90, "due_date": "2026-11-30", "description": "Order 12345", "webhook": "https://yoursystem.example.com/webhooks/fastgivr", "name": "Example Customer", "email": "customer@example.com", "document": "00000000000", "late_fee": 2, "late_fee_type": "PERCENTAGE", "amount_rate": 1, "type_rate": "PERCENTAGE" } ``` Response `201` (shortened). The charge is in `data`: ```json { "data": { "id": 1001, "code": "charge-code-32-characters", "amount": 150.9, "amount_paid": 0, "payment_method": "BOLEPIX", "due_date": "2026-11-30T03:00:00.000000Z", "payment_date": null, "status": { "id": 1, "title": "pending", "description": "Pendente" }, "pix": { "txid": "PIX_TXID", "qrcode": "PIX_COPY_AND_PASTE_CODE", "amount": 150.9 }, "boleto": { "txid": "BOLETO_TXID", "barcode": "BOLETO_BARCODE", "digitable_line": null, "path_pdf": "https://BOLETO_PDF_URL.pdf" } } } ``` | Field | Use it to | | :--- | :--- | | `data.id` | Store in your system. Used to read, update and delete. | | `data.code` | String identifier. Also works as `{id}`. | | `data.pix.qrcode` | Show the Pix copy-and-paste code and render the QR Code image. `null` for `BOLETO`. | | `data.boleto.barcode` | Boleto barcode. `null` for `PIX`. | | `data.boleto.digitable_line` | Boleto typeable line. May be `null`: use `barcode` or the PDF. | | `data.boleto.path_pdf` | Link to the boleto PDF. | Create errors: `422` (fields), `409` (idempotency in progress), `4xx`/`5xx` with the bank message when the bank rejects the Pix or the boleto. If issuing fails halfway, the charge may stay in the list with status `failed` and nothing to pay. ## 2.2 List charges ```http GET /billing/charges?status_id=1&due_date_start=2026-11-01&due_date_end=2026-11-30&page=1&per_page=50 Authorization: Bearer YOUR_ACCESS_TOKEN ``` | Parameter | Rule | | :--- | :--- | | `search` | Up to 100 characters. Customer name, e-mail or document. | | `status_id` | Comma-separated IDs: `1,2`. | | `payment_method` | Comma-separated: `PIX,BOLEPIX`. | | `client_id` | Only this customer's charges. | | `created_at_start` / `created_at_end` | Creation date `YYYY-MM-DD`. | | `due_date_start` / `due_date_end` | Due date `YYYY-MM-DD`. | | `payment_date_start` / `payment_date_end` | Payment date `YYYY-MM-DD`. | | `order_by` | `created_at`, `due_date`, `payment_date` or `id` (default). | | `order_dir` | `asc` or `desc` (default). | | `page` | From `1`. | | `per_page` | From `1` to `500`. Default `15`. | Response `200`: list in `data` and pagination in `meta` (`total`, `page`, `limit`, `total_pages`, `has_next_page`, `has_prev_page`). To fetch everything, repeat with `page + 1` while `meta.has_next_page` is `true`. ## 2.3 Read a charge ```http GET /billing/charges/{id} Authorization: Bearer YOUR_ACCESS_TOKEN ``` Response `200`: the charge in `data`, with the create fields plus `client`. `404` with `message` `Cobrança não encontrada` if it does not exist or belongs to another account. To confirm a payment, read the charge before marking it paid in your system: `data.status.title` equal to `paid` and `data.amount_paid` with the paid amount. Statuses (`data.status.title`; always decide by `title`): | `title` | Meaning | | :--- | :--- | | `pending` | Waiting for payment. | | `paid` | Paid. See `amount_paid` and `payment_date`. | | `canceled` | Canceled. | | `failed` | Issuing failed. Nothing to pay. | | `DELETED` | Deleted by the account. | The ID of each status (for the `status_id` filter) comes from `GET /enums/charge-status` (no token). ## 2.4 Update a charge ```http PUT /billing/charges/{id} Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "due_date": "2026-12-15" } ``` Only updates a charge with status `pending`. Send only the fields that change: | Field | Rule | | :--- | :--- | | `due_date` | New due date, today or later. The Pix and the boleto are updated at the bank. | | `description` | Up to 500 characters. | | `details`, `instructions` | Free text. | | `webhook` | New notice URL. | | `amount_rate`, `type_rate`, `late_fee`, `late_fee_type` | Boleto interest and late fee. `0` removes. | | `discount`, `type_discount`, `days_discount` | Boleto discount. `days_discount` from `0` to `365`. `0` removes. | The amount does NOT change once the Pix or the boleto was issued (`422` on the `amount` field). For another amount, create a new charge. Response `200`: WARNING, the charge comes under the `charge` key (not `data`), with the stored fields. For the full format, read it with `GET /billing/charges/{id}`. ```json { "code": 200, "success": true, "charge": { "id": 1001, "code": "charge-code-32-characters", "value": "150.90", "due_date": "2026-12-15T03:00:00.000000Z", "status_id": 1 }, "message": "Cobrança atualizada com sucesso!" } ``` Errors: `404` (does not exist or belongs to another account), `422` (invalid field, locked amount, due date before today, or the bank rejected it), `500` (the charge is not pending, for example already paid). ## 2.5 Delete a charge ```http DELETE /billing/charges/{id} Authorization: Bearer YOUR_ACCESS_TOKEN ``` Response `200` with `message` `Cobrança apagado com sucesso!`. The charge moves to status `DELETED`. Before deleting, the API: - Refuses a paid charge: `422`, `Esta cobrança já foi paga e não pode ser excluída.` - Refuses a canceled charge: `422`, `Esta cobrança já foi excluída ou cancelada.` - Cancels the Pix at the bank: the QR code stops working. If the bank fails: `422`, `Não foi possível cancelar o Pix no banco. Nada foi alterado; tente novamente.` - Cancels the boleto at the bank (write-off). If the bank fails: `422`, the charge stays. Retry. - After that, nobody can pay the charge's Pix or boleto. - `404` if the charge does not exist, belongs to another account or was already deleted. --- # 3. CRUD of payment links A payment link is a ready-made checkout page where the customer pays. You create the link and send the customer the address returned in `public_url`. | Method | Path | Does | | :--- | :--- | :--- | | `POST` | `/billing/payment-links` | Create | | `GET` | `/billing/payment-links` | List | | `GET` | `/billing/payment-links/{external_id}` | Read | | `PUT` | `/billing/payment-links/{external_id}` | Update | | `DELETE` | `/billing/payment-links/{external_id}` | Remove | WARNING: in the routes with an identifier, use the `external_id` (UUID string) returned on creation, not the numeric `id`. ## 3.1 Create a link ```http POST /billing/payment-links Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` | Field | Type | Required | Rule | | :--- | :--- | :--- | :--- | | `title` | string | yes | Up to 255 characters. Shown to the customer. | | `payment_methods` | array | yes | At least one of: `PIX`, `BOLETO`, `CARD`. | | `amount` | number | yes, for a fixed amount | Amount in reais. Always send more than `0`. | | `is_variable_amount` | boolean | no | `true` = the customer picks the amount. Default `false`. | | `min_amount` | number | yes, when `is_variable_amount` is `true` | Lowest accepted amount. | | `max_amount` | number | no | Highest accepted amount. Greater than `min_amount`. | | `description` | string | no | Free text. | | `expires_at` | date-time | no | Link validity. Must be in the future. | | `max_uses` | integer | no | How many payments the link accepts. Minimum `1`. If omitted it is `1` (single-use link). `null` = no limit. | | `installments` | integer | no | Installments, from `1` to `12`. | | `pass_transaction_fee_to_customer` | boolean | no | `true` = the transaction fee is charged to the customer. | | `client_id` | integer | no | ID of a customer of your account. Only checked: the link does NOT store the customer. A customer of another account returns `422`. | | `reference_code` | string | no | Your order code. Up to 255. If omitted the API generates `REF-...`. | | `success_url` | URL | no | Where the customer goes after paying. | | `cancel_url` | URL | no | Where the customer goes when giving up. | | `webhook_url` | URL | no | Receives the link notices. Create only: it cannot be changed later. | | `currency` | string | no | 3 letters. Default `BRL`. | Example: ```json { "title": "Order 12345", "description": "Blue T-shirt, size M", "amount": 89.90, "payment_methods": ["PIX", "BOLETO"], "max_uses": 1, "expires_at": "2026-11-30T23:59:00-03:00", "reference_code": "ORDER-12345", "success_url": "https://yourstore.example.com/thanks", "webhook_url": "https://yoursystem.example.com/webhooks/fastgivr-links" } ``` Response `201` (shortened). The link is in `data`: ```json { "data": { "id": 77, "external_id": "9b1d3f5e-0000-0000-0000-000000000000", "title": "Order 12345", "amount": 89.9, "is_variable_amount": false, "payment_methods": [{ "value": "PIX", "label": "PIX" }, { "value": "BOLETO", "label": "BOLETO" }], "status": { "value": "active", "label": "Ativo" }, "reference_code": "ORDER-12345", "max_uses": 1, "current_uses": 0, "expires_at": "2026-12-01T02:59:00.000000Z", "public_url": "https://checkout-gateway.fastgivr.com.br/9b1d3f5e-0000-0000-0000-000000000000" }, "message": "Link de pagamento criado com sucesso." } ``` - Store `data.external_id`: it identifies the link in the other calls. - Send `data.public_url` to the customer. That is the page where they pay. - The link starts with status `active` and accepts payments right away. ## 3.2 List links ```http GET /billing/payment-links?status=active&page=1&per_page=50 Authorization: Bearer YOUR_ACCESS_TOKEN ``` | Parameter | Rule | | :--- | :--- | | `search` | Searches the title, the description or the `reference_code`. | | `status` | One status (see the table below). | | `id` | The numeric `id` of a link. | | `created_start` / `created_end` | Creation date. | | `updated_start` / `updated_end` | Last update date. | | `order` | `asc` or `desc` (default), by creation date. | | `page` | From `1`. | | `per_page` | From `1` to `100`. Default `15`. | Response `200`: links in `data`, pagination in `meta` and totals per status in `summary` (each item with `value`, `label`, `count` and `amount`; `summary.all` adds them all up). Link statuses (`data.status.value`): | `value` | Meaning | | :--- | :--- | | `active` | Accepts payments. | | `paid` | Paid. | | `exhausted` | Reached `max_uses`: no more payments. | | `expired` | Past `expires_at`. | | `canceled` | Turned off by the account. | | `pending`, `draft`, `unknown` | Other states. Treat as "does not accept payments". | ## 3.3 Read a link ```http GET /billing/payment-links/{external_id} Authorization: Bearer YOUR_ACCESS_TOKEN ``` Response `200`: the link in `data`. `client` is `null`: the link does not store the customer. `404` if it does not exist or belongs to another account. ## 3.4 Update a link ```http PUT /billing/payment-links/{external_id} Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "status": "canceled" } ``` Send only the fields that change: `title`, `description`, `status`, `amount`, `is_variable_amount`, `min_amount`, `max_amount`, `payment_methods`, `expires_at`, `max_uses`, `installments`, `pass_transaction_fee_to_customer`, `success_url`, `cancel_url`. Same rules as create; `amount` and `min_amount` minimum `0.01`. - `status` accepts only `active` (turn on) or `canceled` (turn off). - An expired link (`expired` or `expires_at` in the past) cannot be updated: `422` `Este link passou da validade e não pode ser editado. Crie um novo link.` - A link that already took payments keeps its amount: `422` `Este link já recebeu pagamentos. Para outro valor, crie um novo link.` - A `paid` or `exhausted` link keeps its status: `422` `Este link já foi pago e não pode mudar de status.` - `webhook_url` and `reference_code` cannot change after creation. Response `200`: the updated link in `data`, with `message` `Link de pagamento atualizado com sucesso.` ## 3.5 Remove a link ```http DELETE /billing/payment-links/{external_id} Authorization: Bearer YOUR_ACCESS_TOKEN ``` Response `200` with `message` `Link de pagamento removido com sucesso.`. The link leaves the list. To only stop taking payments, prefer `PUT` with `{ "status": "canceled" }`, which keeps the history. `404` if it does not exist or belongs to another account. --- # 4. Ready-made flows Direct charge: 1. `POST /access/account/get-token` → keep `data.token`. 2. `POST /billing/charges` with `Idempotency-Key` and `webhook` → keep `data.id`. 3. Show the customer `data.pix.qrcode` or `data.boleto.path_pdf`. 4. When the notice reaches the `webhook`, confirm with `GET /billing/charges/{id}` (`status.title` = `paid`) before marking it paid. Payment link: 1. `POST /access/account/get-token`. 2. `POST /billing/payment-links` → keep `data.external_id`. 3. Send `data.public_url` to the customer. 4. Follow it with `GET /billing/payment-links/{external_id}` (`status.value`, `current_uses`). Nothing outside these flows is part of this integration. In particular, Pix out (sending money out of the account) must not be integrated.