Issue payment card

post

https://api.banking.netevia.dev/netevia/paymentCard

Issue Payment Card

This endpoint issues a new payment card for a customer within the Netevia Banking platform. It supports both initial card issuance and reissuance (for lost, stolen, or damaged cards), and handles physical and virtual card types. On success, it returns card details including the financial account association.

Endpoint

POST /netevia/paymentCard

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 onboarding a new customer who needs a payment card linked to their financial account, or when reissuing a replacement card due to loss, theft, or expiration. For physical cards, supply cardDeliveryDetails to specify the shipping name and address. For virtual cards, set physical to false and omit delivery details.

Request Body

The request body accepts one of two schemas: Issue Payment Card (new card) or Reissue Payment Card (replacement card). The reissue schema extends the issue schema with additional reissuance fields.

Issue Payment Card (`issuepaymentcard`)

Field	Type	Required	Description
profileId	integer (int32)	Yes	The customer profile ID to issue the card for
subProfileId	integer (int32)	No	Authorized user (subProfile) ID; business customers only
financialAccount	string	No	The financial account ID to associate the card with
physical	boolean	Yes	`true` for a physical (plastic) card; `false` for a virtual card
activateNow	boolean	No	If `true`, activates the card immediately upon issuance
expirationDate	string (date-time)	No	Desired expiration date/time for the card (ISO 8601)
shipping	string	No	Shipping method for physical cards (e.g., `"STANDARD"`, `"EXPEDITED"`)
last4	string	No	Last 4 digits of an existing card, used for reissuance matching
paymentCardId	string	No	Existing payment card ID, used when reissuing a specific card
cardProfileSetId	string	No	Card profile set identifier for card program selection
partnerId	integer (int32)	No	Partner ID override; defaults to the authenticated partner
cardDeliveryDetails	object	No	Required for physical cards — cardholder name and shipping address
cardDeliveryDetails.name	object	Yes (if cardDeliveryDetails)	Cardholder name for delivery
cardDeliveryDetails.name.givenName	string	Yes	Cardholder first name
cardDeliveryDetails.name.familyName	string	Yes	Cardholder last name
cardDeliveryDetails.companyName	string	Yes (if cardDeliveryDetails)	Company name printed on or associated with the card
cardDeliveryDetails.address	object	Yes (if cardDeliveryDetails)	Shipping address for the physical card
cardDeliveryDetails.address.streetAddress	string	Yes	Street address (must begin with a number)
cardDeliveryDetails.address.extendedAddress	string	No	Apartment, suite, unit, or additional address line
cardDeliveryDetails.address.locality	string	Yes	City
cardDeliveryDetails.address.region	string	Yes	2-letter state/region code (e.g., `"TX"`)
cardDeliveryDetails.address.postalCode	string	Yes	5-digit ZIP code (e.g., `"78701"`)
cardDeliveryDetails.address.countryCodeAlpha3	string	Yes	ISO 3166-1 alpha-3 country code (e.g., `"USA"`)

Reissue Payment Card (`reissuepaymentcard`)

Inherits all fields from issuepaymentcard, plus:

Field	Type	Required	Description
reason	string	No	Reason for reissuance (e.g., `"LOST"`, `"STOLEN"`, `"DAMAGED"`)
keepSpendingLimits	boolean	No	If `true`, carries over existing spending limits to the new card
paymentCardName	string	No	Display name for the reissued card

Example — Issue a physical card:

{
  "profileId": 100234,
  "financialAccount": "fa_9b3e2f1a4c",
  "physical": true,
  "activateNow": false,
  "shipping": "STANDARD",
  "cardDeliveryDetails": {
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "companyName": "Acme Corp",
    "address": {
      "streetAddress": "123 Main St",
      "extendedAddress": "Suite 400",
      "locality": "Austin",
      "region": "TX",
      "postalCode": "78701",
      "countryCodeAlpha3": "USA"
    }
  }
}

Example — Issue a virtual card:

{
  "profileId": 100234,
  "financialAccount": "fa_9b3e2f1a4c",
  "physical": false,
  "activateNow": true
}

Example — Reissue a lost card:

{
  "profileId": 100234,
  "paymentCardId": "pc_7f2a1b8d3e",
  "financialAccount": "fa_9b3e2f1a4c",
  "physical": true,
  "activateNow": false,
  "reason": "LOST",
  "keepSpendingLimits": true,
  "paymentCardName": "Jane Business Card",
  "shipping": "EXPEDITED",
  "cardDeliveryDetails": {
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "companyName": "Acme Corp",
    "address": {
      "streetAddress": "456 Commerce Blvd",
      "locality": "Dallas",
      "region": "TX",
      "postalCode": "75201",
      "countryCodeAlpha3": "USA"
    }
  }
}

Response

200 OK

The response may be one of two shapes depending on whether a new financial account was opened as part of the card issuance.

`boardingresponse`

Field	Type	Description
profileId	integer (int32)	The customer profile ID the card was issued to
success	boolean	`true` if the card was successfully issued
errors	string	Error message if `success` is `false`; `null` otherwise
changeLog	array	List of change log entries describing actions performed during boarding
changeLog[].requestType	integer (int32)	Numeric code identifying the type of boarding request performed
changeLog[].changes	string	Description of the change applied

`openfinancialaccountresponse` (extends `boardingresponse`)

Field	Type	Description
financialAccountId	string	ID of the financial account opened as part of this card issuance
profileId	integer (int32)	The customer profile ID
success	boolean	`true` if the card was successfully issued
errors	string	Error message if `success` is `false`; `null` otherwise
changeLog	array	List of change log entries

{
  "profileId": 100234,
  "success": true,
  "errors": null,
  "changeLog": [
    {
      "requestType": 5,
      "changes": "Payment card issued and linked to financial account fa_9b3e2f1a4c"
    }
  ]
}

{
  "financialAccountId": "fa_9b3e2f1a4c",
  "profileId": 100234,
  "success": true,
  "errors": null,
  "changeLog": [
    {
      "requestType": 5,
      "changes": "Payment card issued; new financial account opened"
    }
  ]
}

Error Codes

Code	When it happens
400	Missing required fields, invalid address format, invalid postal code, or malformed date-time
401	Token missing, expired, or invalid
403	Insufficient permissions to issue a card for the given profile or subProfile
404	profileId, subProfileId, financialAccount, or paymentCardId not found
500	Internal server error

Common Mistakes

Omitting cardDeliveryDetails when physical is true — physical cards require a full delivery name and address
Providing a postalCode with fewer or more than 5 digits — the API strictly validates the 5-digit format
Using a 2-character country code instead of the required ISO 3166-1 alpha-3 format (e.g., using "US" instead of "USA")
Setting subProfileId for a personal customer — authorized users (subProfiles) are only supported for business customer profiles
Sending paymentCardId and last4 together without a reissuance context — use the reissue schema when replacing an existing card
Forgetting to set activateNow: true for virtual cards that should be immediately usable after issuance

Related Endpoints

POST /api/auth/v2 — Obtain a Bearer token for authentication
POST /api/auth/refresh — Refresh an expiring Bearer token
GET /netevia/paymentCard/{paymentCardId} — Retrieve details for an existing payment card
PUT /netevia/paymentCard/{paymentCardId} — Update payment card settings or spending limits
POST /netevia/profile — Create a new customer profile before issuing a card

Example

Issue a physical card for a business customer:

curl -X POST https://api.banking.netevia.dev/netevia/paymentCard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": 100234,
    "financialAccount": "fa_9b3e2f1a4c",
    "physical": true,
    "activateNow": false,
    "shipping": "STANDARD",
    "cardDeliveryDetails": {
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "companyName": "Acme Corp",
      "address": {
        "streetAddress": "123 Main St",
        "extendedAddress": "Suite 400",
        "locality": "Austin",
        "region": "TX",
        "postalCode": "78701",
        "countryCodeAlpha3": "USA"
      }
    }
  }'

Issue a virtual card (activate immediately):

curl -X POST https://api.banking.netevia.dev/netevia/paymentCard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": 100234,
    "financialAccount": "fa_9b3e2f1a4c",
    "physical": false,
    "activateNow": true
  }'

Reissue a lost card:

curl -X POST https://api.banking.netevia.dev/netevia/paymentCard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": 100234,
    "paymentCardId": "pc_7f2a1b8d3e",
    "financialAccount": "fa_9b3e2f1a4c",
    "physical": true,
    "activateNow": false,
    "reason": "LOST",
    "keepSpendingLimits": true,
    "paymentCardName": "Jane Business Card",
    "shipping": "EXPEDITED",
    "cardDeliveryDetails": {
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "companyName": "Acme Corp",
      "address": {
        "streetAddress": "456 Commerce Blvd",
        "locality": "Dallas",
        "region": "TX",
        "postalCode": "75201",
        "countryCodeAlpha3": "USA"
      }
    }
  }'

Body Params

expirationDate

date-time

activateNow

boolean

profileId

int32

subProfileId

int32 | null

isMain

boolean | null

financialAccount

string | null

physical

boolean

shipping

string | null

last4

string | null

paymentCardId

string | null

cardProfileSetId

string | null

partnerId

int32 | null

cardDeliveryDetails

object

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

content-type

string

enum

Defaults to application/json

Generated from available request content types

Allowed:

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