Tutorial: Issue your first card¶

This tutorial walks an issuer tenant through the complete flow — from authenticating to creating a card product and issuing a card — using the QPay sandbox.

Prerequisites:

• You have a sandbox tenant with the issuer role — see Getting started
• You have a client_id and client_secret — see Creating client credentials
• curl and jq installed locally

1. Get an access token¶

TOKEN=$(curl -s -X POST \
  https://sandbox.qpay.quecto.com.br/auth/realms/qpay/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  | jq -r '.access_token')

Confirm it works:

curl https://sandbox.qpay.quecto.com.br/credentials/whoami \
  -H "Authorization: Bearer $TOKEN" | jq .

Expected response:

{
  "tenant_type": "issuer",
  "tenant_id": "your-issuer-tenant-id",
  "parent_tenant_id": "your-processor-tenant-id"
}

2. Browse available card templates¶

Your processor has configured one or more data preparation templates (BIN-level card configurations). List the templates available to your issuer:

curl "https://sandbox.qpay.quecto.com.br/issuer/card-products/templates" \
  -H "Authorization: Bearer $TOKEN" | jq .

Pick a template and note its id. You will reference it when creating your card product.

3. Create a card layout¶

A card layout defines the graphic and physical characteristics of the card (artwork, embossing fields, delivery inputs). Create one:

curl -X POST https://sandbox.qpay.quecto.com.br/issuer/card-layouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Layout",
    "description": "Tutorial card layout"
  }' | jq .

Note the id returned — this is your layout_id.

4. Create a card product¶

A card product combines a template with a layout and defines service-level options:

curl -X POST https://sandbox.qpay.quecto.com.br/issuer/card-products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Product",
    "template_id": "TEMPLATE_ID_FROM_STEP_2",
    "layout_id": "LAYOUT_ID_FROM_STEP_3"
  }' | jq .

Note the id — this is your product_id.

5. Issue a card¶

With a product in place, issue a card for a cardholder:

curl -X POST https://sandbox.qpay.quecto.com.br/issuer/cards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "PRODUCT_ID_FROM_STEP_4",
    "cardholder_name": "JOAO DA SILVA",
    "cardholder_document": "12345678900"
  }' | jq .

The response contains a card_id and the card status (pending_embossing). In the sandbox, the embossing step is simulated automatically.

6. Check card status¶

curl https://sandbox.qpay.quecto.com.br/issuer/cards/CARD_ID \
  -H "Authorization: Bearer $TOKEN" | jq .

When the simulated embosser processes the card, the status transitions to active.

What's next?¶

• Certificates — add HSM certificates to your issuer for cryptographic operations during authorization
• Embossing jobs — if you manage your own embosser, see the Embosser API to poll and confirm jobs
• Transactions — see the Issuer Simulator API to simulate authorization callbacks during development

Browse the full API Reference to explore all available endpoints.