OpenAPI specification
Release: ActiveSingle operation + dependencies. Includes the request, responses, and referenced schemas for this API—not the full product specification.
Loading, please wait…
Update a card status.
/v1/party/{partyId}/baas/cards/{cardId}/status/updateUse this BaaS endpoint to lock and unlock the cardholder's card upon their request. This same endpoint is also used to mark a card as lost, stolen and damaged.
Showing 9 of 9 top-level parameters (9 total fields) for Update Card Status
partyIdRequiredstringpathThe UUID of the Payfare (banking service) user.
cardIdRequiredstringpathThe UUID of the banking service card.
Api-KeyRequiredstringheaderCommerceHub API key. Use the same value as the first part of the HMAC signing input.
Auth-Token-TypeRequiredstringheaderIdentifies the CommerceHub HMAC authentication scheme.
Available enum values
Selecting a value updates the request header.
Client-Request-IdRequiredstringheaderFresh client request identifier included in the HMAC signing input. Generate a new identifier for every request, for example using String(Date.now()). Use exactly the same value in the header and signature; this does not establish an idempotency or retry guarantee.
TimestampRequiredstringheaderRequest time as a 13-digit Unix timestamp in milliseconds, generated using String(Date.now()). Use exactly this value in the HMAC signing input. Accepted clock skew awaits confirmation.
AuthorizationRequiredstringheaderBase64(HMAC-SHA-256(apiSecret, apiKey + clientRequestId + timestamp)), without a prefix. Use exactly the values sent in the corresponding headers.
statusstringThe status the cardholder wishes to set the card to. The table below contains the current allowable card status changes along with their descriptions: Card Status Description active All transactions allowed. frozen Withdrawals and purchases are blocked. Cardholder has the option of switching the card into an unlocked state ("active") from this status. lost Use this status for when the user has marked their card as lost. Withdrawals and purchases are blocked. Once a card is marked as lost, banking service does not allow the card to be reactivated. damaged Use this status for when the user has marked their card as damaged. Withdrawals and purchases are blocked. Once a card is marked as damaged, banking service does not allow the card to be reactivated. stolen Use this status for when the user has marked their card as stolen. Withdrawals and purchases are blocked. Once a card is marked as stolen, banking service does not allow the card to be reactivated. 📘 Card Status Terminology The frozen status is what banking service uses to refer to a card that is commonly referred to as locked. In same way, an active card is a card that is commonly referred to as unlocked.
Available enum values
Selecting a value updates the request body.
report_datestringThe date on which the cardholder has requested to make this status change in (YYYY-MM-DD) format.
Request
Update Card StatusResponse
Top-level fields returned in a successful (200) response.
statusstringThe status field.
messagestringThe message field.
dataobjectThe data field.
curl --request POST 'https://cert.api.fiservapps.com/ch/v1/party/{partyId}/baas/cards/{cardId}/status/update' \
--header 'Api-Key: YOUR_API_KEY' \
--header 'Auth-Token-Type: HMAC' \
--header 'Client-Request-Id: YOUR_CLIENT_REQUEST_ID' \
--header 'Timestamp: YOUR_TIMESTAMP' \
--header 'Authorization: YOUR_BASE64_SIGNATURE' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"status": "frozen",
"report_date": "2023-06-30"
}'Standard HTTP error reference. Not every status applies to every operation.
| HTTP | Meaning | Guidance |
|---|---|---|
| 400 | Bad Request | Check the URL parameters, headers, and request payload. |
| 401 | Unauthorized | Verify the API key, HMAC signature, request ID, and timestamp. |
| 403 | Forbidden | Verify access to the requested service and resource. |
| 404 | Not Found | Check the endpoint and resource identifiers. |
| 409 | Conflict | Check the current resource state before repeating the operation. |
| 422 | Unprocessable Content | Review the returned validation details and correct the request. |
| 429 | Too Many Requests | Respect Retry-After when present; confirm retry safety before resending mutations. |
| 500 | Internal Server Error | Record the response and request identifier; confirm the outcome before retrying a mutation. |
| 502 | Bad Gateway | An upstream response failed. Confirm the outcome before retrying a mutation. |
| 503 | Service Unavailable | Respect Retry-After when present and confirm the outcome before retrying a mutation. |
| 504 | Gateway Timeout | The upstream response timed out. Check the operation outcome before resending. |
Single operation + dependencies. Includes the request, responses, and referenced schemas for this API—not the full product specification.
No Postman workflow is mapped to this operation. No product-wide collection is substituted.
QA collections: Configure your environment and credentials before running. Some requests create resources or move funds.