--- title: "Collect" description: "20 operations under /v1/collect (GET POST PATCH PUT): parameters, status codes, refusal bodies, and the same request in curl, HTTP, Python and TypeScript." --- Base URL: `https://api.codespar.dev` Operations below require a Bearer token unless their bar says `No credential`. See [Authentication](/docs/concepts/authentication). ### GET `/v1/collect/attempts/{attemptId}/artifact` The WhatsApp material of an attempt What the partner's channel sends: the copia-e-cola, a QR code PNG of it (base64), the amount, the due date and the hosted page URL as the fallback. CodeSpar sends nothing (`sent` is always false). NOT BEFORE IT EXISTS. While the attempt is `issuing` this answers 409 `artifact_not_ready` with `Retry-After` and `details.retry_after`; subscribe to `collect.attempt.ready` instead of polling if you prefer; a failed attempt emits `collect.attempt.failed` with its `failure_code`. An attempt that is no longer payable (paid, superseded, expired, cancelled, failed) answers 410 `artifact_unavailable` with its state. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `attemptId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | No attempt with that id in this project. | | `409` | object | Not ready, or the link does not enable WhatsApp. | | `410` | object | The attempt has no payable material any more. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | `integer` | yes | — | | `attempt_id` | `string` | yes | — | | `copy_paste` | `string,null` | yes | The Pix copia-e-cola. Null until the attempt is `open`: it does not exist before the issuer registers it. | | `currency` | `"BRL"` | yes | — | | `due_date` | `string` | yes | — | | `environment` | `"live"` \| `"test"` | yes | The link's environment. `test`: the Pix moves no real money, and the message can say so. | | `expires_at` | `string` | yes | — | | `failure_code` | `string,null` | no | — | | `fallback_url` | `string` | yes | — | | `id` | `string` | yes | — | | `link_id` | `string` | yes | — | | `object` | `"collect_artifact"` | yes | — | | `qr_mime_type` | `"image/png"` | yes | — | | `qr_png_base64` | `string` | yes | — | | `ready_at` | `string,null` | yes | — | | `retry_after` | `integer` | no | While `issuing`: seconds until the next readiness check. | | `sent` | `false` | yes | — | | `state` | `"issuing"` \| `"open"` \| `"superseded"` \| `"expired"` \| `"cancelled"` \| `"paid"` \| `"failed"` | yes | — | | `surface` | `"page"` \| `"whatsapp"` | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/attempts/{attemptId}/artifact \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/attempts/{attemptId}/artifact HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/attempts/{attemptId}/artifact", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/attempts/{attemptId}/artifact", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/attempts/{attemptId}/artifact", { path: { attemptId: "attempt_0000000000000000" } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "state": "issuing", "surface": "page", "amount_minor": 1000, "currency": "BRL", "due_date": "string", "expires_at": "string", "copy_paste": "string", "ready_at": "string", "retry_after": 0, "failure_code": "string", "object": "collect_artifact", "attempt_id": "attempt_0000000000000000", "link_id": "link_0000000000000000", "environment": "live", "qr_png_base64": "string", "qr_mime_type": "image/png", "fallback_url": "https://example.com/hook", "sent": false } ``` ### POST `/v1/collect/attempts/{attemptId}/test-pay` Pay a Test attempt's charge from the shared Test payer (the payer button) "Simular pagamento do cliente": pays the attempt's charge FOR REAL at the Celcoin sandbox, from the operator's Test payer account, the way a customer would pay its copia-e-cola. Test projects only. No body: the amount and the destination come from the stored attempt and charge. One payment per charge; a second call answers 409 `test_pay_already_used` whatever happened to the first. Capped per payment and per project per 24 hours. The attempt turns `paid` the way any payment does (the charge-in, the reconciler, or the hosted page's read), never from this answer. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `attemptId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | A body was sent, or the credential names no project. | | `403` | object | Not a Test credential or project. | | `404` | object | No attempt with that id in this project. | | `409` | object | The attempt is not open, the charge already had its Test payment, or it is above the cap. | | `429` | object | The project used its Test payments for the last 24 hours. | | `502` | object | A step at Celcoin failed; the charge keeps its claim. | | `503` | object | No Test payer or Celcoin connection on this deployment. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | `integer` | yes | — | | `attempt_id` | `string` | yes | — | | `charge_id` | `string` | yes | — | | `end_to_end_id` | `string,null` | yes | — | | `object` | `"collect_test_payment"` | yes | — | | `status` | `string` | yes | Celcoin's answer to the Pix, usually PROCESSING; not a settlement. | ```bash curl -X POST https://api.codespar.dev/v1/collect/attempts/{attemptId}/test-pay \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http POST /v1/collect/attempts/{attemptId}/test-pay HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/attempts/{attemptId}/test-pay", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/attempts/{attemptId}/test-pay", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const r = await cs.api.response("post", "/v1/collect/attempts/{attemptId}/test-pay", { path: { attemptId: "attempt_0000000000000000" } }); // r.status is one of the documented statuses (200, 403), // each with its own body shape in r.data; nothing here throws on 403. if (r.ok) { console.log(r.data); } ``` ```json title="application/json" { "object": "collect_test_payment", "attempt_id": "attempt_0000000000000000", "charge_id": "charge_0000000000000000", "amount_minor": 1000, "status": "string", "end_to_end_id": "endtoend_0000000000000000" } ``` ### GET `/v1/collect/links` List this project's Collect links Newest first. `next_cursor` is the `created_at` of the last row, to pass as `before`. **Query parameters** | Name | Type | Required | Description | |---|---|---|---| | `before` | `string (date-time)` | no | — | | `limit` | `integer` | no | — | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | Bad Request. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | — | | `next_cursor` | `string,null` | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/links \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/links HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/links", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/links"); ``` ```json title="application/json" { "data": [ { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } } } ], "next_cursor": "string" } ``` ### POST `/v1/collect/links` Create a Collect link with its first draft Creates a single-use link (one link, one charge, one valid payment) in `draft`, with version 1 as its draft. Nothing is shown to payers until it is published. `consumer_id` is the RECEIVING consumer: the Pix the link issues settles into that consumer's wallet. No Pix key or account is accepted on the link. `payer` optionally prefills the payer. `document` (CPF/CNPJ, check digits verified) and `address` are the regulated fields a Pix with due date requires; when they are not prefilled, the hosted page collects them. All payer data is stored encrypted and is never returned: the response names which fields are prefilled and shows the document masked. Collect is off unless the deployment sets `COLLECT_ENABLED=true`. Off, every `/v1/collect` path (owner and payer) answers 404 `{"error": "collect_disabled", "message": "Collect não está disponível nesta versão. ..."}`, never the router's generic 404. **Request body** | Field | Type | Required | Description | |---|---|---|---| | `consumer_id` | `string` | yes | — | | `payer` | object | no | — | | `valid_until` | `string (date-time)` | no | — | | `version` | object | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `201` | object | OK | | `400` | object | Bad Request. The body did not match the schema (`invalid_body`, with `details.issues`), or the version breaks a rule the schema cannot state: the items total below the R$5.00 a Pix with due date needs (`collect_total_below_minimum`), above R$1,000,000.00 (`collect_total_above_maximum`), or brand colors whose contrast is below 4.5:1 (`collect_brand_contrast_insufficient`), or a `usdc_price` on a version without the agent surface (`collect_usdc_price_requires_agent`). Unknown keys are refused, not dropped: the regulated payer fields (document, address) are never free-text questions. | **Response `201`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X POST https://api.codespar.dev/v1/collect/links \ -H "Authorization: Bearer $CODESPAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "consumer_id": "csm_0000000000000000", "valid_until": "2026-01-15T12:00:00.000Z", "version": { "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }, "payer": { "name": "Example", "contact": "string", "external_reference": "string", "document": "string", "address": { "publicArea": "string", "number": "string", "neighborhood": "string", "city": "string", "state": "string", "postalCode": "string" } } }' ``` ```http POST /v1/collect/links HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY Content-Type: application/json { "consumer_id": "csm_0000000000000000", "valid_until": "2026-01-15T12:00:00.000Z", "version": { "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }, "payer": { "name": "Example", "contact": "string", "external_reference": "string", "document": "string", "address": { "publicArea": "string", "number": "string", "neighborhood": "string", "city": "string", "state": "string", "postalCode": "string" } } } ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/links", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, json={ "consumer_id": "csm_0000000000000000", "valid_until": "2026-01-15T12:00:00.000Z", "version": { "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }, "payer": { "name": "Example", "contact": "string", "external_reference": "string", "document": "string", "address": { "publicArea": "string", "number": "string", "neighborhood": "string", "city": "string", "state": "string", "postalCode": "string" } } }, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "consumer_id": "csm_0000000000000000", "valid_until": "2026-01-15T12:00:00.000Z", "version": { "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }, "payer": { "name": "Example", "contact": "string", "external_reference": "string", "document": "string", "address": { "publicArea": "string", "number": "string", "neighborhood": "string", "city": "string", "state": "string", "postalCode": "string" } } }), }); const data = await res.json(); ``` ```ts const result = await cs.api.post("/v1/collect/links", { body: { consumer_id: "csm_0000000000000000", valid_until: "2026-01-15T12:00:00.000Z", version: { title: "Example", description: "string", success_message: "string", items: [ { name: "Example", quantity: 0, unit_amount_minor: 1000 } ], brand: { logo_url: "https://example.com/hook", color: "string", text_color: "string", texts: { header: "string", footer: "string" } }, surfaces: [ "page" ], due_in_days: 0, payer_fields: { contact: "optional", external_reference: "off" }, usdc_price: "string" }, payer: { name: "Example", contact: "string", external_reference: "string", document: "string", address: { publicArea: "string", number: "string", neighborhood: "string", city: "string", state: "string", postalCode: "string" } } } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } } } ``` ### GET `/v1/collect/links/stats` The project's Collect numbers over the last 30 days One read for the Collect screen's figures, over `[to - 30 days, to)` by `paid_at`. Only `paid` payments count as received: a late or duplicate payment is credited too, but it is a refund obligation, not revenue. `by_surface` is the surface of the attempt each payment paid. `previous_received_minor` is the same sum over the 30 days before, and null when the project has no paid payment before `from` (no history to compare against; 0 would read as a real drop). `links` lists every link with a paid payment or an attempt in the window, most received first; a link with neither is absent. **Query parameters** | Name | Type | Required | Description | |---|---|---|---| | `window` | `"30d"` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | Bad Request. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `by_surface` | object | yes | — | | `currency` | `"BRL"` | yes | — | | `from` | `string` | yes | — | | `links` | array of object | yes | — | | `payments` | `integer` | yes | Paid payments in the window. | | `previous_received_minor` | `integer,null` | yes | — | | `received_minor` | `integer` | yes | — | | `to` | `string` | yes | — | | `window` | `"30d"` | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/links/stats \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/links/stats HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/links/stats", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/stats", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/links/stats"); ``` ```json title="application/json" { "window": "30d", "from": "string", "to": "string", "currency": "BRL", "received_minor": 1, "previous_received_minor": 1, "payments": 0, "by_surface": { "page": 0, "whatsapp": 0 }, "links": [ { "link_id": "link_0000000000000000", "received_minor": 1, "payments": 0, "attempts": 0, "by_surface": { "page": 0, "whatsapp": 0 }, "paid": true } ] } ``` ### GET `/v1/collect/links/{linkId}` Read a Collect link **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X GET https://api.codespar.dev/v1/collect/links/{linkId} \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/links/{linkId} HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/links/{linkId}", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/links/{linkId}", { path: { linkId: "link_0000000000000000" } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } } } ``` ### PATCH `/v1/collect/links/{linkId}` Change a draft link's validity or receiving consumer Only while the link has never been published (`state: draft`). Once published, the validity and the receiving consumer are fixed with what payers were shown, and this answers 409 `collect_link_published_immutable` (an archived link: `collect_link_archived`); a different charge is a new link. A new `consumer_id` is asked the publish gate's question first, in the link's environment, and refused with the same 422 `receiving_identity_missing`; the link is left as it was. `valid_until: null` clears the validity. At least one field. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Request body** | Field | Type | Required | Description | |---|---|---|---| | `consumer_id` | `string` | no | — | | `valid_until` | `string,null (date-time)` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | Bad Request. The body did not match the schema (`invalid_body`, with `details.issues`), or the version breaks a rule the schema cannot state: the items total below the R$5.00 a Pix with due date needs (`collect_total_below_minimum`), above R$1,000,000.00 (`collect_total_above_maximum`), or brand colors whose contrast is below 4.5:1 (`collect_brand_contrast_insufficient`), or a `usdc_price` on a version without the agent surface (`collect_usdc_price_requires_agent`). Unknown keys are refused, not dropped: the regulated payer fields (document, address) are never free-text questions. | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | | `409` | object | The link was published (or archived): its settings are fixed. | | `422` | object | The new consumer cannot receive a Pix with due date in the link's environment. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X PATCH https://api.codespar.dev/v1/collect/links/{linkId} \ -H "Authorization: Bearer $CODESPAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "valid_until": "2026-01-15T12:00:00.000Z", "consumer_id": "csm_0000000000000000" }' ``` ```http PATCH /v1/collect/links/{linkId} HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY Content-Type: application/json { "valid_until": "2026-01-15T12:00:00.000Z", "consumer_id": "csm_0000000000000000" } ``` ```python import os import requests res = requests.patch( "https://api.codespar.dev/v1/collect/links/{linkId}", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, json={ "valid_until": "2026-01-15T12:00:00.000Z", "consumer_id": "csm_0000000000000000" }, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "valid_until": "2026-01-15T12:00:00.000Z", "consumer_id": "csm_0000000000000000" }), }); const data = await res.json(); ``` ```ts const r = await cs.api.response("patch", "/v1/collect/links/{linkId}", { path: { linkId: "link_0000000000000000" }, body: { valid_until: "2026-01-15T12:00:00.000Z", consumer_id: "csm_0000000000000000" } }); // r.status is one of the documented statuses (200, 422), // each with its own body shape in r.data; nothing here throws on 422. if (r.ok) { console.log(r.data); } ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } } } ``` ### POST `/v1/collect/links/{linkId}/archive` Archive a Collect link Terminal. The link takes no new version and issues nothing. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `changed` | `boolean` | yes | False when the link was already in the requested state (the call was a no-op). | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X POST https://api.codespar.dev/v1/collect/links/{linkId}/archive \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http POST /v1/collect/links/{linkId}/archive HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/links/{linkId}/archive", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/archive", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.post("/v1/collect/links/{linkId}/archive", { path: { linkId: "link_0000000000000000" } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } }, "changed": true } ``` ### GET `/v1/collect/links/{linkId}/attempts` List a Collect link's attempts Newest first. No payer data and no copia-e-cola: an attempt's state, charge, amount and due date only. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/links/{linkId}/attempts \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/links/{linkId}/attempts HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/links/{linkId}/attempts", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/attempts", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/links/{linkId}/attempts", { path: { linkId: "link_0000000000000000" } }); ``` ```json title="application/json" { "data": [ { "id": "obj_0000000000000000", "object": "collect_attempt", "link_id": "link_0000000000000000", "version": 0, "surface": "page", "state": "issuing", "charge_id": "charge_0000000000000000", "amount_minor": 1000, "currency": "BRL", "due_date": "string", "expires_at": "string", "ready_at": "string", "superseded_by": "string", "failure_code": "string", "created_at": "string", "closed_at": "string" } ] } ``` ### POST `/v1/collect/links/{linkId}/attempts` Issue a Pix attempt for the partner's channel Issues a payable Pix with due date on a published link, for the partner's own channel (surface `whatsapp` by default). Same rules as the hosted page's POST: the amount is the published version's, the payer fields not prefilled are sent here, one live attempt per link (`collect_attempt_exists`), and `renew: true` replaces the open attempt only after its charge was cancelled at the issuer. `idempotency_key` (or the `Idempotency-Key` header) makes a retry answer the same attempt. The attempt starts `issuing`: the copia-e-cola appears 30 s to 60 min later. Read it with the artifact route, or subscribe to `collect.attempt.ready`. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Request body** | Field | Type | Required | Description | |---|---|---|---| | `idempotency_key` | `string` | no | — | | `payer` | object | no | — | | `renew` | `boolean` | no | — | | `surface` | `"whatsapp"` \| `"page"` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `201` | object | OK | | `400` | object | Bad Request. | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | | `409` | object | Conflict. | | `410` | object | The link is past its validity. | | `422` | object | The issuer refused the charge before it existed; `details.failure_code` says why. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | `integer` | yes | — | | `charge_id` | `string,null` | yes | — | | `closed_at` | `string,null` | yes | — | | `created_at` | `string` | yes | — | | `currency` | `"BRL"` | yes | — | | `due_date` | `string` | yes | — | | `expires_at` | `string` | yes | — | | `failure_code` | `string,null` | yes | — | | `id` | `string` | yes | `cla_` + 128 random bits. The charge is created under `idempotency_key = collect:`. | | `link_id` | `string` | yes | — | | `object` | `"collect_attempt"` | yes | — | | `ready_at` | `string,null` | yes | — | | `replay` | `true` | yes | — | | `state` | `"issuing"` \| `"open"` \| `"superseded"` \| `"expired"` \| `"cancelled"` \| `"paid"` \| `"failed"` | yes | `issuing` until the copia-e-cola exists (30 s to 60 min after the charge is created); `open` once it does; `failed` when it never did (`failure_code`). | | `superseded` | `string,null` | yes | — | | `superseded_by` | `string,null` | yes | — | | `surface` | `"page"` \| `"whatsapp"` | yes | — | | `version` | `integer` | yes | — | ```bash curl -X POST https://api.codespar.dev/v1/collect/links/{linkId}/attempts \ -H "Authorization: Bearer $CODESPAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "surface": "whatsapp", "payer": {}, "renew": false, "idempotency_key": "string" }' ``` ```http POST /v1/collect/links/{linkId}/attempts HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY Content-Type: application/json { "surface": "whatsapp", "payer": {}, "renew": false, "idempotency_key": "string" } ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/links/{linkId}/attempts", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, json={ "surface": "whatsapp", "payer": {}, "renew": False, "idempotency_key": "string" }, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/attempts", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "surface": "whatsapp", "payer": {}, "renew": false, "idempotency_key": "string" }), }); const data = await res.json(); ``` ```ts const r = await cs.api.response("post", "/v1/collect/links/{linkId}/attempts", { path: { linkId: "link_0000000000000000" }, body: { surface: "whatsapp", payer: {}, renew: false, idempotency_key: "string" } }); // r.status is one of the documented statuses (200, 422), // each with its own body shape in r.data; nothing here throws on 422. if (r.ok) { console.log(r.data); } ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_attempt", "link_id": "link_0000000000000000", "version": 0, "surface": "page", "state": "issuing", "charge_id": "charge_0000000000000000", "amount_minor": 1000, "currency": "BRL", "due_date": "string", "expires_at": "string", "ready_at": "string", "superseded_by": "string", "failure_code": "string", "created_at": "string", "closed_at": "string", "replay": true, "superseded": "string" } ``` ### PUT `/v1/collect/links/{linkId}/draft` Replace the draft of a Collect link Replaces the open draft, or opens a new draft after the last publish. A published version never changes. Refused on an archived link, and on a link that already issued a Pix to a payer (`collect_link_version_locked`): a single-use link keeps the version it was issued under. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Request body** | Field | Type | Required | Description | |---|---|---|---| | `brand` | object | no | — | | `description` | `string` | no | — | | `due_in_days` | `integer` | yes | — | | `items` | array of object | yes | — | | `payer_fields` | object | no | — | | `success_message` | `string` | no | — | | `surfaces` | array of `"page"` \| `"whatsapp"` \| `"agent"` | yes | — | | `title` | `string` | yes | — | | `usdc_price` | `string` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | Bad Request. The body did not match the schema (`invalid_body`, with `details.issues`), or the version breaks a rule the schema cannot state: the items total below the R$5.00 a Pix with due date needs (`collect_total_below_minimum`), above R$1,000,000.00 (`collect_total_above_maximum`), or brand colors whose contrast is below 4.5:1 (`collect_brand_contrast_insufficient`), or a `usdc_price` on a version without the agent surface (`collect_usdc_price_requires_agent`). Unknown keys are refused, not dropped: the regulated payer fields (document, address) are never free-text questions. | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | | `409` | object | Conflict. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X PUT https://api.codespar.dev/v1/collect/links/{linkId}/draft \ -H "Authorization: Bearer $CODESPAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }' ``` ```http PUT /v1/collect/links/{linkId}/draft HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY Content-Type: application/json { "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" } ``` ```python import os import requests res = requests.put( "https://api.codespar.dev/v1/collect/links/{linkId}/draft", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, json={ "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/draft", { method: "PUT", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "brand": { "logo_url": "https://example.com/hook", "color": "string", "text_color": "string", "texts": { "header": "string", "footer": "string" } }, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "contact": "optional", "external_reference": "off" }, "usdc_price": "string" }), }); const data = await res.json(); ``` ```ts const result = await cs.api.put("/v1/collect/links/{linkId}/draft", { path: { linkId: "link_0000000000000000" }, body: { title: "Example", description: "string", success_message: "string", items: [ { name: "Example", quantity: 0, unit_amount_minor: 1000 } ], brand: { logo_url: "https://example.com/hook", color: "string", text_color: "string", texts: { header: "string", footer: "string" } }, surfaces: [ "page" ], due_in_days: 0, payer_fields: { contact: "optional", external_reference: "off" }, usdc_price: "string" } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } } } ``` ### POST `/v1/collect/links/{linkId}/pause` Pause a Collect link No new attempt is issued while paused, and payers see the link as paused. An attempt already issued can still be paid; that payment is credited. Emits `collect.link.paused`. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | | `409` | object | Conflict: the link is not published. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `changed` | `boolean` | yes | False when the link was already in the requested state (the call was a no-op). | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X POST https://api.codespar.dev/v1/collect/links/{linkId}/pause \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http POST /v1/collect/links/{linkId}/pause HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/links/{linkId}/pause", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/pause", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.post("/v1/collect/links/{linkId}/pause", { path: { linkId: "link_0000000000000000" } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } }, "changed": true } ``` ### GET `/v1/collect/links/{linkId}/payments` List a Collect link's payments Every payment of the link's charges: the one `paid` (a single-use link has at most one) and any exceptions. Each is recorded in the same transaction as the wallet credit, keyed on the charge id, and carries its signed receipt once minted. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/links/{linkId}/payments \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/links/{linkId}/payments HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/links/{linkId}/payments", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/payments", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/links/{linkId}/payments", { path: { linkId: "link_0000000000000000" } }); ``` ```json title="application/json" { "data": [ { "id": "obj_0000000000000000", "object": "collect_payment", "kind": "paid", "exception": "late", "link_id": "link_0000000000000000", "attempt_id": "attempt_0000000000000000", "surface": "page", "version": 0, "charge_id": "charge_0000000000000000", "amount_minor": 1000, "currency": "BRL", "paid_at": "string", "rail": "pix", "end_to_end_id": "endtoend_0000000000000000", "ledger_entry_id": "ledgerentry_0000000000000000", "simulated": true, "receipt": { "id": "obj_0000000000000000", "object": "collect_receipt", "document": { "v": 1, "receipt_id": "receipt_0000000000000000", "issuer": "string", "charge_id": "charge_0000000000000000", "link_id": "link_0000000000000000", "link_version": 0, "amount_minor": 1000, "currency": "BRL", "paid_at": "string", "rail": "pix", "end_to_end_id": "endtoend_0000000000000000", "ledger_entry_id": "ledgerentry_0000000000000000" }, "digest": "string", "sig": "string", "kid": "string", "recipe": {} } } ] } ``` ### POST `/v1/collect/links/{linkId}/publish` Publish a Collect link Freezes the draft as the version in force and puts the link in front of payers; emits `collect.link.published`. GATED ON THE RECEIVER. The owner's consumer must be able to receive a Pix with due date in the link's environment: its own receiving identity, or, in a test project, the shared-sandbox receiver seeded on this deployment. Otherwise the publish is refused with 422 `receiving_identity_missing` before anything is written, and the link stays a draft. A link already published with no new draft answers 200 with `changed: false`. CONFIRMED USDC PRICE (N12). A draft with a `usdc_price` publishes only when the body confirms that exact price (`confirm_usdc_price`); the confirmation is stored with the version (`usdc_price_confirmed_at`). A missing or different price, or a price confirmed for a draft that has none, answers 409 `collect_usdc_price_unconfirmed` with the draft's price and the statement the tenant confirms, and nothing is published. A different price is a new version and asks again. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Request body** | Field | Type | Required | Description | |---|---|---|---| | `confirm_usdc_price` | `string,null` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | Bad Request. The body did not match the schema (`invalid_body`, with `details.issues`), or the version breaks a rule the schema cannot state: the items total below the R$5.00 a Pix with due date needs (`collect_total_below_minimum`), above R$1,000,000.00 (`collect_total_above_maximum`), or brand colors whose contrast is below 4.5:1 (`collect_brand_contrast_insufficient`), or a `usdc_price` on a version without the agent surface (`collect_usdc_price_requires_agent`). Unknown keys are refused, not dropped: the regulated payer fields (document, address) are never free-text questions. | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | | `409` | object | Conflict. | | `422` | object | The owner's consumer has no receiving identity in this environment. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `changed` | `boolean` | yes | False when the link was already in the requested state (the call was a no-op). | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X POST https://api.codespar.dev/v1/collect/links/{linkId}/publish \ -H "Authorization: Bearer $CODESPAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "confirm_usdc_price": "string" }' ``` ```http POST /v1/collect/links/{linkId}/publish HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY Content-Type: application/json { "confirm_usdc_price": "string" } ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/links/{linkId}/publish", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, json={ "confirm_usdc_price": "string" }, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/publish", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "confirm_usdc_price": "string" }), }); const data = await res.json(); ``` ```ts const r = await cs.api.response("post", "/v1/collect/links/{linkId}/publish", { path: { linkId: "link_0000000000000000" }, body: { confirm_usdc_price: "string" } }); // r.status is one of the documented statuses (200, 422), // each with its own body shape in r.data; nothing here throws on 422. if (r.ok) { console.log(r.data); } ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } }, "changed": true } ``` ### GET `/v1/collect/links/{linkId}/refunds` The refund obligations of a link's exception payments A payment that is not the link's one valid payment (`late` or `duplicate`) is never kept as credit by default. Its refund obligation is recorded in the same transaction as the credit. A duplicate is due for refund at once. A late payment waits for the collector until `decide_by` (`COLLECT_LATE_REFUND_DECISION_DAYS`, 3 by default), and is due for refund if not honored. Events: `collect.refund.awaiting_decision`, `collect.refund.required` (with `refund_method` and `manual`), `collect.refund.honored`. No money moves yet: a Pix refund waits in `awaiting_pix_rail`, and a boleto one is `manual_refund_required`. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/links/{linkId}/refunds \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/links/{linkId}/refunds HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/links/{linkId}/refunds", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/refunds", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/links/{linkId}/refunds", { path: { linkId: "link_0000000000000000" } }); ``` ```json title="application/json" { "data": [ { "id": "obj_0000000000000000", "object": "collect_refund", "payment_id": "payment_0000000000000000", "link_id": "link_0000000000000000", "charge_id": "charge_0000000000000000", "reason": "late", "refund_method": "pix", "state": "awaiting_collector", "amount_minor": 1000, "currency": "BRL", "decide_by": "string", "decided_at": "string", "created_at": "string" } ] } ``` ### POST `/v1/collect/links/{linkId}/resume` Resume a paused Collect link Publishes the link again, re-checking the receiving identity first; emits `collect.link.published` with `resumed: true`. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | Not Found. No link with that id in this project. A link of another project answers identically. | | `409` | object | Conflict: the link is not paused. | | `422` | object | The owner's consumer has no receiving identity in this environment. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `agent` | `object,null` | no | The agent surface (402), on the single-link read: null when the version in force does not enable it. | | `archived_at` | `string,null` | yes | — | | `changed` | `boolean` | yes | False when the link was already in the requested state (the call was a no-op). | | `consumer_id` | `string` | yes | The receiving consumer: the charge settles into its wallet. | | `created_at` | `string` | yes | — | | `current_version` | `integer,null` | yes | — | | `draft` | `object,null` | yes | The open draft, if any. | | `environment` | `"live"` \| `"test"` | yes | — | | `id` | `string` | yes | `cl_` + 128 random bits. Minted by the server; never chosen by the caller. | | `object` | `"collect_link"` | yes | — | | `paid` | `boolean` | yes | Whether the link has its paid payment, whenever it settled (not bound to any stats window). A late or duplicate payment is not the link's payment and does not make it paid. | | `paid_at` | `string,null` | yes | When the paid payment settled; null while unpaid. | | `paused_at` | `string,null` | yes | — | | `payer_document_masked` | `string,null` | yes | The prefilled CPF/CNPJ, last four characters only. | | `payer_prefilled` | array of `"name"` \| `"contact"` \| `"external_reference"` \| `"document"` \| `"address"` | yes | Which payer fields were prefilled at create. Their values are never returned. | | `published_at` | `string,null` | yes | — | | `receiver` | object | yes | The name the payer sees on the hosted page: the consumer's display name, else the organization's name. The same text the public read answers. | | `state` | `"draft"` \| `"published"` \| `"paused"` \| `"archived"` | yes | — | | `updated_at` | `string` | yes | — | | `url` | `string` | yes | The hosted page for this link. | | `valid_until` | `string,null` | yes | — | | `version` | `object,null` | yes | The published version in force. | ```bash curl -X POST https://api.codespar.dev/v1/collect/links/{linkId}/resume \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http POST /v1/collect/links/{linkId}/resume HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/links/{linkId}/resume", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/links/{linkId}/resume", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const r = await cs.api.response("post", "/v1/collect/links/{linkId}/resume", { path: { linkId: "link_0000000000000000" } }); // r.status is one of the documented statuses (200, 422), // each with its own body shape in r.data; nothing here throws on 422. if (r.ok) { console.log(r.data); } ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_link", "state": "draft", "environment": "live", "consumer_id": "csm_0000000000000000", "receiver": { "name": "Example" }, "paid": true, "paid_at": "string", "current_version": 0, "valid_until": "string", "url": "https://example.com/hook", "payer_prefilled": [ "name" ], "payer_document_masked": "string", "version": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "draft": { "version": 0, "status": "draft", "title": "Example", "description": "string", "success_message": "string", "items": [ { "name": "Example", "quantity": 0, "unit_amount_minor": 1000 } ], "total_minor": 1, "currency": "BRL", "brand": {}, "surfaces": [ "page" ], "due_in_days": 0, "payer_fields": { "name": "required", "contact": "required", "external_reference": "required" }, "usdc_price": "string", "usdc_price_atomic": "string", "usdc_price_confirmed_at": "string", "created_at": "string", "published_at": "string" }, "created_at": "string", "updated_at": "string", "published_at": "string", "paused_at": "string", "archived_at": "string", "agent": { "url": "https://example.com/hook", "status": "ready", "reason": "string", "challenge": {}, "refusal": { "code": "string", "message": "string", "http_status": 0 }, "usdc": { "price": "string", "amount": "1000", "currency": "USDC", "network": "string", "asset": "string", "payable": false, "reason": "usdc_pay_to_unavailable", "message": "string", "statement": "string" } }, "changed": true } ``` ### POST `/v1/collect/payments/{paymentId}/honor` Keep a late payment instead of refunding it The collector confirms they honor a LATE payment, before its `decide_by`. Idempotent: honoring an honored refund answers it again. A duplicate cannot be honored, and a late payment past its window is already due for refund. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `paymentId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `404` | object | No payment with a refund decision under that id in this project. | | `409` | object | Not honorable. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | `integer` | yes | — | | `charge_id` | `string` | yes | — | | `created_at` | `string` | yes | — | | `currency` | `"BRL"` | yes | — | | `decide_by` | `string,null` | yes | — | | `decided_at` | `string,null` | yes | — | | `id` | `string` | yes | — | | `link_id` | `string` | yes | — | | `object` | `"collect_refund"` | yes | — | | `payment_id` | `string` | yes | — | | `reason` | `"late"` \| `"duplicate"` | yes | — | | `refund_method` | `"pix"` \| `"manual"` | yes | `pix` when the payment was a Pix; `manual` when it was a boleto or the channel is unknown. | | `state` | `"awaiting_collector"` \| `"honored"` \| `"awaiting_pix_rail"` \| `"manual_refund_required"` | yes | `awaiting_collector`: a late payment the collector may honor until `decide_by`. `honored`: kept by the collector. `awaiting_pix_rail`: due for refund by Pix, waiting for the Pix refund of Collect charges, which is not wired yet; no money has moved. `manual_refund_required`: due for refund and there is no Pix to return, so a person refunds it outside CodeSpar. | ```bash curl -X POST https://api.codespar.dev/v1/collect/payments/{paymentId}/honor \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http POST /v1/collect/payments/{paymentId}/honor HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/payments/{paymentId}/honor", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/payments/{paymentId}/honor", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.post("/v1/collect/payments/{paymentId}/honor", { path: { paymentId: "payment_0000000000000000" } }); ``` ```json title="application/json" { "id": "obj_0000000000000000", "object": "collect_refund", "payment_id": "payment_0000000000000000", "link_id": "link_0000000000000000", "charge_id": "charge_0000000000000000", "reason": "late", "refund_method": "pix", "state": "awaiting_collector", "amount_minor": 1000, "currency": "BRL", "decide_by": "string", "decided_at": "string", "created_at": "string" } ``` ### GET `/v1/collect/receivers` The consumers that could receive a Collect charge in this project The accounts a link may name as `consumer_id`, each decided by the publish gate's own rule in this project's environment: the consumer's own active Celcoin receiving identity (`identity: own`), or, in a test project only, the deployment's shared-sandbox receiver (`identity: shared_sandbox`). An ineligible consumer carries `reason: receiving_identity_missing`, the code a publish would answer. The candidates are the consumers this project already knows: an active directed-pay wallet in the project, a Pix (Celcoin) funding source attached to it, or one of its Collect links. At most 200, by consumer id. **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | Bad Request. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | — | | `environment` | `"live"` \| `"test"` | yes | The environment eligibility was decided for: this project's. | | `object` | `"list"` | yes | — | ```bash curl -X GET https://api.codespar.dev/v1/collect/receivers \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/receivers HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/receivers", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/receivers", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/receivers"); ``` ```json title="application/json" { "object": "list", "environment": "live", "data": [ { "consumer_id": "csm_0000000000000000", "label": "Example", "eligible": true, "identity": "own", "reason": "receiving_identity_missing" } ] } ``` ### GET `/v1/collect/{linkId}` The hosted page's read of a Collect link (public) No credential: the link id is the only thing the payer holds. Returns what a payer needs to pay and nothing else: the receiver's display name, items and total, brand, state, which payer fields the page must ask for (`payer_form`; a prefilled field reads `prefilled` and its value is never returned), the current attempt (its copia-e-cola only once `open`) and, once paid, the payment with its signed receipt. `environment` (`live` or `test`) is the link's: a test link moves no real money, and the page says so only when this field does. Rate limited per client IP and per link. A draft link answers 404; an archived, unpaid one 410. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `400` | object | The id is not a collect link id (`cl_` + 22 characters). | | `404` | object | No published link with that id. | | `410` | object | The owner withdrew the link. | | `429` | object | Too Many Requests. Per client IP and per link, shared by every API replica; `Retry-After` and `details.retry_after` give the wait, `details.scope` names which bucket refused. | ```bash curl -X GET https://api.codespar.dev/v1/collect/{linkId} \ -H "Authorization: Bearer $CODESPAR_API_KEY" ``` ```http GET /v1/collect/{linkId} HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY ``` ```python import os import requests res = requests.get( "https://api.codespar.dev/v1/collect/{linkId}", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/{linkId}", { method: "GET", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, }, }); const data = await res.json(); ``` ```ts const result = await cs.api.get("/v1/collect/{linkId}", { path: { linkId: "link_0000000000000000" } }); ``` ### POST `/v1/collect/{linkId}/attempts` Ask a Collect link for a payable Pix (public) The hosted page's POST. No credential. The body is strict: `page_session` (the page's idempotency key: the same session answers the same attempt, 200 with `replay: true`), the payer fields the page collected (never a field the charger prefilled), and `renew`. There is no amount field: the charge carries the published version's total. Payer data goes in this body only, never in a URL. Rate limited per client IP and per link, more tightly than the read, because every new attempt is a charge at the issuer. **Path parameters** | Name | Type | Required | Description | |---|---|---|---| | `linkId` | `string` | yes | — | **Request body** | Field | Type | Required | Description | |---|---|---|---| | `page_session` | `string` | yes | — | | `payer` | object | no | — | | `renew` | `boolean` | no | — | **Responses** | Status | Body | Description | |---|---|---| | `200` | object | OK | | `201` | object | OK | | `400` | object | Bad Request. | | `404` | object | No published link with that id. | | `409` | object | Conflict. | | `410` | object | The link is past its validity. | | `422` | object | The issuer refused the charge before it existed. | | `429` | object | Too Many Requests. Per client IP and per link, shared by every API replica; `Retry-After` and `details.retry_after` give the wait, `details.scope` names which bucket refused. | | `503` | object | The rate-limit store could not answer, and this route fails closed because its limit bounds charges created at the issuer. `Retry-After` gives the wait. | **Response `200`** | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | `integer` | yes | — | | `copy_paste` | `string,null` | yes | The Pix copia-e-cola. Null until the attempt is `open`: it does not exist before the issuer registers it. | | `currency` | `"BRL"` | yes | — | | `due_date` | `string` | yes | — | | `expires_at` | `string` | yes | — | | `failure_code` | `string,null` | no | — | | `id` | `string` | yes | — | | `ready_at` | `string,null` | yes | — | | `replay` | `true` | yes | — | | `retry_after` | `integer` | no | While `issuing`: seconds until the next readiness check. | | `state` | `"issuing"` \| `"open"` \| `"superseded"` \| `"expired"` \| `"cancelled"` \| `"paid"` \| `"failed"` | yes | — | | `surface` | `"page"` \| `"whatsapp"` | yes | — | ```bash curl -X POST https://api.codespar.dev/v1/collect/{linkId}/attempts \ -H "Authorization: Bearer $CODESPAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "page_session": "string", "payer": {}, "renew": false }' ``` ```http POST /v1/collect/{linkId}/attempts HTTP/1.1 Host: api.codespar.dev Authorization: Bearer $CODESPAR_API_KEY Content-Type: application/json { "page_session": "string", "payer": {}, "renew": false } ``` ```python import os import requests res = requests.post( "https://api.codespar.dev/v1/collect/{linkId}/attempts", headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"}, json={ "page_session": "string", "payer": {}, "renew": False }, ) res.raise_for_status() data = res.json() ``` ```ts const res = await fetch("https://api.codespar.dev/v1/collect/{linkId}/attempts", { method: "POST", headers: { Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "page_session": "string", "payer": {}, "renew": false }), }); const data = await res.json(); ``` ```ts const r = await cs.api.response("post", "/v1/collect/{linkId}/attempts", { path: { linkId: "link_0000000000000000" }, body: { page_session: "string", payer: {}, renew: false } }); // r.status is one of the documented statuses (200, 422), // each with its own body shape in r.data; nothing here throws on 422. if (r.ok) { console.log(r.data); } ``` ```json title="application/json" { "id": "obj_0000000000000000", "state": "issuing", "surface": "page", "amount_minor": 1000, "currency": "BRL", "due_date": "string", "expires_at": "string", "copy_paste": "string", "ready_at": "string", "retry_after": 0, "failure_code": "string", "replay": true } ```