Account Applications

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

POST /v1/account-applications

Open a consumer account application

Opens a consumer's account application at the provider, and this is the path by which a consumer comes to have an account and a Pix funding source.

The response is not the account, it is the application. What comes back is verification_id and a status from the provider; the account and the funding source appear when GET /v1/account-applications/{id} is read after the approval: that read is what provisions. A flow that expects an account here keeps waiting.

The disclosure is there to be rendered. It names the institution that holds the account and CodeSpar's role as BaaS tomadora; the text comes in pt-BR to appear as it is, not to be rewritten.

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/account-applications \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "buyer": {},
       "consumer_id": "csm_0000000000000000",
       "opt_ins": [
         "string"
       ]
     }'

POST /v1/account-applications HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "buyer": {},
  "consumer_id": "csm_0000000000000000",
  "opt_ins": [
    "string"
  ]
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/account-applications",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "buyer": {},
      "consumer_id": "csm_0000000000000000",
      "opt_ins": [
        "string"
      ]
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/account-applications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "buyer": {},
    "consumer_id": "csm_0000000000000000",
    "opt_ins": [
      "string"
    ]
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/account-applications", {
  body: {
    buyer: {},
    consumer_id: "csm_0000000000000000",
    opt_ins: [
      "string"
    ]
  }
});
// r.status is one of the documented statuses (200, 403, 422),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "verification_id": "verification_0000000000000000",
  "status": "string",
  "hosted_url": "https://example.com/hook",
  "disclosure": {
    "institution": "string",
    "institution_document": "string",
    "codespar_role": "tomadora",
    "text": "string"
  },
  "next_step": {
    "code": "in_review_check_later",
    "verification_id": "verification_0000000000000000",
    "message": "string",
    "retry_after_seconds": 0
  },
  "sample_files": true,
  "already_submitted": true,
  "dda_opt_in": {
    "status": "pending",
    "message": "string"
  }
}

GET /v1/account-applications/{id}

Read the status of a consumer account application

Where a consumer's account onboarding stands, and — once the provider has approved it — the account and the Pix funding source it produced. Requires the kyc:read scope.

THIS IS NOT A PURE READ, and a caller should plan around that. On the approved branch the handler resolves the account from the provider and then persists: it inserts (or re-resolves) the consumer's pix-celcoin funding source, registers a Pix key for it, and anchors the consumer record. Every approval path in the product converges on that one place, so polling this endpoint is how an application becomes a usable funding source. It is idempotent — the funding source id is derived from the consumer id, and re-provisioning merges into the existing row rather than replacing it, so a Pix key already registered is not erased.

document_number IS REQUIRED, and the reason is ownership. It is never used to address the provider: the handler loads the proposal recorded under this id and compares. A mismatch, or an id with no recorded proposal, is refused before any provider call and provisions nothing — the attack it closes is an attacker's own approved proposal presented with a victim's document.

THOSE OWNERSHIP REFUSALS ARRIVE AS 409 with their own code (document_ownership_unproven, onboarding_document_mismatch), and so does a proposal recorded under ANOTHER project of the organization, in the same words as an unknown id. Only RESOURCE_CREATED binds an account; the proposal is read a bounded number of times when it is not visible yet, and an inconclusive read answers pending with next_step, never a new proposal.

The query is NOT schema-validated. The handler reads request.query directly and checks only that document_number is present; any other parameter is ignored rather than rejected.

Path parameters

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account-applications/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account-applications/{id} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account-applications/{id}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/account-applications/{id}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const r = await cs.api.response("get", "/v1/account-applications/{id}", {
  path: {
    id: "accountapplication_0000000000000000"
  },
  query: {
    document_number: "string"
  }
});
// 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);
}

{
  "status": "pending",
  "proposal_status": "string",
  "next_step": {
    "code": "in_review_check_later",
    "verification_id": "verification_0000000000000000",
    "message": "string",
    "retry_after_seconds": 0
  },
  "rejected_reason": "string",
  "hosted_url": "https://example.com/hook",
  "account": "string",
  "funding_source_id": "fundingsource_0000000000000000",
  "funding_source_status": "active",
  "pix_key": "string",
  "pix_key_type": "string",
  "pix_key_registration_error": "string"
}