Sign in
Card issuing request

Create a card issuing request

Creates a card issuing request. Requires the caller to be a member of the target company and either an admin or hold the card_issuing_requests_manage permission.

On creation the request runs an eligibility check (Cards::CardIssuingEligibilityChecker); if it fails, the endpoint returns 422 with { "message": <first error>, "errors": [...] }.

For physical CLP cards, recipient_name and shipping_address are required (model validation). budget_cents must be ≥ 1 and budget_currency a valid ISO-4217 currency.

post/v1/card_issuing_requests

Parameters

#/paths/~1v1~1merchants/get/parameters/0 — unresolved $ref

Request body

namestring

Display name for the card.

user_idstring required

Firebase user id of the future cardholder. Must belong to company_id.

company_idstring uuid required

UUID of the company the card belongs to.

budget_centsinteger required

Requested spending budget in cents. Must be at least 1.

budget_currencystring required

ISO-4217 code of the budget currency. Must be a valid currency.

interval'monthly' | 'daily'

Budget renewal interval. Defaults to monthly.

physicalboolean

Request a physical card. Defaults to false. Cannot be changed after creation.

purchase'national' | 'international' | 'both'

Allowed purchase geography.

recipient_namestring

Recipient full name. Required for physical CLP requests.

contact_phonestring

Contact phone for the physical shipment.

status'pending' | 'accepted' | 'declined' | 'printing' | 'printed' | 'sent' | 'delivered'

Initial status. Admin-only — ignored for non-admin callers.

Example request

{
  "name": "Marketing — María Pérez",
  "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "budget_cents": 500000,
  "budget_currency": "CLP",
  "interval": "monthly",
  "purchase": "both",
  "recipient_name": "María Pérez",
  "contact_phone": "+56912345678",
  "shipping_address": {
    "street": "Av. Apoquindo",
    "number": "4700",
    "municipality_id": 13114,
    "complement": "Oficina 501"
  }
}

Response

The created card issuing request.

idstring uuid
namestring nullable

Display name requested for the card.

user_idstring

Firebase user id of the future cardholder (not a UUID).

company_idstring uuid
status'pending' | 'accepted' | 'declined' | 'printing' | 'printed' | 'sent' | 'delivered'

Lifecycle of the request.

  • pending — created, awaiting approval / issuing.
  • accepted — a card was issued and linked (vendor_card_id is set).
  • declined — rejected.
  • printing / printed — physical card in production.
  • sent — dispatched to the cardholder (admin marks this).
  • delivered — cardholder self-confirmed receipt (see confirm_delivery).
budget_centsinteger

Requested spending budget in cents, in budget_currency.

budget_currencystring

ISO-4217 code of the requested budget currency.

interval'monthly' | 'daily'

Budget renewal interval for the resulting card.

physicalboolean

Whether a physical (plastic) card is requested. false for virtual-only.

purchase'national' | 'international' | 'both' nullable

Allowed purchase geography for the card.

vendor_idstring nullable

Issuing partner selected at approval time (e.g. plh, pomelo, slash).

vendor_card_idstring nullable

Id of the issued VendorCard once the request is accepted (vendor-prefixed string, not a UUID).

typestring nullable

STI subclass derived from vendor_id (e.g. Cards::Plh::Request).

recipient_namestring nullable

Recipient full name for physical shipments. Required for physical CLP requests.

contact_phonestring nullable

Contact phone for the physical shipment.

shipping_municipality_namestring nullable

Resolved municipality name for the shipping address (computed field).

kyc_completedboolean

Whether the owning company has completed KYC. Computed field. Serialized as the JSON key kyc_completed (the ? Ruby predicate suffix is stripped).

tracking_numberstring nullable

Carrier tracking number (staff-set). Only present for dispatched physical cards.

tracking_urlstring nullable

Carrier tracking URL (staff-set).

estimated_delivery_datestring date nullable

Estimated delivery date (staff-set).

shipment_idstring nullable

Vendor shipment identifier for physical cards.

printing_atstring date-time nullable

When the request entered the printing milestone.

sent_atstring date-time nullable

When the physical card was dispatched.

delivered_atstring date-time nullable

When the cardholder confirmed delivery.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "9f8b2c1d-4e5a-6b7c-8d9e-0f1a2b3c4d5e",
  "name": "Marketing — María Pérez",
  "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "budget_cents": 500000,
  "budget_currency": "CLP",
  "interval": "monthly",
  "purchase": "both",
  "vendor_id": "plh",
  "vendor_card_id": "Q2FyZDoxMDIwNjQ5Mw==",
  "type": "Cards::Plh::Request",
  "recipient_name": "María Pérez",
  "contact_phone": "+56912345678",
  "shipping_address": {
    "street": "Av. Apoquindo",
    "number": "4700",
    "municipality_id": 13114,
    "municipality_name": "Las Condes",
    "complement": "Oficina 501"
  },
  "shipping_municipality_name": "Las Condes",
  "kyc_completed": true,
  "tracking_number": "CL123456789",
  "tracking_url": "https://tracking.example.com/CL123456789",
  "estimated_delivery_date": "2026-08-01"
}

Changes