Skip to main content

Refresh CVV

Submit a new card verification value for a stored card belonging to the authenticated user.

Domain
Cards and vault
Owning service
Payments
Intended for
Customer application · user to server
Supported authorization
Authenticated user Bearer token

Headers#

2
AuthorizationstringRequired
Accepted or forwarded by the API Gateway for this operation.
X-Merchant-IDstringOptional
Accepted or forwarded by the API Gateway for this operation.

Path parameters#

2
user_idstring<uuid>Required
Value substituted for `user_id` in the endpoint path.
card_idstring<uuid>Required
Value substituted for `card_id` in the endpoint path.

Request body#

1
card_cvvstringRequired
JSON payload accepted by the owning service. Use the request panel to edit and preview the body.
Example 123

Response#

7
204The request was accepted or completed. Inspect the response payload for the business outcome.
400The request is malformed or fails validation.
401The supplied credentials or caller context are invalid.
403The supplied credentials or caller context are invalid.
404The requested resource or route was not found.
422The request is malformed or fails validation.
500The service could not complete the request. Retry only when the operation is safe or idempotent.

Before you refresh the CVV#

  • Authenticate the customer and send their user access token in the Authorization header.
  • Set the path user ID to the authenticated customer's UUID and use a card ID returned by List stored cards.
  • Collect the card verification value (CVV) from the customer for the stored card. The card must belong to that customer and have a valid expiration date.

Send the refresh request#

Use the sandbox base URL below for testing and https://api.deuna.io for production. Send a JSON object with the required card_cvv string containing the three- or four-digit CVV. There are no query parameters. This operation updates an existing card; it does not create a card or charge the customer.

curl --request POST \
  --url 'https://api.sandbox.deuna.io/users/USER_ID/cards/CARD_ID/refresh-cvv' \
  --header 'Authorization: Bearer USER_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"card_cvv":"123"}'

Verify the result#

A successful request returns HTTP 204 No Content with an empty body. Do not parse it as JSON. The response confirms completion of the CVV refresh; it does not confirm a payment or expose the CVV in a card response. No payment webhook is needed to confirm this operation.

Continue with your payment request when the customer is ready to pay.

Handle errors and retries#

HTTP 400 indicates invalid identifiers, malformed JSON, or a missing or invalid CVV. HTTP 401 indicates invalid user authorization. HTTP 404 means the stored card was not found for the authenticated user. HTTP 422 indicates an expired card, invalid expiration data, or a card that cannot be refreshed. Correct the input or select another card before retrying.

If a timeout or server error leaves the outcome uncertain, do not replay the CVV automatically. No idempotency-key contract is defined for this operation. Let the customer retry within the active flow and collect the CVV again when needed. See response codes and troubleshooting.