Request New Payment Cards (Virtual or Physical)
The POST /api/paymentCards/v2/Issue endpoint allows partners to request the issuance of a new payment card — either virtual or physical — linked to a customer's financial account. Virtual cards are available for immediate use upon issuance, while physical cards are produced and mailed to the cardholder. The endpoint supports optional configuration such as card naming, activation behavior, and assignment to authorized subprofile users.
Endpoint
POST /api/paymentCards/v2/Issue
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include 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 new payment card issued against one of their financial accounts. This is the primary method for provisioning both virtual cards (for immediate digital use) and physical plastic cards (shipped to the cardholder). For business customers, cards can be issued to authorized subprofile users by providing a subProfileId.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| financialAccountId | string | Yes | The ID of the financial account to which the card will be linked. Minimum length: 1. |
| activateNow | boolean | No | If true, the card is activated immediately upon issuance. Defaults to platform behavior if omitted. |
| expirationDate | string (date-time) | No | Optional custom expiration date for the card in ISO 8601 format. If omitted, the platform assigns a default expiration. |
| paymentCardName | string | No | A display name or label for the card (e.g., "Travel Card", "Office Expenses"). |
| partnerId | integer (int32) | No | The partner ID associated with the issuance request. Use when issuing on behalf of a specific partner configuration. |
| cardProfileSetId | string | No | The card profile set identifier that defines card product settings, spending controls, and branding. |
| subProfileId | integer (int32) | No | For business customers only. The ID of the authorized subprofile user to whom the card will be issued. |
{
"financialAccountId": "fa_9b2c4e1d7a3f8b0e",
"activateNow": true,
"paymentCardName": "Operations Card",
"cardProfileSetId": "cps_virtual_standard",
"subProfileId": 4821
}Response
200 OK
| Field | Type | Description |
|---|---|---|
| success | boolean | Indicates whether the card issuance request was accepted. |
| paymentCardId | string | Unique identifier for the newly issued payment card. |
| status | string | Current status of the card (e.g., ACTIVE, PENDING_ACTIVATION, PENDING_FULFILLMENT). |
| cardType | string | Type of card issued: VIRTUAL or PHYSICAL. |
| last4 | string | Last four digits of the issued card number. |
| expirationDate | string | The expiration date assigned to the card. |
| financialAccountId | string | The financial account ID to which the card is linked. |
{
"success": true,
"paymentCardId": "pc_3d7f1a2b9c0e4f5d",
"status": "ACTIVE",
"cardType": "VIRTUAL",
"last4": "4782",
"expirationDate": "2027-12-31T23:59:59Z",
"financialAccountId": "fa_9b2c4e1d7a3f8b0e"
}Error Codes
| Code | When it happens |
|---|---|
| 400 | Missing financialAccountId, invalid field values, or malformed request body |
| 401 | Token missing, expired, or invalid |
| 403 | Insufficient permissions to issue a card for the specified account or subprofile |
| 404 | The specified financialAccountId or subProfileId does not exist |
| 500 | Internal server error |
Common Mistakes
- Omitting
financialAccountId— this is the only required field and the request will fail without it. - Passing
subProfileIdfor a personal customer account — subprofiles are only supported for business customers. - Sending an
expirationDatein the past or in an incorrect format — use ISO 8601 date-time (e.g.,2027-06-30T23:59:59Z). - Expecting a physical card to be immediately usable — physical cards have a fulfillment period and are not active until produced and optionally activated by the cardholder.
Related Endpoints
GET /api/paymentCards/v2— List all payment cards for a customerPOST /api/paymentCards/v2/Activate— Activate a pending payment cardPOST /api/paymentCards/v2/Cancel— Cancel an existing payment cardGET /api/paymentCards/v2/{paymentCardId}— Retrieve details for a specific payment card
Example
curl -X POST https://api.banking.netevia.dev/api/paymentCards/v2/Issue \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"financialAccountId": "fa_9b2c4e1d7a3f8b0e",
"activateNow": true,
"paymentCardName": "Operations Card",
"cardProfileSetId": "cps_virtual_standard",
"subProfileId": 4821
}'Success