Physical Cards

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.

Physical card issuance requires a fully onboarded account with KYC approved, terms accepted, and wallet deployed. See the Onboarding Guide.

Type Definitions

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;
  };
}

Order a Physical Card

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

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

string

required

Your Yativo Card account ID.

object

required

The delivery address for the physical card.

string

required

Street address line 1.

string

Street address line 2 (apartment, suite, unit, etc.).

string

required

City name.

string

State or province code. Required for applicable countries.

string

required

Postal or ZIP code.

string

required

ISO 3166-1 alpha-2 country code (e.g., "DE", "GB", "US").

string

A label for this card (e.g., “Personal Card”). Defaults to the account holder name.

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"
    }
  }'

{
  "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"
  }
}

Attach Payment to Order

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

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

string

required

Your Yativo Card account ID.

string

required

The order ID returned when the order was created.

string

required

Payment method. Accepted values: "card_balance", "crypto".

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"
  }'

{
  "status": "success",
  "data": {
    "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
    "payment_status": "paid",
    "order_status": "processing",
    "amount_charged": 9.99,
    "currency": "USD"
  }
}

Get Order Status

Check the current status of a physical card order.

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

string

required

Your Yativo Card account ID.

string

required

The order ID to check.

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'

{
  "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"
  }
}

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

string

required

Your Yativo Card account ID.

curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "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
}

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

string

required

Your Yativo Card account ID.

string

required

The order ID to cancel.

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 '{}'

{
  "status": "success",
  "data": {
    "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
    "order_status": "cancelled",
    "cancelled_at": "2026-03-25T13:00:00Z",
    "refund_status": "pending"
  }
}

Set Physical Card PIN

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.

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:

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

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"] }'

Response

{
  "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:

<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>

The PIN updates the online PIN stored by the card network. The chip’s offline PIN syncs automatically on the first ATM transaction.

Setting a Card PIN

Complete flow for virtual and physical cards — PSE iframe, brand theming, pin_set monitoring, and webhook confirmation.

Delivery Timeframes

Delivery times are estimates and may vary based on destination country and carrier conditions.

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.

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.

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

{
  "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.

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 to let the cardholder set theirs immediately after activation, and use the same flow to change it later.

Overview

Wallets & Assets

Transactions

Yativo Card

Payment Gateway

Agentic Wallets

IBAN

Automation

Compliance

B2B

Developer Tools

Tutorials

SDKs

Browser Extensions (Coming Soon)

Sandbox

Physical Cards

Overview

Order a Physical Card

Attach Payment to Order

Get Order Status

Order Status Values

List All Orders

Cancel an Order

Set Physical Card PIN

Setting a Card PIN

Delivery Timeframes

Physical Card Activation

​Overview

​Order a Physical Card

​Attach Payment to Order

​Get Order Status

​Order Status Values

​List All Orders

​Cancel an Order

​Set Physical Card PIN

Setting a Card PIN

​Delivery Timeframes

​Physical Card Activation

Overview

Order a Physical Card

Attach Payment to Order

Get Order Status

Order Status Values

List All Orders

Cancel an Order

Set Physical Card PIN

Delivery Timeframes

Physical Card Activation