How to Create a Card¶

This guide covers the per-cardholder half of card issuance: turning an existing card product into a card, and following it to ACTIVE. The one-time setup it depends on — product, layout, certified embosser — is Manage Card Products.

Time to complete: ~10 minutes
API: Issuer API — base path /api/issuer

Prerequisites¶

• An access token for an issuer tenant with the create-card or manage-card role. See Authentication.
• An issuable product. It must be active and have a layout with an approved embosser. Confirm with GET /api/issuer/card-products/issuing-data — a product missing from that list cannot issue a card. See Manage Card Products.
• The ledger accounts the card will be backed by. Which endpoint you call depends on whose ledger holds them — see the next section.

export TOKEN="eyJhbGci..."
export BASE="https://sandbox.qpay.quecto.com.br"
export ISSUER="$BASE/api/issuer"

Which endpoint issues your card¶

A card is worthless without accounts behind it, so who holds those accounts decides where you start.

Overview¶

flowchart TD
    A[Import a certificate - once] --> B[Pick the product and layout]
    B --> C[Create the card]
    C --> D[Monitor status]
    C -. optional .-> P[Supply your own PIN]

Step 1 — Import a certificate (once per issuer)¶

QPay uses your issuer certificate to establish trust for the cryptographic operations that happen during authorization — ARQC validation and ARPC generation — and it is what a caller-supplied PIN block is keyed against. Import one before issuing cards.

Generate an ECC P-256 certificate signing request with your HSM or openssl:

openssl ecparam -name prime256v1 -genkey -noout -out issuer.key
openssl req -new -key issuer.key -out issuer.csr \
  -subj "/CN=My Issuer/O=My Organization/C=BR"

# Base64-encode the CSR (single line, no line breaks)
CSR_B64=$(base64 -w 0 issuer.csr)

Submit it:

curl -s -X POST $ISSUER/certificates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"certificate_request_pem\": \"$CSR_B64\"}" | tee cert.json

Example response:

{
  "certificate_id": 42,
  "hsm_key_reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "certificate_pem_base64": "LS0tLS1CRUdJTi..."
}

export CERT_ID=$(jq -r '.certificate_id' cert.json)

GET /api/issuer/certificates lists your certificates with an expires_at for each — rotate before that date, or authorization begins failing. This step is only needed once, and again at rotation.

Step 2 — Pick the product and layout¶

curl -s $ISSUER/card-products/issuing-data \
  -H "Authorization: Bearer $TOKEN" | jq .

[
  {
    "product_id": 101,
    "name": "Classic Debit",
    "description": "Standard UnionPay debit card",
    "currency_numeric_code": 986,
    "layouts": [ { "layout_id": 15, "prints_pan_on_face": false } ],
    "credit_application_aids": []
  }
]

export PRODUCT_ID=101
export LAYOUT_ID=15

This listing is already filtered to what can be issued today, so anything it returns will pass the checks in Step 3. If your product is absent, go back to Manage Card Products — it is inactive, has no layout, or has no approved embosser on one.

Step 3 — Create the card¶

curl -s -X POST $ISSUER/cards/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"product_id\": $PRODUCT_ID,
    \"layout_id\": $LAYOUT_ID,
    \"reference_id\": \"MY-UNIQUE-REF-001\",
    \"card_holder_name\": \"JOAO DA SILVA\",
    \"billing_address\": {
      \"name\": \"Joao da Silva\",
      \"postal_code\": \"01310-100\",
      \"country\": \"BR\",
      \"state\": \"SP\",
      \"city\": \"São Paulo\",
      \"address_line1\": \"Av. Paulista 1000\",
      \"address_line2\": \"Apto 42\"
    },
    \"shipping_address\": {
      \"name\": \"Joao da Silva\",
      \"postal_code\": \"01310-100\",
      \"country\": \"BR\",
      \"state\": \"SP\",
      \"city\": \"São Paulo\",
      \"address_line1\": \"Av. Paulista 1000\",
      \"address_line2\": \"Apto 42\"
    },
    \"account_links\": {
      \"A0000003330101\": {
        \"account_id\": \"0192f3b2-1111-7000-9c4e-1f2a3b4c5d61\",
        \"float_account_id\": \"0192f3b2-2222-7000-9c4e-1f2a3b4c5d62\"
      }
    }
  }" | jq .

Request fields:

Example response:

{
  "reference_number": "MY-UNIQUE-REF-001",
  "card_id": 5821,
  "embosser_id": 3,
  "status": "PRODUCTION_STATUS_APPROVED",
  "embossing_status": "EMBOSSING_PENDING"
}

export CARD_ID=5821

reference_number echoes the reference_id you sent, so you can reconcile the response against your own record. errors appears only when there are any.

Step 4 — Monitor card status¶

curl -s $ISSUER/cards/$CARD_ID \
  -H "Authorization: Bearer $TOKEN" | jq .

GET /api/issuer/cards lists every card with its product, layout, BIN and per-application status.

Card status lifecycle:

PROVISIONED  →  ACTIVE
                  ↓
              FROZEN  ←→  ACTIVE
                  ↓
        BLOCKED     CANCELLED

A card leaves PROVISIONED when the embosser reports progress through the Embosser API — nothing advances it on its own, in the sandbox or anywhere else. If your cards sit at PROVISIONED, the bureau has not reported yet.

Advanced — supply your own PIN¶

Omitting pin is the normal path: the HSM generates a random PIN and the cardholder gets it through your usual channel. Supply one only when the cardholder chose it in your own environment — QPay never accepts a plaintext PIN.

Your HSM must, inside your secure environment:

1. Fetch the QPay HSM public key certificate and use it to agree a key:

   curl -s $ISSUER/key-agreement \
     -H "Authorization: Bearer $TOKEN" | jq -r .cert
   

2. Build an ISO 9564 PIN block for the cardholder's PIN, and encipher it under the PIN encryption key derived from that agreement.

3. Sign your ephemeral public key with the private key of the certificate from Step 1.

Then add a pin object to the Step 3 body:

"pin": {
  "enciphered_pin_block": "A1B2C3D4E5F60708",
  "incoming_pek": {
    "key_reference": "my-hsm-key-alias",
    "wrapped_key": {
      "wrapped_key_type": "ECC",
      "ecc_wrapped_key": {
        "ca_public_key_identifier": "42",
        "signed_public_key": "LS0tLS1CRUdJTi...",
        "derived_key_algorithm": "3DES_3KEY",
        "derivation_function": "NIST_SP800_108",
        "derivation_hash_algorithm": "SHA_256",
        "shared_information": "3f1a...64 hex characters..."
      }
    }
  }
}

A TR-31 key block is accepted instead: "wrapped_key_type": "TR31" with "tr31_wrapped_key": { "key_block": "..." }.

Issuing multiple cards (batch)¶

For bulk issuance use the batch endpoint rather than looping over /cards/create:

POST $ISSUER/cards/create/batch/{product_id}

The body takes a request_id (your idempotency key) and card_batch_info, an array whose entries carry the same per-card fields as above — reference_id, cardholder_name, layout_id, both addresses, account_links, and optionally pin. The response returns a batch_id and a per-card status, which you poll:

GET $ISSUER/cards/create/batch/{product_id}/{batch_id}

A batch is accepted whole (ACCEPTED), in part (PARTIAL), or not at all (REJECT) — always read the per-card statuses, since a partial batch still produced cards.

Related¶

• Manage Card Products — the product, layout and embosser this guide assumes
• Use the QPay Ledger — issuing a card whose accounts QPay holds
• Connect Your Own Ledger — issuing against your own accounts
• Issuer API reference — interactive endpoint documentation
• Credentials & authentication — token management