Set / Reset PIN

Set or reset the 4-digit PIN for a physical card. Never send PINs over plaintext channels.

POST/v1/cards/{id}/pin

🔐

For PCI compliance, PINs must be collected from the user via a secure hosted page or an encrypted widget. Do not accept raw PINs in your own backend. Request a PIN token first.

1. Request a PIN change token

POST/v1/cards/{id}/pin/tokens

curl -X POST https://api.vaultspay.ae/v1/cards/card_01HX7.../pin/tokens \
  -H "Authorization: Bearer sk_test_yourApiKeyHere"

200 OK

{
  "token": "pint_01HX7ABCDEFG...",
  "hosted_url": "https://pay.vaultspay.ae/pin/pint_01HX7ABCDEFG...",
  "expires_at": "2026-04-24T15:02:03Z"
}

Redirect the user to hosted_url or embed it inside an iframe. Once completed you’ll receive the webhook card.pin_set.

2. (Alternative) Direct PIN set with encrypted payload

If you are PCI-DSS certified and approved for direct PIN entry:

Field	Type	Description
`encrypted_pin`required	string	RSA-OAEP encrypted PIN, base64-encoded.
`kid`required	string	Key ID of the VaultsPay public key used for encryption.

curl -X POST https://api.vaultspay.ae/v1/cards/card_01HX7.../pin \
  -H "Authorization: Bearer sk_test_yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -d '{ "encrypted_pin": "...base64...", "kid": "vp-pin-2026-01" }'

Spend Controls Card Transactions