Manage card PIN

Read a card's PIN encrypted to the cardholder's device, and set a new 4-digit PIN.

Gravv gives every new card a random 4-digit PIN when it issues the card. This page explains how to show the PIN to the cardholder and how to set a new one.

A money example. Ada wants to pay 9.99 USD at a terminal that asks for a PIN. Your app shows her PIN on her phone, she changes it to 4821, and she pays.

Show the PIN

Get card PIN uses the same encryption as sensitive details:

Send the device's public key in X-Client-Public-Key.
Pass encrypted_key, nonce and ciphertext from the response to the device.
Decrypt them on the device. The plaintext is {"pin":"4821"}.

curl --request GET \
     --url https://api.gravv.xyz/v1/cards/a14ec356-f33d-4384-ba68-4d9bfa19765b/pin \
     --header 'Api-Key: <API_KEY>' \
     --header 'X-Client-Public-Key: <base64 of the PEM public key>'

Set a PIN

Update card PIN is a PUT. Send 4 digits as a string. The API refuses repeated or sequential digits (1111, 1234).

curl --request PUT \
     --url https://api.gravv.xyz/v1/cards/a14ec356-f33d-4384-ba68-4d9bfa19765b/pin \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "card_pin": "4821"
}
'

{
  "data": "card pin updated successfully",
  "error": null
}

What can go wrong

Response	Why	Fix
400 `card pin update failed`	The PIN is weak or invalid, or the card program returned an error	Choose another 4-digit PIN
400 `json: cannot unmarshal number into Go struct field Body.card_pin of type string`	You sent the PIN as a number	Send `"4821"`
400 `this card has no PIN set: set one with PUT /v1/cards/{card_id}/pin, or reissue — cards issued now are given a PIN at creation`	The card is an older card with no PIN	Set a PIN
400 `failed to get card pin from provider`	The API cannot reveal the PIN right now	Retry later
400 `card does not exist`	The card id is wrong. The API checks the id before the key header	Check the id

Never ask a cardholder to type their PIN into a chat or a support form, and never log it.