# Register Payment Identifiers
source: https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/register-payment-identifiers/index.md

## Register Payment Identifiers within the Consumer Clarity API {#register-payment-identifiers-within-the-consumer-clarity-api}

This document outlines the registration flow that enables secure registration of Primary Account Number (PAN) and payment identifiers using the Registrations Endpoint within the Consumer Clarity API.

The `/registrations` endpoint lets you securely register payment identifiers for use within the Consumer Clarity API to enable subscription identification and enhanced merchant recognition.

This guide explains:

* When the `/registrations` endpoint is required
* How to submit registration requests
* How registration processing works
* How to retrieve registered data
* Authentication, encryption, and PAN handling requirements

## When to use the Registrations endpoint {#when-to-use-the-registrations-endpoint}

Use the `/registrations` endpoint if you rely on Mastercard Data Warehouse transaction data for subscription identification. Registration lets Mastercard associate a cardholder's `paymentId` with transaction data available within Mastercard systems.

The `/registrations` endpoint is recommended for issuers that:

* Have a portfolio with a significant share allocated to Mastercard, because the relevant transaction data is available through the Mastercard Data Warehouse.
* Intend to pass an internally generated UUID value for the `paymentId` field when calling the Smart Subscriptions endpoints for subscription identification.

After registration is complete, you can use the associated `paymentId` when calling the `/searches` and `/listings` endpoints.

The `/registrations` endpoint isn't necessary if you provide your transaction data directly. In this case, subscription identification is performed using the supplied transaction data. Cardholder registration isn't required.

Issuers that intend to use the Payment Account Reference (PAR) value for the paymentID field in the `/searches` and `/listings` endpoint don't need to call the `/registrations` endpoint, because the PAR serves as a common value that can be referenced in Mastercard systems.

Issuers who have 0% Mastercard portfolio share aren't eligible to use this endpoint.
Note: The source of the transaction data determines whether registration is required. Both issuer types can use `paymentId`. However, only issuers that use Mastercard Data Warehouse transaction data must register cardholders through the `/registrations` endpoint.

## Registration Workflow {#registration-workflow}

Registering payment identifiers is an asynchronous process that includes registration, processing, and retrieval steps. This section walks through each stage of the workflow and explains what to expect at each step.

### Step 1: Submit a Registration Request {#step-1-submit-a-registration-request}

Submit a bulk registration request to:

**Endpoint** : `POST /registrations`

Each request can contain up to 500 registrations.

Each registration includes:

```json
{
  "pan": "5287773326428815",
  "paymentId": "52318413-bd05-4960-a745-f79e5c3d6de9"
}
```

Because PAN data is included in the request, the entire payload must be [encrypted using JWE](https://developer.mastercard.com/consumer-clarity/documentation/api-basics/authentication-and-encryption/index.md#encryption) prior to transmission. You can also refer to our [Reference Application](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md) documentation, which provides a step-by-step guide on integrating with the Ethoca Consumer Clarity and Smart Subscriptions APIs.

For large registration loads exceeding 250,000 records, allow additional processing time.

### Step 2: Receive an Acknowledgement {#step-2-receive-an-acknowledgement}

After validation, Consumer Clarity returns an acknowledgement response.

Example:

```json
{
  "requestId": "52318413-bd05-4960-a745-f79e5c3d6de9",
  "status": "Your registration batch has been accepted for processing."
}
```

Important:

* `ACCEPTED` indicates the request was successfully received.
* `ACCEPTED` does **not** indicate registration processing is complete.
* Registration processing occurs asynchronously.

### Step 3: Registration Processing {#step-3-registration-processing}

Consumer Clarity performs asynchronous processing after the request is accepted.

During processing the platform:

1. Creates a secure mapping between the registered `paymentId` and generated token.
2. Stores only non-PCI tokenized data.

Registration processing is typically completed within 24 hours.

### Step 4: Retrieve Registered Data {#step-4-retrieve-registered-data}

After processing is complete, retrieve registration results using the `/listings` endpoint.

**Endpoint** : `POST /listings`

Provide:

* `paymentId`

Responses can include subscription data.

## Authentication Requirements {#authentication-requirements}

Access to the `/registrations` endpoint requires OAuth 1.0 authentication and encryption credentials issued through the Mastercard Developer Portal.

When you [create a project](https://developer.mastercard.com/consumer-clarity/documentation/quick-start-guide/index.md#create-a-new-project-and-generate-your-credentials) in the Mastercard Developer Portal, you receive these credentials:

|             Credential             |                   Purpose                    |
|------------------------------------|----------------------------------------------|
| Signer Key                         | OAuth 1.0 authentication                     |
| Client Encryption Key (Public Key) | JWE encryption of sensitive request payloads |

Use the Mastercard Signer Library to generate OAuth authorization headers for API requests.

## Encryption Requirements {#encryption-requirements}

Registrant requests contain PAN data and must be protected using layered security controls. This section describes the encryption requirements used to secure data before, during, and after transmission.

### Required Controls {#required-controls}

* Encrypt the full request payload using JWE.
* Protect all network traffic using TLS.
* Never transmit PAN in plain text.

### Encryption Lifecycle {#encryption-lifecycle}

PAN data is encrypted:

1. Before transmission.
2. During transit.
3. During secure processing.

After receipt:

* PAN is securely processed.
* PAN is processed to establish a secure association with the registered paymentID.
* PAN isn't retained after processing completes.

## Data Handling and Retention {#data-handling-and-retention}

Consumer Clarity is designed to protect sensitive cardholder data throughout the registration process. This section explains how PAN data is handled, what information is retained, and how long registration records are stored.

### Temporary Storage {#temporary-storage}

Encrypted payloads are stored only for processing purposes and retained for a minimal period.

### PAN Handling {#pan-handling}

Consumer Clarity doesn't persist any decrypted PAN values.

After processing:

* PAN data is removed.
* Tokenized identifiers are retained.
* Only anonymized mappings remain available for future lookups.

### Retention Period {#retention-period}

Registration data and associated non-PCI records are retained for up to five years in accordance with applicable retention policies.

## Implementation Tips {#implementation-tips}

Follow these implementation best practices to help keep registration data current and improve long-term maintenance.

* Submit registrations periodically for your new user base.
* Existing registered users don't require any ongoing maintenance.

## Error Handling {#error-handling}

The `/registrations` endpoint validates incoming requests and returns detailed error information when validation fails. This section describes common error scenarios and the responses returned by the API.

Invalid requests return HTTP 400.

Example error response:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "Service",
        "ReasonCode": "BAD_REQUEST",
        "Description": "Short description of the error",
        "Recoverable": false,
        "Details": "Detailed description of the error"
      }
    ]
  }
}
```

### Successful registration acknowledgement {#successful-registration-acknowledgement}

A valid registration request returns HTTP 202 `ACCEPTED`. The response body includes a non-blank `requestId` and a status indicating that the registration batch was accepted for processing.

### Bad request responses {#bad-request-responses}

If one or more fields fail validation, the API returns HTTP 400 and provides an error for each invalid field.

Common validation scenarios include:

|                  Scenario                  |                                                             Expected result                                                             |
|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `clientId` is `null`                       | HTTP 400 with reason code `BAD_REQUEST`; details indicate `clientId` must not be null.                                                  |
| `clientId` is empty                        | HTTP 400 with details indicating `clientId` must not be empty, must be between 1 and 128 characters, and must match `^[a-zA-Z0-9-_]+$`. |
| `clientId` contains unsupported characters | HTTP 400 with details indicating `clientId` must match `^[a-zA-Z0-9-_]+$`.                                                              |
| `clientId` exceeds the maximum length      | HTTP 400 with details indicating `clientId` must be between 1 and 128 characters.                                                       |
| `issuerId` is `null`                       | HTTP 400 with details indicating `issuerId` must not be null.                                                                           |
| `issuerId` is empty                        | HTTP 400 with details indicating `issuerId` must not be empty, must be between 1 and 128 characters, and must match `^[a-zA-Z0-9-]+$`.  |
| `issuerId` contains unsupported characters | HTTP 400 with details indicating `issuerId` must match `^[a-zA-Z0-9-]+$`.                                                               |
| `issuerId` exceeds the maximum length      | HTTP 400 with details indicating `issuerId` must be between 1 and 128 characters.                                                       |

Note: The `issuerId` pattern allows alphanumeric characters and hyphens only: `^[a-zA-Z0-9-]+$`. The `clientId` pattern also allows underscores: `^[a-zA-Z0-9-_]+$`.

### Malformed request body responses {#malformed-request-body-responses}

Malformed request bodies return HTTP 400 with reason code `REQUEST_BODY_MALFORMED`.

Examples of malformed request bodies include:

* Whitespace only, such as `" "`.
* Special characters only, such as `"@#$$^&*^"`.
* Plain text, such as `"text"`.
* A bare number, such as `"223"`.

### Authorization and permission responses {#authorization-and-permission-responses}

If the `clientId` is syntactically valid but doesn't have sufficient permission for `SUBSCRIPTION_CONTROLS`, the API returns HTTP 400 with reason code `BAD_REQUEST`. The error details indicate that the issuer's `clientId` has insufficient permission for `SUBSCRIPTION_CONTROLS`.

### Unsupported content type responses {#unsupported-content-type-responses}

If the request uses an unsupported content type, such as `application/xml`, the API returns HTTP 400 with reason code `UNSUPPORTED_CONTENT_TYPE`. The error response includes `source` set to `SS_TOKENIZATION_SERVICE`, `description` set to `Invalid Request`, and `recoverable` set to `false`.

## Next Steps {#next-steps}

* Configure [OAuth authentication](https://developer.mastercard.com/consumer-clarity/documentation/api-basics/authentication-and-encryption/index.md) and JWE payload encryption, if necessary.
* Register payment identifiers using the [`/registrations` endpoint](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#tag/Clarity-Registrations).
* Retrieve results using the `/listings` API.