Order Physical card with required parameters (V2)

post

https://api.banking.netevia.dev/api/paymentCards/v2/orderPhysicalPaymentCard

Order Physical Payment Card (V2)

This endpoint initiates the order of a physical payment card linked to a specified financial account. Partners supply delivery recipient details, a shipping method, and optional notification preferences to trigger card production and dispatch. Upon success, the API returns an order record including status, shipment details, and the new physical card ID.

Endpoint

POST /api/paymentCards/v2/orderPhysicalPaymentCard

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a customer needs a physical card shipped to a specific address. It supports both personal and business customers, and allows business customers to order cards for authorized users (subProfiles). Specify a shipping method to control delivery speed, from standard USPS ground to UPS next-day.

Request Body

Top-level fields

Field	Type	Required	Description
financialAccountId	string	Yes	ID of the financial account the card will be linked to
deliveryDetails	object	Yes	Recipient name, company, and delivery address
courier	object	No	Shipping method selection
paymentCardName	string	No	Custom name to print or label on the card
subProfileId	integer	No	ID of the authorized user (subProfile) to issue the card to (business customers only)
cardProfileSetId	string	No	Card profile set override; uses account default if omitted
isEmailEnable	boolean	No	Enable email notifications for card activity
isPushEnable	boolean	No	Enable push notifications for card activity

deliveryDetails object (required)

Field	Type	Required	Description
name	object	Yes	Recipient name (see name object below)
companyName	string	Yes	Company name for delivery label
address	object	Yes	Delivery address (see address object below)

deliveryDetails.name object

Field	Type	Required	Description
givenName	string	Yes	Recipient first name
familyName	string	Yes	Recipient last name

deliveryDetails.address object

Field	Type	Required	Description
streetAddress	string	Yes	Street number and name; must match pattern `^\d+([\s/-]?[A-z\d/]2
extendedAddress	string	No	Apartment, suite, unit number, etc.
postalCode	string	Yes	5-digit US ZIP code (pattern: `^\d{5}$`)
region	string	Yes	2-letter US state code (e.g., `FL`)
locality	string	Yes	City name
countryCodeAlpha3	string	Yes	ISO 3166-1 alpha-3 country code, exactly 3 characters (e.g., `USA`)

courier object (optional)

Field	Type	Required	Description
method	string	No	Shipping method. Allowed values: `USPS_GROUND`, `USPS_PRIORITY`, `USPS_EXPRESS`, `UPS_GROUND`, `UPS_SECOND_DAY`, `UPS_NEXT_DAY`

{
  "financialAccountId": "fa_abc123def456",
  "deliveryDetails": {
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "companyName": "Acme Corp",
    "address": {
      "streetAddress": "123 Main St",
      "extendedAddress": "Suite 400",
      "postalCode": "33101",
      "region": "FL",
      "locality": "Miami",
      "countryCodeAlpha3": "USA"
    }
  },
  "courier": {
    "method": "UPS_GROUND"
  },
  "paymentCardName": "Jane Smith",
  "subProfileId": null,
  "isEmailEnable": true,
  "isPushEnable": false
}

Response

200 OK

Field	Type	Description
orderPhysicalPaymentCard	object	Physical card order record
orderPhysicalPaymentCard.id	string	Unique order ID
orderPhysicalPaymentCard.orderState	object	Current order status
orderPhysicalPaymentCard.orderState.status	string	Order status string (e.g., `PENDING`, `ISSUED`, `SHIPPED`)
orderPhysicalPaymentCard.physicalPaymentCardId	string	ID of the newly created physical payment card
orderPhysicalPaymentCard.subProfileId	integer	SubProfile ID if card was ordered for an authorized user
orderPhysicalPaymentCard.cardPersonalization	object	Card personalization details
orderPhysicalPaymentCard.cardPersonalization.textLines	object	Text lines printed on the card
orderPhysicalPaymentCard.cardPersonalization.textLines.line1	string	First line of card text
orderPhysicalPaymentCard.cardPersonalization.textLines.line2	string	Second line of card text
orderPhysicalPaymentCard.paymentCardShipment	object	Shipment details
orderPhysicalPaymentCard.paymentCardShipment.courier	object	Courier and tracking information
orderPhysicalPaymentCard.paymentCardShipment.courier.method	string	Shipping method selected
orderPhysicalPaymentCard.paymentCardShipment.courier.signatureRequiredOnDelivery	boolean	Whether a signature is required upon delivery
orderPhysicalPaymentCard.paymentCardShipment.courier.tracking	object	Tracking details
orderPhysicalPaymentCard.paymentCardShipment.courier.tracking.trackingNumber	string	Carrier tracking number
orderPhysicalPaymentCard.paymentCardShipment.courier.tracking.actualShipDateLocal	string (date-time)	Actual ship date in local time
orderPhysicalPaymentCard.paymentCardShipment.requestedShipDate	string (date-time)	Requested ship date
orderPhysicalPaymentCard.paymentCardShipment.senderDetails	object	Sender name and address
orderPhysicalPaymentCard.paymentCardShipment.deliveryDetails	object	Recipient name and address
orderPhysicalPaymentCard.stateHistory	array	History of order state transitions
orderPhysicalPaymentCard.stateHistory[].previousStatus	string	State before the transition
orderPhysicalPaymentCard.stateHistory[].newStatus	string	State after the transition
orderPhysicalPaymentCard.stateHistory[].createdAt	string (date-time)	Timestamp of the transition
orderPhysicalPaymentCard.createdAt	string (date-time)	Order creation timestamp
orderPhysicalPaymentCard.updatedAt	string (date-time)	Order last updated timestamp
orderPhysicalPaymentCard.errors	array	Mutation-level errors if the order could not be placed
mutationResult	object	Mutation result wrapper
mutationResult.errors	array	List of user-facing errors
mutationResult.errors[].path	array of strings	JSON path to the field that caused the error
mutationResult.errors[].code	string	Error code
mutationResult.errors[].description	string	Human-readable error description

{
  "orderPhysicalPaymentCard": {
    "id": "order_9f8e7d6c5b4a",
    "orderState": {
      "status": "PENDING"
    },
    "physicalPaymentCardId": "card_1a2b3c4d5e6f",
    "subProfileId": null,
    "cardPersonalization": {
      "textLines": {
        "line1": "Jane Smith",
        "line2": "Acme Corp"
      }
    },
    "paymentCardShipment": {
      "courier": {
        "method": "UPS_GROUND",
        "signatureRequiredOnDelivery": false,
        "tracking": {
          "trackingNumber": null,
          "actualShipDateLocal": "0001-01-01T00:00:00"
        }
      },
      "requestedShipDate": null,
      "senderDetails": {
        "name": {
          "givenName": "Netevia",
          "familyName": "Banking",
          "title": null,
          "suffix": null,
          "middleName": null
        },
        "companyName": "Netevia",
        "address": {
          "streetAddress": "1 Netevia Way",
          "extendedAddress": null,
          "postalCode": "33101",
          "locality": "Miami",
          "region": "FL",
          "countryCodeAlpha3": "USA"
        }
      },
      "deliveryDetails": {
        "name": {
          "givenName": "Jane",
          "familyName": "Smith",
          "title": null,
          "suffix": null,
          "middleName": null
        },
        "companyName": "Acme Corp",
        "address": {
          "streetAddress": "123 Main St",
          "extendedAddress": "Suite 400",
          "postalCode": "33101",
          "locality": "Miami",
          "region": "FL",
          "countryCodeAlpha3": "USA"
        }
      }
    },
    "stateHistory": [],
    "createdAt": "2026-06-08T14:30:00Z",
    "updatedAt": null,
    "errors": []
  },
  "mutationResult": {
    "errors": []
  }
}

Error Codes

Code	When it happens
400	Missing required fields (`financialAccountId`, `deliveryDetails`, `name`, `address`), invalid `postalCode` format, invalid `region` length, invalid `countryCodeAlpha3` length, or unrecognized `courier.method` value
401	Token missing, expired, or invalid
403	Insufficient permissions to order a card for this account or subProfile
404	`financialAccountId` or `subProfileId` not found
500	Internal server error

Common Mistakes

Providing a postalCode that is not exactly 5 digits — the API enforces ^\d{5}$ strictly; do not use ZIP+4 format.
Setting region to the full state name instead of the 2-letter ISO code (e.g., use FL not Florida).
Setting countryCodeAlpha3 to an ISO alpha-2 code (e.g., US) — this field requires exactly 3 characters (e.g., USA).
Omitting companyName from deliveryDetails — it is a required field even for personal customer orders.
Passing subProfileId for a personal customer account — subProfiles are only available for business customers.
Using a courier.method value not in the allowed enum; the field is silently ignored if blank but will fail validation if an unrecognized string is provided.
Sending a streetAddress that does not match the required pattern (must begin with a house number).

Related Endpoints

POST /api/paymentCards/v2/orderVirtualPaymentCard — Order a virtual (digital-only) payment card
POST /api/paymentCards/v2/orderBurnerPaymentCard — Order a temporary burner payment card
GET /api/paymentCards/v2/getPaymentCard/{paymentCardId} — Retrieve details for an existing payment card
GET /api/paymentCards/v2/getPaymentCards — List all payment cards for a financial account
POST /api/financialAccounts/v2/createFinancialAccount — Create the financial account to link the card to

Example

curl -X POST https://api.banking.netevia.dev/api/paymentCards/v2/orderPhysicalPaymentCard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "financialAccountId": "fa_abc123def456",
    "deliveryDetails": {
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "companyName": "Acme Corp",
      "address": {
        "streetAddress": "123 Main St",
        "extendedAddress": "Suite 400",
        "postalCode": "33101",
        "region": "FL",
        "locality": "Miami",
        "countryCodeAlpha3": "USA"
      }
    },
    "courier": {
      "method": "UPS_GROUND"
    },
    "paymentCardName": "Jane Smith",
    "isEmailEnable": true,
    "isPushEnable": false
  }'

Response

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

text/plain

application/json

text/json

Order Physical Payment Card (V2)

Endpoint

Authentication

When to use

Request Body

Response

Error Codes

Common Mistakes

Related Endpoints

Example

200Success