| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Problem statement
Partners need a way to change the PIN of an already issued physical card. The public API exposes the card PIN change flow, but the client must send the PIN in encrypted form.
Executive Summary
This endpoint exposes PATCH /v1/corporate-cards/{cardId}/pin.
It is intended for authenticated partners. The public API accepts the encrypted PIN, verifies card ownership, and changes the card PIN for the authenticated card owner.
The public request contains only one field:
- Encrypt the PIN with the public key provided during onboarding.
- Use RSA with OAEP padding.
- Base64-encode the encrypted bytes.
- Send the result as
pinEncrypted.
Integration model
| Step | Method | Endpoint | Purpose |
|---|---|---|---|
| 1. Encrypt PIN | Client-side | N/A | Encrypt the new card PIN before sending it to Altery |
| 2. Submit change | PATCH | /v1/corporate-cards/{cardId}/pin | Change the PIN for the authenticated card |
| 3. Verify result | Response | Base API response | Check whether the change completed successfully |
Request details
| Field | Required | Description |
|---|---|---|
cardId | Yes | Card identity in the URL path. |
pinEncrypted | Yes | Encrypted card PIN. Encrypt the PIN with the public key provided during onboarding using RSA with OAEP padding, then base64-encode the encrypted bytes before sending the request. |
The request model does not accept a plaintext PIN. See Sending encrypted pin in ChangePin request for a client-side example.
Examples
Change the card PIN
{
"pinEncrypted": "QmFzZTY0RW5jcnlwdGVkRGF0YQ=="
}Request path
PATCH /v1/corporate-cards/11111111-2222-3333-4444-555555555555/pinCard lifecycle notes
The API validates the request, checks that the caller can act on the card, and applies the PIN change for the authenticated card owner.
Encryption notes
Use the public key shared during onboarding to encrypt the PIN before sending it to Altery. The encrypted bytes should be encoded as base64 and placed in pinEncrypted.
Security
[!WARNING]
pinEncryptedstill represents a sensitive cardholder secret. Encrypt the PIN on the client side and send it only over HTTPS. Do not log the plaintext PIN or the decrypted value.
[!NOTE]
The public API never expects a raw PIN payload.
Timeout: 2 seconds.