Create Hosted Page for PIN Management

Create a hosted page for viewing and resetting a PIN.

In the sandbox, you can set any number other than 1111.

Rapyd sends you Issued Card PIN Set Webhook when the customer sets a PIN.

Note

PINs are relevant to physical cards.
Some card programs do not support resetting the PIN. Holders of those cards must reset the PIN at an ATM.

Prerequisites

Rapyd Wallet. See Wallet.
Wallet contact with a valid phone number. See Wallet Contact.
Issued card that is activated. See Activate Issued Card Using Hosted Page.

Parameters

Request Header Parameters

Request Body Parameters

- cancel_url
- URL where the customer is redirected after pressing Back to website.
- card
- ID of the card. String starting with card_.
- complete_url
- URL where the customer is redirected after completing the hosted page.
- ewallet_contact
- ID of the wallet contact that the card is assigned to. Must have a valid phone number. String starting with cont_.
- language
- Determines the default language of the hosted page.
- page_expiration
- End of the time when the customer can use the hosted page, in Unix time.
  7 days after creation
- skip_view_pin
- When true, the customer cannot view the PIN via a hosted page.
  false

Response Parameters

- cancel_url
- URL where the customer is redirected after pressing Back to Website to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- card_token
- ID of the card. String starting with card_.
- card_issuing
- ID of the Issued Card object, a string starting with ci_.
- complete_url
- URL where the customer is redirected after pressing Close to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- ewallet_contact
- ID of the wallet contact that the card is assigned to. Must have a valid phone number. String starting with cont_.
- geo_country
- Reserved.
- id
- ID of the hosted page for resetting a PIN, a string starting with hp_issuing_pin_.
- language
- Determines the default language of the hosted page. For a list of values, see List Supported Languages.
  When this parameter is null, the language of the user's browser is used.
  If the language of the user's browser cannot be determined, the default language is English.
- merchant_alias
- Client's name.
  Rapyd
- merchant_color
- Color of the call-to-action (CTA) button on the hosted page.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_customer_support
- Contains details of the client’s customer support. To configure these fields, use the Client Portal. See Customizing Your Hosted Page.
  email
  Email address.
  url
  URL for the client's customer support service.
  phone_number
  Phone number for contacting the client's customer support service.
- merchant_logo
- URL for the image of the client's logo.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_privacy_policy
- URL for the terms and conditions of the agreement between the client and the client’s customers.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_terms
- URL for the terms and conditions of the client. To configure this field, use the Client Portal.
  See Customizing Your Hosted Page.
- merchant_website
- The URL where the customer is redirected after exiting the hosted page.
  Relevant when one or both of the following fields is unset:
  cancel_url
  complete_url
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- page_expiration
- End of the time when the customer can use the hosted page, in Unix time. If page_expiration is not set, the hosted page expires 14 days after creation.
  Range: 1 minute to 30 days.
- redirect_url
- URL of the hosted page that is shown to the customer.
- region
- Reserved.
- skip_view_pin
- When true, the customer cannot view the PIN via a hosted page.
- status
- Status of the hosted page. One of the following:
  NEW - The hosted page was created.
  DON - Done. The card was added to the customer profile.
  EXP - The hosted page expired.

/v1/hosted/issuing/pin

Create Hosted Page for PIN Management

curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/issuing/pin' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "card": "card_d1c07ed0ce32fe5c2a1f628007b09a58",
    "ewallet_contact": "cont_cb60ec28c2f0bdfc621cfc21270c20ce"   
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "b4e1d268-dc69-401a-8c7e-eab3e9e4943f"
    },
    "data": {
        "status": "NEW",
        "cancel_url": "https://example1234.net",
        "complete_url": "https://example1234.net",
        "language": "",
        "org_id": "153e08b8-4bf3-4cb9-bb03-79d405eaed2a",
        "merchant_color": "323fff",
        "merchant_logo": "",
        "merchant_website": "https://example1234.net",
        "merchant_customer_support": {
            "url": "https://example1234.net",
            "email": "support@example1234.net",
            "phone_number": "121255551213"
        },
        "merchant_alias": "Doc Team",
        "merchant_terms": "https://example1234.net/terms_and_conditions",
        "merchant_privacy_policy": "https://example1234.net/privacy_policy",
        "page_expiration": 1764502764,
        "redirect_url": "https://sandboxhosted.rapyd.net/otp?token=hp_issuing_pin_4343909b3442d06087b93f71893d2f57",
        "id": "hp_issuing_pin_4343909b3442d06087b93f71893d2f57",
        "ewallet_contact": "cont_cb60ec28c2f0bdfc621cfc21270c20ce",
        "card_token": "card_d1c07ed0ce32fe5c2a1f628007b09a58",
        "card_issuing": "ci_1fe7a25f7bf7092c949d1d6473a8c555",
        "skip_view_pin": false
    }
}

Bad Request - Card Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/issuing/pin' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "card": "card_d1c07ed0ce32fe5c2a1f628007b09a5",
    "ewallet_contact": "cont_cb60ec28c2f0bdfc621cfc21270c20ce"   
}'

{
    "status": {
        "error_code": "ERROR_GET_ISSUED_CARD",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a card ID, but the card was not found. The request was rejected. Corrective action: In the 'card' field, provide the ID or card number of a valid card.",
        "response_code": "ERROR_GET_ISSUED_CARD",
        "operation_id": "3f8078ae-b0e6-4f3e-9c4a-395fff0f0de5"
    }
}

Bad Request - Contact Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/issuing/pin' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "card": "card_d1c07ed0ce32fe5c2a1f628007b09a58",
    "ewallet_contact": "cont_cb60ec28c2f0bdfc621cfc21270c20c"   
}'

{
    "status": {
        "error_code": "ERROR_GET_EWALLET_CONTACT",
        "status": "ERROR",
        "message": "The request tried to retrieve a wallet contact, but the contact was not found. The request was rejected. Corrective action: Specify the ID of a valid wallet, a string starting with 'ewallet_', and the ID of a valid contact belonging to that wallet, a string starting with 'cont_'.",
        "response_code": "ERROR_GET_EWALLET_CONTACT",
        "operation_id": "9012b8bd-55d9-46d5-a274-77aa535675f6"
    }
}

In this section:

Documentation