> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borderless.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastercard Crypto Credential

> Issue verifiable Crypto Credential usernames for your KYC-verified users, and check counterparties across the Mastercard network, through the Borderless API.

This document is a technical guide for integrating with Mastercard Crypto Credential through the Borderless platform.

Crypto Credential provides a common usable credential for ID-verified consumers from verified Virtual Asset Service Providers (VASPs). Participating VASPs can issue a Crypto Credential username to users who have been properly verified through their KYC process. Any other participating VASP can then verify that credential, helping reduce the risk and friction of duplicative KYC while saving time and cost for both the VASP and the end user.

Borderless acts as the gateway between VASPs and the Mastercard Crypto Credential network. All Mastercard API calls are handled by Borderless on behalf of VASPs using securely stored credential keys. VASPs never communicate with Mastercard directly.

***

## Roles & Terminology

This guide covers two integration roles. Your role determines which flows are relevant to your integration.

| **Role**             | **Description**                                                                                                                                                  |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Originator VASP**  | A VASP that uses the Borderless API to onboard its own users and wants Crypto Credential created for them so they can be verified when sending transactions.     |
| **Beneficiary VASP** | A VASP (PFI) that receives user verification requests from Borderless and needs to use Crypto Credential to validate eligibility before accepting a transaction. |

| **Term**              | **Definition**                                                                                                                                                                                                     |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User**              | The end user — the individual whose identity is verified and for whom a Crypto Credential is created and issued. Corresponds to an **identity** in the Borderless system or a **customer** at your platform (PFI). |
| **Alias**             | Any identifier that resolves to a Crypto Credential account. An account has an email alias and a Mastercard-generated domain name alias.                                                                           |
| **Domain name alias** | The Crypto Credential username Mastercard derives at registration, in the form `user.customer.mastercard`. This is the identifier other participants resolve when sending funds.                                   |
| **ICA**               | Interbank Card Association identifier. Mastercard issues one per participant; it scopes every account you create.                                                                                                  |

<Info>
  **Which role am I?** If you use the Borderless API to create identities and accounts for your users — you are an **Originator VASP**. If you receive users from Borderless — you are a **Beneficiary VASP**. Some organizations act as both.
</Info>

***

## Prerequisites

Before integrating with Mastercard Crypto Credential, ensure the following:

1. Your organization is registered on the Borderless platform with active API or Dashboard credentials. Please contact the Borderless team.
2. You have received your Mastercard Crypto Credential keys from Mastercard. Please see the links below for details on how to generate each prerequisite:
   * **ICA** — created and shared after onboarding
   * **Client ID** — [How to generate](https://developer.mastercard.com/crypto-solutions-api/documentation/mtid/)
   * **Encryption Key** — [How to generate an RSA key pair](https://developer.mastercard.com/crypto-solutions-api/documentation/tutorials-and-guides/tutorials/generate-rsa-key-pair/)
3. Your Mastercard keys are stored in Borderless via [`PUT /organizations/integrations`](/api-reference/integrations-config/setup-integration-credentials-consolidated) or through the Borderless Dashboard, and your organization is flagged as a Mastercard partner. These are two separate switches and both must be set — otherwise no Crypto Credential is created and the proxy endpoints report a configuration error.
4. Proxy endpoint access is enabled for your organization, if you intend to call Mastercard directly through Borderless. Contact the Borderless team to turn it on. The passive flows described below do not require it.

<Note>
  Mastercard responses are encrypted. Alongside Mastercard's public encryption key you also provide **your own** RSA private key, which Borderless uses to decrypt them. Generate the pair with the tutorial linked above and share the public certificate with Mastercard during onboarding.
</Note>

***

## Originator VASP

You use the Borderless API to onboard users and manage their accounts. By storing your Mastercard keys in Borderless, your users automatically receive a Crypto Credential — making them verifiable across the Mastercard Crypto Credential network.

### Creating Crypto Credential

#### Option A: Automatic Creation (Passive)

**How it works:**

This flow uses the standard Borderless API for creating identities and managing compliance. If you are not yet integrated with the Borderless API, see the [Quick Start Guide](/docs/quick-start-guide) to get started.

Once your Mastercard keys are stored in Borderless, a Crypto Credential is created automatically for each identity you create — personal or business. No additional API calls or integration work is needed. The response to [`POST /identities/personal`](/api-reference/identities/create-a-new-personal-identity) and [`POST /identities/business`](/api-reference/identities/create-a-new-business-identity) includes the resulting `cryptoCredential`.

**When to use:**

This is the recommended default for Originator VASPs. Your existing Borderless integration handles everything — creation happens transparently in the background.

**What to implement:**

Nothing. Store your Mastercard keys in Borderless and continue using your existing flow.

<Note>
  If the alias is already registered by another participant, Mastercard rejects the registration. We record the identity as verified and keep serving its status, but the credential itself remains under the participant that registered it first — so `aliases.domainName` is not returned and the Crypto Credential endpoints will not accept it.
</Note>

<Note>
  An email address is required. Since the alias is the identity's email, an identity created without one gets `cryptoCredential.errors` instead of a credential. This mostly affects business identities, where email is optional in the standard flow.
</Note>

#### Option B: Create via Proxy Endpoint (Active)

**How it works:**

If you need to create a Crypto Credential at a specific point in your flow — for example for a user who was onboarded outside of Borderless, or when you want explicit control over timing — call the proxy endpoint directly.

**When to use:**

When you need granular control over when and for whom a credential is created, or when the user was not onboarded through the standard Borderless identity flow.

**Example:**

```bash theme={null}
curl -X POST "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/accounts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountAlias": "user@example.com",
    "aliasType": "Email",
    "country": "US"
  }'
```

**Request body:**

| **Field**                 | **Type** | **Required** | **Description**                                                                                                                                                                                                                           |
| :------------------------ | :------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountAlias`            | string   | Yes          | The alias to register — typically the user's email address. Up to 255 characters.                                                                                                                                                         |
| `aliasType`               | enum     | No           | `Email`, `PhoneNumber` or `DomainName`. There is no default — if you omit it, no alias type is sent to Mastercard.                                                                                                                        |
| `status`                  | enum     | No           | `Active`, `Suspended` or `Decommissioned`. Mastercard registers new accounts as `Active`.                                                                                                                                                 |
| `country`                 | enum     | No           | ISO 3166-1 alpha-2 country code.                                                                                                                                                                                                          |
| `statusReasonInformation` | array    | No           | Up to 10 `{ reasonCode, description }` entries explaining a non-default status. Within each entry `reasonCode` is **required** and must be one of Mastercard's accepted codes; `description` is optional free text, up to 255 characters. |

Full endpoint documentation: [Create a Crypto Credential account](/api-reference/mastercard-crypto-credential/create-a-crypto-credential-account)

<Note>
  Credentials created this way are not linked to a Borderless identity, so they do not appear in `GET /identities/{id}`. Use [Search for a Crypto Credential account](/api-reference/mastercard-crypto-credential/search-for-a-crypto-credential-account) to read them back.
</Note>

### Crypto Credential Lifecycle

#### Option A: Update via Identity Endpoint (Passive)

**How it works:**

To change an identity's Crypto Credential state — for example to suspend it during an investigation — include a `cryptoCredential` object in the standard identity update request: [`PATCH /identities/personal/{id}`](/api-reference/identities/update-a-personal-identity) or [`PATCH /identities/business/{id}`](/api-reference/identities/update-a-business-identity). Borderless maps your status to the corresponding Mastercard status and handles the API call.

For an identity that already has a credential, omitting `cryptoCredential` leaves it untouched.

For an identity that has none, any update creates one as `Active` — including an update that omits `cryptoCredential` entirely. Note the asymmetry: sending `status: "Suspended"` or `"Decommissioned"` for an identity with no credential creates nothing and returns none. Create the credential first, then change its status in a second call.

**When to use:**

When you manage credential lifecycle through the standard Borderless identity flow. This is the recommended default.

**Example:**

```bash theme={null}
curl -X PATCH "https://sandbox-api.borderless.xyz/v1/identities/personal/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cryptoCredential": {
      "status": "Suspended",
      "reasonCode": "ALIAS_UNDER_INVESTIGATION",
      "reasonDescription": "Account flagged for compliance review"
    }
  }'
```

**Request body (`cryptoCredential`):**

| **Field**           | **Type** | **Required** | **Description**                                                                                                                                                                                                                                                  |
| :------------------ | :------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`            | enum     | Yes          | `Active`, `Suspended` or `Decommissioned`.                                                                                                                                                                                                                       |
| `reasonCode`        | enum     | No           | Machine readable code explaining the change. A closed set defined by Mastercard — any other value is rejected with `400`. For status changes you will most often need `ALIAS_UNDER_INVESTIGATION` or `OTHER`; the endpoint reference lists every accepted value. |
| `reasonDescription` | string   | No           | Free-text explanation, up to 255 characters. Only forwarded to Mastercard when `reasonCode` is also set — on its own it is silently dropped.                                                                                                                     |

<Warning>
  `Decommissioned` is permanent and irreversible. Mastercard keeps the alias reserved afterwards, so the same email cannot be registered again — by you or by any other participant.
</Warning>

<Note>
  You can only change a credential your organization issued. If it was issued by another participant the credential is left untouched, but the request still returns `200` — the reason arrives in `cryptoCredential.errors`, not as an error status code. Check that field rather than relying on the HTTP status.
</Note>

#### Option B: Update via Proxy Endpoint (Active)

**How it works:**

If you need full control over Mastercard-specific fields, or want to update a credential that is not tied to a Borderless identity, call the proxy endpoint directly.

**Example:**

```bash theme={null}
curl -X PUT "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/accounts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountAlias": "user@example.com",
    "status": "Suspended",
    "statusReasonInformation": [{
      "reasonCode": "ALIAS_UNDER_INVESTIGATION",
      "description": "Account flagged for compliance review"
    }]
  }'
```

Returns `204 No Content` on success.

Full endpoint documentation: [Update a Crypto Credential account](/api-reference/mastercard-crypto-credential/update-a-crypto-credential-account)

### Credential Lookup

As an Originator VASP, you may need to check a Crypto Credential before initiating a transaction.

#### Option A: Standard Identity Endpoint (Passive)

Use [`GET /identities/{id}`](/api-reference/identities/get-an-identity-by-id). The response includes the identity's `cryptoCredential`, with state read live from Mastercard.

```bash theme={null}
curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{id}" \
  -H "Authorization: Bearer {token}"
```

**Response — `cryptoCredential`:**

```json theme={null}
{
  "cryptoCredential": {
    "aliases": {
      "email": "user@example.com",
      "domainName": "user.yourcompany.mastercard"
    },
    "status": "Active",
    "country": "US",
    "vasps": null,
    "assets": [],
    "errors": null
  }
}
```

| **Field**            | **Description**                                                                                                                                                                                                                                 |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aliases.email`      | The alias the credential is registered under. May differ from `identity.email` if the user has since changed their address — the credential stays bound to the alias it was created with.                                                       |
| `aliases.domainName` | The Crypto Credential username. `null` unless your organization issued the credential.                                                                                                                                                          |
| `status`             | `Active`, `Suspended` or `Decommissioned`, as currently reported by Mastercard. `null` when `errors` is set.                                                                                                                                    |
| `country`            | The country the credential is registered in, ISO 3166-1 alpha-2.                                                                                                                                                                                |
| `assets`             | The assets the alias can receive, populated once blockchain addresses are registered. Always an array — `[]` when it can receive none.                                                                                                          |
| `assets[].asset`     | An `AssetId` such as `USDC_ETHEREUM`, combining the token and the network it resolves on.                                                                                                                                                       |
| `assets[].vasps`     | Participants that can route **that asset** to the alias. `null` unless Mastercard entitles your ICA to VASP data.                                                                                                                               |
| `vasps`              | Participants that can route funds to the alias at all. `null` unless Mastercard entitles your ICA to VASP data.                                                                                                                                 |
| `errors`             | Non-`null` when the operation did not complete — Mastercard unreachable, no email on the identity, a rejected registration, or an attempt to change a credential issued elsewhere. Each entry carries a `message` and an optional `reasonCode`. |

`cryptoCredential` is present when a VASP in the Borderless network has verified this identity — either your own organization, or a PFI you routed compliance to. It is scoped to **that identity**, not to the email address: verification happens once per identity, and if the same person later appears as a separate identity — a different customer record, at your platform or another — that record starts without a credential until it completes compliance in its own right. We do not treat two identities as the same person because they share an alias.

<Info>
  Every field inside `cryptoCredential` is always present in the response, holding `null` — or `[]` for `assets` — where there is no value. Nothing is dropped from the object. Only `cryptoCredential` itself is omitted, and only when your organization is not set up for Mastercard. Test for `=== null`, not for a missing key.
</Info>

<Info>
  `errors` and `status` never both carry a value: when `errors` is set, `status`, `country` and `vasps` are `null` and `assets` is `[]`. `aliases` stays populated in most error cases, so it remains the one field you can still read. Treat the state as unknown and retry — do not treat it as an absent credential.
</Info>

<Info>
  `cryptoCredential: null` does **not** mean the user has no Crypto Credential. It means we hold no record for this identity — the same alias may be registered by a participant outside the Borderless network. To ask the network directly, call [`GET /mastercard/crypto-credential/alias-lookup`](/api-reference/mastercard-crypto-credential/look-up-a-crypto-credential-alias).
</Info>

<Warning>
  A Crypto Credential identifies a **verified alias**, not the person currently in front of you. `status: "Active"` confirms that the holder of that alias completed verification with a network participant. It does not confirm that whoever is contacting you now controls that alias. Establish alias ownership by your own means before relying on it.
</Warning>

#### Option B: Proxy Endpoints (Active)

**Cross-network lookup** — query the entire Mastercard network to check an alias at any participant:

```bash theme={null}
curl -X GET "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/alias-lookup?accountAlias=recipient@example.com" \
  -H "Authorization: Bearer {token}"
```

Optional query parameters: `asset` to narrow the result to one asset and network pair, plus `offset` (default `0`) and `limit` (default `25`, maximum `100`) to page through the alias's assets.

Full endpoint documentation: [Look up a Crypto Credential alias](/api-reference/mastercard-crypto-credential/look-up-a-crypto-credential-alias)

**Account search** — read the accounts your own organization registered:

```bash theme={null}
curl -X GET "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/accounts/search?accountAlias=user@example.com" \
  -H "Authorization: Bearer {token}"
```

Full endpoint documentation: [Search for a Crypto Credential account](/api-reference/mastercard-crypto-credential/search-for-a-crypto-credential-account)

<Info>
  **alias-lookup vs accounts/search:** `alias-lookup` queries the **entire Mastercard network** and returns status, country and supported assets — but never a blockchain address or an alias list. `accounts/search` is scoped to **your own ICA** and returns the full account, including every alias and registered address. Use `alias-lookup` to check a counterparty; use `accounts/search` to inspect your own records.
</Info>

### Crypto Address

Registering a blockchain address links it to a Crypto Credential and declares which asset and network it supports. This is what allows other participants to send funds to your user by alias, and lets Mastercard confirm the recipient can actually receive a given asset on a given chain before a transaction starts.

#### Option A: Automatic via Borderless Account (Passive)

<Note>
  This flow is planned for an upcoming release. Until it ships, register addresses with the proxy endpoints below.
</Note>

Once available, adding blockchain addresses to a Borderless Account will register them against the user's Crypto Credential automatically, and changes to those addresses will propagate to Mastercard.

#### Option B: Manage via Proxy Endpoints (Active)

**How it works:**

Register, update and decommission blockchain addresses directly.

**Example:**

```bash theme={null}
curl -X POST "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/crypto-addresses" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountAlias": "user@example.com",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "asset": "USDC_ETHEREUM"
  }'
```

**Request body:**

| **Field**      | **Type** | **Required** | **Description**                                                                                                                  |
| :------------- | :------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------- |
| `accountAlias` | string   | Yes          | The alias the address belongs to. Up to 255 characters.                                                                          |
| `address`      | string   | Yes          | The blockchain wallet address. Between 10 and 255 characters.                                                                    |
| `asset`        | enum     | No           | An `AssetId` such as `USDC_ETHEREUM` or `USDT_POLYGON`. Borderless splits it into the asset and network pair Mastercard expects. |

The response carries the address `id`. Keep it — the update, get and decommission endpoints address the record by that identifier, and it is otherwise only recoverable through `accounts/search`.

**Additional address endpoints:**

* [`PUT /mastercard/crypto-credential/crypto-addresses/{cryptoAddressId}`](/api-reference/mastercard-crypto-credential/update-a-registered-blockchain-address) — change the `accountAlias`, `address`, `asset` or `status`. All four are optional; returns `204 No Content`
* [`DELETE /mastercard/crypto-credential/crypto-addresses/{cryptoAddressId}`](/api-reference/mastercard-crypto-credential/decommission-a-registered-blockchain-address) — decommission permanently; returns `204 No Content`
* [`GET /mastercard/crypto-credential/crypto-addresses/{cryptoAddressId}`](/api-reference/mastercard-crypto-credential/get-a-registered-blockchain-address) — read a single address

Full endpoint documentation: [Register a blockchain address](/api-reference/mastercard-crypto-credential/register-a-blockchain-address)

<Warning>
  A registered address makes your user discoverable as a recipient across the Crypto Credential network. Completing an inbound transfer additionally requires responding to Mastercard alias resolution requests, which Borderless does not currently handle on your behalf.
</Warning>

***

## Beneficiary VASP

As a Beneficiary VASP, you receive users from Borderless. When an identity already carries a Crypto Credential, Borderless passes it to your platform — enabling a simplified compliance process. If the identity has none, Borderless creates a Crypto Credential on your behalf after the user passes compliance at your platform.

The integration requires **minimal changes on your side**. All existing flows remain unchanged — the integration is entirely additive. VASPs that are not participating in the program are not affected in any way.

### Creating Crypto Credential

#### Option A: Automatic Creation (Passive)

When a user is sent to your platform by Borderless, they go through your standard compliance and KYC process. Borderless monitors the outcome — either via long polling or by receiving a webhook from your system — and waits for your decision.

Once you approve the user, Borderless automatically creates a Crypto Credential record in the Mastercard network on your behalf, using your stored keys. If you reject the user, Borderless suspends the credential instead and passes your rejection reasons along as the explanation.

This is the default behaviour and **requires no changes to your existing flow**.

<Info>
  It is recommended that a blockchain address be linked to a user's Crypto Credential username, so the crypto address can be used for both sending and receiving from other participants in the global Crypto Credential network.
</Info>

#### Option B: Create via Proxy Endpoint (Active)

If you need to create a Crypto Credential independently — for a user who was not onboarded through Borderless, or at a specific point in your own flow — use the proxy endpoint directly:

```bash theme={null}
curl -X POST "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/accounts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountAlias": "user@example.com",
    "aliasType": "Email",
    "country": "US"
  }'
```

Full endpoint documentation: [Create a Crypto Credential account](/api-reference/mastercard-crypto-credential/create-a-crypto-credential-account)

<Info>
  Once a Crypto Credential username has been created and linked to a blockchain address, the VASP is responsible for telling their user that they can receive from other Crypto Credential network participants using that username. The username is the Mastercard-generated domain name alias. The proxy response returns it in `additionalAccountAliases`, as the entry whose `aliasType` is `DomainName`; in the passive identity flow the same value appears as `aliases.domainName`.
</Info>

### Crypto Credential Lifecycle

#### Option A: Automatic via Compliance Status (Passive)

**How it works:**

When you update a user's status at your platform — for example when a user fails re-verification or is flagged for investigation — Borderless receives that update through your existing reporting mechanism and maps it to the corresponding Mastercard status. Your rejection reasons are passed through as the explanation.

**What to implement:**

Nothing. Continue using your existing status reporting flow.

#### Option B: Update via Proxy Endpoint (Active)

If you need direct control over credential status, call the proxy endpoint with the same payload as described for Originator VASPs:

Full endpoint documentation: [Update a Crypto Credential account](/api-reference/mastercard-crypto-credential/update-a-crypto-credential-account)

### Retrieving Crypto Credential

#### Option A: Receive Credential Data (Passive)

**How it works:**

Once enabled, the user payload sent to your platform includes a `cryptoCredential` object alongside the standard user data you already receive. No additional API calls are needed.

This is not turned on by default. Borderless enables it after you confirm your system accepts the new field — an unrecognised field can otherwise fail schema validation on your side.

**What to implement:**

* Update your user creation endpoint to accept the `cryptoCredential` field.
* If `status` is `Active`, consider a reduced review based on your internal compliance policy.

**Example payload from Borderless:**

```json theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "...": "your standard user fields",

  "cryptoCredential": {
    "aliases": { "email": "john@example.com", "domainName": null },
    "status": "Active",
    "country": "US",
    "assets": [
      { "asset": "USDC_ETHEREUM", "vasps": ["VASP_A"] }
    ]
  }
}
```

If no VASP in the Borderless network has verified the identity yet, `cryptoCredential` is `null`. Proceed with your standard KYC flow.

`aliases.domainName` is `null` unless your organization issued the credential itself, because only the issuing participant can act on it.

<Info>
  Not all participants choose to display assets and networks during onboarding to Crypto Credential, so not every user on the network has them associated with their username. If there are associated assets and networks they will be returned; if not, `assets` is empty.
</Info>

#### Option B: Query the Network (Active)

**How it works:**

Borderless sends user data to your system as it does today. When you want to check an alias against the Mastercard network, call the proxy endpoint yourself. This gives you full control over when and how you retrieve credential data.

**What to implement:**

* Call [`GET /mastercard/crypto-credential/alias-lookup`](/api-reference/mastercard-crypto-credential/look-up-a-crypto-credential-alias) with the user's alias.
* Use the status returned to make a compliance decision: reduced review, or full KYC.

```bash theme={null}
curl -X GET "https://sandbox-api.borderless.xyz/v1/mastercard/crypto-credential/alias-lookup?accountAlias=john@example.com" \
  -H "Authorization: Bearer {token}"
```

<Warning>
  A network lookup tells you that the alias has been verified by some participant. It is not a record held by Borderless, and it carries no information about which participant verified the user or when. Your compliance team decides what that is worth.
</Warning>

***

## Comparison: Passive vs Active

| **Flow**                                | **Passive (Automatic)**                                                                                                 | **Active (Manual)**                                                                                            |
| :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| **Scope** ⚠️                            | **The Borderless network** — bound to a Borderless identity, so verification counts per identity, not per email address | **The Mastercard network** — bound to an alias, with no Borderless record. Invisible to the identity endpoints |
| **Creating Credential**                 | Created automatically with the identity, or after the PFI approves the user                                             | Call `POST /mastercard/crypto-credential/accounts`                                                             |
| **Credential Lifecycle**                | Send `cryptoCredential` on `PATCH /identities/personal/{id}` (Originator), or report a status change (Beneficiary)      | Call `PUT /mastercard/crypto-credential/accounts`                                                              |
| **Credential Lookup**                   | `GET /identities/{id}` returns `cryptoCredential`                                                                       | Call `GET /mastercard/crypto-credential/alias-lookup` or `/accounts/search`                                    |
| **Crypto Address**                      | Planned for an upcoming release                                                                                         | Call `POST`, `PUT`, `DELETE` and `GET` on `/mastercard/crypto-credential/crypto-addresses`                     |
| **Retrieving Credential** (Beneficiary) | `cryptoCredential` included in the user payload                                                                         | Call `GET /mastercard/crypto-credential/alias-lookup`                                                          |
| **Integration effort**                  | No additional API calls needed                                                                                          | Requires implementing proxy endpoint calls                                                                     |

<Warning>
  **Scope is the one row that changes your architecture.** Everything else in this table is a choice about effort; that row is a choice about where the credential lives. Anything created actively exists only in Mastercard's ledger and will never appear on a Borderless identity — if you use both flows, reconciling the two views is on you.
</Warning>

***

## API Reference

All endpoints require a Bearer token. See [Authentication](/api-reference/authentication).

### Borderless API Endpoints

These standard Borderless endpoints participate in the Crypto Credential flow:

| **Method** | **Endpoint**                   | **Description**                                                               | **Docs**                                                              |
| :--------- | :----------------------------- | :---------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| POST       | `/v1/identities/personal`      | Create a personal identity — creates a Crypto Credential automatically        | [View docs](/api-reference/identities/create-a-new-personal-identity) |
| POST       | `/v1/identities/business`      | Create a business identity — creates a Crypto Credential automatically        | [View docs](/api-reference/identities/create-a-new-business-identity) |
| GET        | `/v1/identities/{id}`          | Get identity by ID — includes `cryptoCredential`                              | [View docs](/api-reference/identities/get-an-identity-by-id)          |
| PATCH      | `/v1/identities/personal/{id}` | Update a personal identity — accepts `cryptoCredential` for lifecycle changes | [View docs](/api-reference/identities/update-a-personal-identity)     |
| PATCH      | `/v1/identities/business/{id}` | Update a business identity — accepts `cryptoCredential` for lifecycle changes | [View docs](/api-reference/identities/update-a-business-identity)     |

### Configuration

| **Method** | **Endpoint**                     | **Description**                                                                                  | **Docs**                                                                                   |
| :--------- | :------------------------------- | :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
| PUT        | `/v1/organizations/integrations` | Provide Mastercard Crypto Credential keys (also available via Dashboard). Returns `202 Accepted` | [View docs](/api-reference/integrations-config/setup-integration-credentials-consolidated) |

### Proxy Endpoints

<Note>
  Proxy endpoints require proxy access to be enabled for your organization. Without it every call below returns `403 Forbidden` with `Mastercard Proxy access is not enabled for your organization`. Contact the Borderless team to enable it.
</Note>

| **Method** | **Endpoint**                                                          | **Description**                                | **Docs**                                                                                              |
| :--------- | :-------------------------------------------------------------------- | :--------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| POST       | `/v1/mastercard/crypto-credential/accounts`                           | Register an alias with Crypto Credential       | [View docs](/api-reference/mastercard-crypto-credential/create-a-crypto-credential-account)           |
| PUT        | `/v1/mastercard/crypto-credential/accounts`                           | Change an account's status                     | [View docs](/api-reference/mastercard-crypto-credential/update-a-crypto-credential-account)           |
| GET        | `/v1/mastercard/crypto-credential/accounts/search`                    | Read accounts registered under your ICA        | [View docs](/api-reference/mastercard-crypto-credential/search-for-a-crypto-credential-account)       |
| GET        | `/v1/mastercard/crypto-credential/alias-lookup`                       | Look up an alias across the Mastercard network | [View docs](/api-reference/mastercard-crypto-credential/look-up-a-crypto-credential-alias)            |
| POST       | `/v1/mastercard/crypto-credential/crypto-addresses`                   | Register a blockchain address                  | [View docs](/api-reference/mastercard-crypto-credential/register-a-blockchain-address)                |
| PUT        | `/v1/mastercard/crypto-credential/crypto-addresses/{cryptoAddressId}` | Update a registered address                    | [View docs](/api-reference/mastercard-crypto-credential/update-a-registered-blockchain-address)       |
| DELETE     | `/v1/mastercard/crypto-credential/crypto-addresses/{cryptoAddressId}` | Decommission an address                        | [View docs](/api-reference/mastercard-crypto-credential/decommission-a-registered-blockchain-address) |
| GET        | `/v1/mastercard/crypto-credential/crypto-addresses/{cryptoAddressId}` | Read a registered address                      | [View docs](/api-reference/mastercard-crypto-credential/get-a-registered-blockchain-address)          |

### Webhook

<Note>
  Forwarding Mastercard event notifications to your webhook endpoint is planned for an upcoming release.
</Note>

Mastercard sends event notifications to Borderless, which holds the single webhook registration for your ICA. Once forwarding ships, those events will be delivered through the [Borderless webhook mechanism](/docs/webhooks) you already use, with the Mastercard payload passed through unchanged for event types Borderless does not model itself.

***

## Frequently Asked Questions

**Do I need to register with Mastercard separately?**

Yes. Your organization must have an active contract with Mastercard and receive credential keys (ICA, Client ID and Encryption Key). You also generate your own RSA key pair for decrypting responses. You never communicate with Mastercard directly — Borderless handles all API calls on your behalf using your stored keys.

**What happens if an identity has no Crypto Credential?**

For Beneficiary VASPs: `cryptoCredential` is `null` in the user payload. Proceed with your standard KYC process. Once you approve the user, Borderless creates a Crypto Credential for them.

For Originator VASPs: a Crypto Credential is created automatically with the identity. If `cryptoCredential` is missing entirely, your organization is not set up — either it is not flagged as a Mastercard partner, or one of the required keys is absent. An alias already registered by another participant is a different case: `cryptoCredential` is still returned, just without `aliases.domainName`.

**Does `null` mean the user has no Crypto Credential at all?**

No. It means we hold no verification record for that identity. The same alias may be registered by a participant outside the Borderless network. Use `alias-lookup` to ask the network.

**Can Beneficiary VASPs auto-approve users based on a Crypto Credential?**

`status: "Active"` means the alias holder was verified by a participant in the network. A Crypto Credential indicates that a user has been verified by an eligible VASP and may be eligible for the requested activity — it does not eliminate the need for the receiving or sending VASP to meet all relevant regulatory and compliance obligations, including establishing that the person contacting you controls the alias. Your compliance team defines the policy.

**Why is `aliases.domainName` missing?**

Because the credential was issued by another participant — either a PFI you routed compliance to, or a VASP outside Borderless. Only the issuing participant can surface the username or act on the credential.

**Why does `aliases.email` differ from `identity.email`?**

The credential stays bound to the alias it was registered with. If the user later changes their email address on your platform, the credential does not follow. Other participants will continue to resolve the original alias.

**What is the difference between alias-lookup and accounts/search?**

`alias-lookup` queries the entire Mastercard network and returns status, country and supported assets. `accounts/search` is scoped to your own ICA and returns full account detail, including aliases and registered addresses.

**Can my organization be both an Originator and Beneficiary VASP?**

Yes. Some organizations act as both — onboarding their own users (Originator) while also receiving users from other VASPs through Borderless (Beneficiary). Implement the flows for both roles as needed.

**What is the sandbox base URL?**

`https://sandbox-api.borderless.xyz`. Use this for all integration testing. Contact Borderless for production credentials and base URL.

<Note>
  The Mastercard sandbox returns mock responses and validates only the length and data type of request parameters. It is suitable for verifying your integration wiring, not for exercising complete credential lifecycles.
</Note>

***

## Support

For questions or integration support, reach out to the Borderless team:

* **Email:** [support@borderless.xyz](mailto:support@borderless.xyz)
* **Slack:** your dedicated partner channel
* **API Docs:** [docs.borderless.xyz](https://docs.borderless.xyz)