Skip to main content
POST
Manage Card PIN

Authorizations

x-auth-token
string
header
required

The API token for login provided by UQPAY.

Headers

x-on-behalf-of
string

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts endpoint. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

x-idempotency-key
string<uuid>
required

A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures.

Body

application/json
card_id
string<uuid>
required

Card to manage. It must be active and not expired. Wait for any PIN operation already processing for this card to finish before submitting another.

pin
string
required

New PIN. Do not use a repeated single digit or a PIN that occurs within the cardholder's phone number. Its last four digits must not match the card number's last four digits. When updating, it must differ from the current PIN.

Pattern: ^[0-9]{6}$
type
enum<string>
default:SET

If omitted, defaults to SET for initial PIN setup. Use SET for initial setup; explicitly pass RESET to reset without the current PIN, or UPDATE to change after verifying the current PIN. Supported operations depend on the card; unsupported operations return pin_operation_not_supported.

Available options:
SET

Response

200 - application/json

PIN operation order accepted; the PIN change is not yet confirmed.

request_status
enum<string>
required

The request was accepted; this is not the final PIN operation result.

Available options:
SUCCESS
card_id
string<uuid>
required

Card associated with the order.

card_order_id
string<uuid>
required

Order identifier used to track the PIN operation through Retrieve Card Order or the card order webhook.

order_status
enum<string>
required

PIN operation order status:

  • PROCESSING: accepted and processing; the PIN change is not yet confirmed.
  • SUCCESS: completed; the PIN has changed.
  • FAILED: the operation failed.

This endpoint returns PROCESSING at acceptance. Retrieve the order or consume the card order webhook to obtain its final status. API order statuses use uppercase; card update webhooks use lowercase: pending means processing, success means succeeded, and failed means failed.

Available options:
PROCESSING
create_time
string<date-time>
required

Order creation time in RFC3339 format.