> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Physical Cards

> Order and manage physical payment cards delivered to your address

## Overview

Physical Yativo Cards are plastic payment cards delivered to a shipping address. They work anywhere the payment network is accepted — in-store, at ATMs, and for contactless payments. Physical card orders go through a fulfillment process before the card is shipped.

<Note>
  Physical card issuance requires a fully onboarded account with KYC approved, terms accepted, and wallet deployed. See the [Onboarding Guide](/yativo-crypto/cards/onboarding).
</Note>

<Accordion title="Type Definitions">
  ```typescript theme={null}
  interface PhysicalCardOrder {
    order_id: string;
    status: "pending" | "processing" | "shipped" | "delivered" | "cancelled";
    shipping_address: ShippingAddress;
    tracking_number?: string;
    estimated_delivery?: string;
    created_at: string;
  }

  interface ShippingAddress {
    line1: string;
    line2?: string;
    city: string;
    state?: string;
    postal_code: string;
    country: string; // ISO 3166-1 alpha-2
  }

  interface CreatePhysicalOrderRequest {
    shipping_address: ShippingAddress;
    personalization?: {
      name_on_card?: string;
    };
  }
  ```
</Accordion>

***

## Order a Physical Card

Submit an order for a physical card. A shipping address is required.

```
POST /yativo-card/{yativoCardId}/cards/physical/order
```

<ParamField path="yativoCardId" type="string" required>
  Your Yativo Card account ID.
</ParamField>

<ParamField body="shipping_address" type="object" required>
  The delivery address for the physical card.
</ParamField>

<ParamField body="shipping_address.line1" type="string" required>
  Street address line 1.
</ParamField>

<ParamField body="shipping_address.line2" type="string">
  Street address line 2 (apartment, suite, unit, etc.).
</ParamField>

<ParamField body="shipping_address.city" type="string" required>
  City name.
</ParamField>

<ParamField body="shipping_address.state" type="string">
  State or province code. Required for applicable countries.
</ParamField>

<ParamField body="shipping_address.postal_code" type="string" required>
  Postal or ZIP code.
</ParamField>

<ParamField body="shipping_address.country" type="string" required>
  ISO 3166-1 alpha-2 country code (e.g., `"DE"`, `"GB"`, `"US"`).
</ParamField>

<ParamField body="display_name" type="string">
  A label for this card (e.g., "Personal Card"). Defaults to the account holder name.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "display_name": "Jane'\''s Personal Card",
      "shipping_address": {
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "city": "Berlin",
        "postal_code": "10115",
        "country": "DE"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": {
      "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
      "status": "pending_payment",
      "display_name": "Jane's Personal Card",
      "shipping_address": {
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "city": "Berlin",
        "postal_code": "10115",
        "country": "DE"
      },
      "created_at": "2026-03-25T12:00:00Z"
    }
  }
  ```
</ResponseExample>

***

## Attach Payment to Order

After creating an order, submit payment to initiate card fulfillment.

```
POST /yativo-card/{yativoCardId}/cards/physical/order/{orderId}/payment
```

<ParamField path="yativoCardId" type="string" required>
  Your Yativo Card account ID.
</ParamField>

<ParamField path="orderId" type="string" required>
  The order ID returned when the order was created.
</ParamField>

<ParamField body="payment_method" type="string" required>
  Payment method. Accepted values: `"card_balance"`, `"crypto"`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order/ord_01HX9KZMB3F7VNQP8R2WDGT4F6/payment' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "payment_method": "card_balance"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": {
      "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
      "payment_status": "paid",
      "order_status": "processing",
      "amount_charged": 9.99,
      "currency": "USD"
    }
  }
  ```
</ResponseExample>

***

## Get Order Status

Check the current status of a physical card order.

```
GET /yativo-card/{yativoCardId}/cards/physical/order/{orderId}/status
```

<ParamField path="yativoCardId" type="string" required>
  Your Yativo Card account ID.
</ParamField>

<ParamField path="orderId" type="string" required>
  The order ID to check.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order/ord_01HX9KZMB3F7VNQP8R2WDGT4F6/status' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": {
      "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
      "order_status": "shipped",
      "tracking_number": "1Z999AA10123456784",
      "carrier": "DHL",
      "estimated_delivery": "2026-04-02",
      "shipped_at": "2026-03-27T08:00:00Z"
    }
  }
  ```
</ResponseExample>

### Order Status Values

| Status            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `pending_payment` | Order created, awaiting payment.                               |
| `processing`      | Payment received. Card is being manufactured and personalized. |
| `shipped`         | Card has been dispatched. Tracking number available.           |
| `delivered`       | Card confirmed delivered to the shipping address.              |
| `cancelled`       | Order was cancelled before shipment.                           |
| `failed`          | Order could not be fulfilled. Contact support.                 |

***

## List All Orders

Retrieve all physical card orders for a Yativo Card account.

```
GET /yativo-card/{yativoCardId}/cards/physical/orders
```

<ParamField path="yativoCardId" type="string" required>
  Your Yativo Card account ID.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/orders' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": [
      {
        "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
        "order_status": "shipped",
        "display_name": "Jane's Personal Card",
        "created_at": "2026-03-25T12:00:00Z",
        "shipped_at": "2026-03-27T08:00:00Z"
      }
    ],
    "total": 1
  }
  ```
</ResponseExample>

***

## Cancel an Order

Cancel a physical card order. Cancellation is only possible while the order is in `pending_payment` or `processing` status. Once shipped, orders cannot be cancelled.

```
POST /yativo-card/{yativoCardId}/cards/physical/order/{orderId}/cancel
```

<ParamField path="yativoCardId" type="string" required>
  Your Yativo Card account ID.
</ParamField>

<ParamField path="orderId" type="string" required>
  The order ID to cancel.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order/ord_01HX9KZMB3F7VNQP8R2WDGT4F6/cancel' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": {
      "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
      "order_status": "cancelled",
      "cancelled_at": "2026-03-25T13:00:00Z",
      "refund_status": "pending"
    }
  }
  ```
</ResponseExample>

***

## Set Physical Card PIN

<Note>
  The `pin_set` field in the view-token response tells you whether Yativo has received a `physical.card.pin.changed` webhook for this card. Use it to prompt the cardholder to set a PIN before their first chip-and-PIN or ATM transaction. The same view also handles PIN **changes**.
</Note>

Physical card PINs are set and changed through Yativo's **hosted secure page**, powered by the card network's Partner Secure Elements (PSE) service. The cardholder types their PIN directly inside a sandboxed iframe — your backend never receives or processes the PIN value.

**Flow:**

1. Your backend calls `POST /v1/yativo-card/{yativoCardId}/cards/{cardId}/view-token` with `enabled_views: ["pin"]`
2. You receive a `secure_view_url`
3. Open it in an `<iframe>` or WebView — the cardholder enters and confirms their 4-digit PIN
4. The card network fires a `physical.card.pin.changed` webhook → `pin_set` becomes `true` on the card record
5. Card details can now be displayed

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/card_phys_01HX9KZMB3F7VNQP8R2WDGT4F6/view-token' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "enabled_views": ["pin"] }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "pin_set": false,
    "enabled_views": ["pin"],
    "expires_at": "2026-05-18T12:05:00.000Z"
  }
}
```

Embed the URL in your frontend:

```html theme={null}
<iframe
  src="https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci..."
  title="Set Card PIN"
  width="420" height="520"
  style="border:0; border-radius:16px;"
  allow="clipboard-read; clipboard-write">
</iframe>
```

<Note>
  The PIN updates the **online PIN** stored by the card network. The chip's offline PIN syncs automatically on the first ATM transaction.
</Note>

<Card title="Setting a Card PIN" icon="lock" href="/yativo-crypto/cards/set-pin">
  Complete flow for virtual and physical cards — PSE iframe, brand theming, `pin_set` monitoring, and webhook confirmation.
</Card>

***

## Delivery Timeframes

<Info>
  Delivery times are estimates and may vary based on destination country and carrier conditions.
</Info>

| Region         | Estimated Delivery  |
| -------------- | ------------------- |
| Europe (EU)    | 5–10 business days  |
| United Kingdom | 5–10 business days  |
| North America  | 7–14 business days  |
| Rest of World  | 10–21 business days |

After your card is shipped, you will receive a tracking number via the order status endpoint and via email notification.

***

## Physical Card Activation

Before a physical card can be activated, a **12.00 USDC** one-time activation fee must be paid. Send 12 USDC (SPL) on Solana to your card wallet address. The fee is detected automatically — once confirmed, you can call the activation endpoint with your activation code.

<Note>
  Activation fees are subject to review and may change. The current fee will always be returned in the `402` response if payment is still outstanding.
</Note>

If the fee has not been paid, the activation endpoint returns `HTTP 402` with the payment address:

```json theme={null}
{
  "success": false,
  "error_code": "ACTIVATION_FEE_REQUIRED",
  "message": "A 12.00 USDC activation fee is required...",
  "data": {
    "fee_amount": "12.00",
    "fee_currency": "USDC",
    "payment_address": "SoLFundingWalletAddressXXX",
    "network": "solana",
    "fees_subject_to_review": true
  }
}
```

Once the payment is detected your activation call will succeed normally.

<Tip>
  Set your PIN as soon as your card arrives. Chip-and-PIN and ATM transactions will fail until a PIN is set. Use the [PIN setup flow](#set-physical-card-pin) to let the cardholder set theirs immediately after activation, and use the same flow to change it later.
</Tip>